Skip to content

Features

golergka edited this page Mar 16, 2016 · 10 revisions
Clone this wiki locally

Report Editor

Report Editor Screenshot
The Report Editor is a complex and powerful feature that allows you to analyze all captured traffic with custom JavaScript code.
Read the Report Editor Manual for more details.

Search

A major feature of HoneyProxy is the ability to filter requests based on different criteria. HoneyProxy has a rich set of modifiers to allow fine-grained search requests:

  • Regular Search: If you don't supply any modifiers, HoneyProxy will show all flows that contain the given string. This is case-insensitive.
  • Case Sensitive Search: If your search request starts with an equal sign ( =filter ), search is performed case-sensitive.
  • Inverse Search: If your search request starts with an exclamation mark ( !filter ), all requests that don't match the criteria are displayed.
  • Regular Expressions: If your search request starts with a tidle sign ( ~param=(foo|bar|[\d]+) ), your input is treated as a regular expression. You can combine this with the inverse modifier (!~). Please note that regular expressions are always case-sensitive.

Highlighting

Technically this is identical to searching (with a different treatment of the result). Head over the Search section for details!

Dump conversations into a directory structure

HoneyProxy can dump all response contents into a directory-like structure. For example if you request example.com/files/foo.zip, foo.zip will be placed in $dumpdir/example.com/files/foo.zip. However, there are some restrictions with the filesystem:

  • As file and folder names are limited to different lengths on different operating systems, HoneyProxy is going to cut off long directory and/or file names ([...] in the folder name or file name is a good indicator for this).
  • The content of a unique URL is not guaranteed to be identical when calling it twice. To handle this transparently, HoneyProxy creates a second file if the response contents don't match.
  • As example.com/foo/ can be both a resource and a directory, HoneyProxy appends [dir] to a directory if a resource with the same name exists. This might lead to the problem that example.com/foo/bar.zip and example.com/foo[dir]/baz.zip seem to be in the same directory.

Conclusion: Don't assume that the --dump-dir option creates an exact representation of your HTTP requests. If you keep that in mind, it's still a very powerful tool for visualization!

Examples:

honeyproxy.py --dump-dir ./dump/sites/
Dump all incoming response objects into ./dump/sites/. When HoneyProxy is started with no arguments, default.conf will be loaded and this is the default behaviour.

honeyproxy.py -r ./dump/infile --dump-dir ./dump/sites/
Load saved traffic from infile (-r) and output request contents to ./dump/sites/.

Save HTTP conversations to a file

You can easily save HTTP conversations using the -w flag. The cool thing is that this is a feature of mitmproxy we inherit, so you can use the saved conversations with mitmproxy, too.

Examples:

honeyproxy.py -w ./dump/outfile
Save all incoming traffic in outfile.

honeyproxy.py -r ./dump/infile -n
Load saved traffic from infile (-r) and don't start a proxy server (-n)

honeyproxy.py -r ./dump/infile --replace :~s:Bob:Alice -w ./dump/outfile
Load saved traffic from infile, perform replacements (replace Bob with Alice in every response) and write the modified traffic conversation to outfile. Replacements are documented below.

Multiuser Capability

Due to its client-server architecture, HoneyProxy is not restricted to a single GUI Session. You can open the HoneyProxy GUI on multiple machines and browse the same dump simultaneously. It also works in live mode, all client's get a notice of new flows.

Usage Instructions

When connection from a remote machine, make sure to open both the GUI and the WebSocket port (8081 and 8082 by default). Feel free to configure them using the corresponding command line flags.

The HoneyProxy GUI is protected from unauthorized access via Basic Auth. To access the GUI, you need valid credentials (HoneyProxy adds them by default when opening the browser). While the username is constant, the password is usually a 32 digit random string. It is displayed on the command line after HoneyProxy has been started. If you are working in a trusted environment, you can change this by using the --api-auth command line flag.

Basic Auth User: honey
Basic Auth Pass: displayed on the command line or specified by --api-auth

Programmatic Access with JavaScript / API

While HoneyProxy has inherited a great Python API from mitmproxy (docs), it also provides access to flows via JavaScript. This can be extremly powerful for developers who are interested in extending HoneyProxy or JavaScript hackers who want to run custom queries on a set of flows. For short, HoneyProxy stores all flows in a Backbone Collection (window.HoneyProxy.traffic). A flow contains a request object, a response object, an error object and its unique id. For easified access, we have ES5 proxy objects for both request and response directly as attributes of the Flow (e.g. HoneyProxy.traffic.get(0).request.host). They are stateless wrappers with ES5 getters for the original model attributes. Sounds complicated, but is really easy - let's go over to the examples:

Examples

HoneyProxy.traffic.get(0);
Gets the first flow. Pro tip: You can get the id of a flow by hovering over the small space left to the icon in the table.

HoneyProxy.traffic.get(0).request.host
Gets the hostname of the first flow.

HoneyProxy.traffic.groupBy(function(flow){ return flow.request.host});
Groups all flows by host and returns a host:flows dictionary.

HoneyProxy.traffic.filter( function(flow){ return flow.request.host == "example.com"});
Returns all flows that match the specified criteria.

HoneyProxy ♥ mitmproxy

HoneyProxy is build on top of the excellent mitmproxy. It provides us with a solid proxy base and a great API. The features below are inherited by HoneyProxy and are part of the mitmproxy code base. We show them here, because they are highly useful and also part of HoneyProxy. Credit goes to mitmproxy though :)

Anticache

If you want to access request content of a cached file, specify the --anticache command line flag. It removes all caching headers from HTTP requests. This is a feature of mitmproxy and documented in the mitmproxy docs.

Transparent Mode

This is an currently undocumented feature of the latest mitmproxy trunk code, but it's already in HoneyProxy! Just run HoneyProxy with the -T switch and add a proper iptables rule. This currently only works on Linux.

Replacements

This is a feature of mitmproxy and documented in the mitmproxy docs.

Setting up SSL interception

This is a feature of mitmproxy and documented in the mitmproxy docs. The default certificate directory for HoneyProxy is ~/mitmproxy/.

Programmatic Access with Python - mitmproxy Scripts

HoneyProxy has inherited a great Python API from mitmproxy (docs). You can find a lot of examples in the mitmproxy repo.

So much more...

If you find a command-line switch that is not documented here, head over to the mitmproxy website for details.

Something went wrong with that request. Please try again.