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)
You may need to use
gem install binproxy
sudo, depending on your Ruby installation.
To build and install the gem package:
git clone https://github.com/nccgroup/BinProxy.git 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
Bug reports on installation issues are welcome!
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:
If you leave out the
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 \
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:
† Technically, any subclass of BinData::Base will work.
# return a single-line description of this record
# 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
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.)