BinProxy is a proxy for arbitrary TCP connections. You can define custom message formats using the BinData gem.
- Ruby 2.3 or later
- A C compiler, Ruby headers, etc., are needed to compile several dependencies.
- On Ubuntu,
sudo apt install build-essential ruby-devshould do it.
- If you've installed a custom Ruby (e.g. with RVM), you probably already have what you need.
- On Ubuntu,
--tlswithout an explicit cert/key.
- To build the UI, node.js and npm. (Not needed at runtime)
gem install binproxy
sudo, depending on your Ruby installation.
git clone https://github.com/nccgroup/BinProxy.git binproxy cd binproxy # Install ruby dependencies. # Depending on your setup, one or both of these may require sudo. gem install bundler && bundle # The UI is built with a webpack/babel toolchain: (cd ui && npm install) \ && rake build-ui # Confirm that everything works # run.sh sets up the environment and passes all args to binproxy ./run.sh --help
gem build binproxy.gemspec # Again, you may need sudo here gem install binproxy-1.0.0.gem
binproxywith no arguments.
- Browse to http://localhost:4567/
- Enter local and remote hostnames or IP addresses and ports, and click 'update'
- Point a client at the local service, and watch the packets flow.
Command Line Flags
--helpfor the complete list, but in short:
binproxy -c <class> [<local-host>] <local-port> <remote-host> <remote-port>
-cargument, a simple hex dump is shown.
If you leave out the local host, binproxy assumes localhost.
--http-proxyoptions, the remote host and port are determined dynamically, and should not be specified.
# Proxy from localhost:9000 -> example.com:9000 binproxy localhost 9000 example.com 9000 # Act as a SOCKS proxy on localhost:1080 # MITM and unwrap TLS on the proxied traffic, using a self-signed cert and key binproxy -S --tls 1080 # "Poor substitute for Burp" mode: # # HTTP proxy; MITM TLS w/ pre-generated cert; simple header parsing # Note: this will only work on HTTPS traffic, not plain HTTP! # If you're working with the source repo, you generate the certs with: # rake makecert[example.com] # And then import certs/ca-cert.pem into your browser or OS's trust store. binproxy -H --tls \ --tls-cert certs/example.com-cert.pem \ --tls-key certs/example.com-key.pem \ --class-name DumbHttp::Message \ localhost 8080
By default, the proxy uses the built-in RawMessage class, which just gives you a hexdump of each message (assuming 1:1 between messages and TCP packets)
You can view parsed protocol information by specifying a BinData::Record subclass† with the
--classcommand line argument.
You may also wish to define the following in your class:
def summary # return a single-line description of this record end # currently supported options are # - nil : use default display # - "anon" : for structs, show contents directly # - "hex" : for numbers, display as 0x1234ABCD # - "hexdump" : for strings, display like `hexdump -C` default_parameter display_as: "..." # TODO: document state stuff def self.initial_state end def current_state end def update_state end
By default, BinProxy relays all traffic to a static upstream host and port. It can also be configured to act as a SOCKS (v4 or v4a) or HTTP proxy with the
Note: Currently, the HTTP proxy only supports connections tunneled with the HTTP
CONNNECTverb; it cannot proxy raw HTTP
POST, etc., requests. In practice, this means that HTTPS traffic will work, but plain HTTP traffic will not unless the client supports a flag to force tunneling, like
TLS / SSL
--tlsflag to unwrap TLS encryption before processing messages. By default, BinProxy will generate a self-signed certificate. You can sepecify PEM files containing a certificate and key with
--tls-key. (If you've cloned the source repo, use
rake makecert[example.com]to generate a static CA and a certificate with the appropriate hostname.)