See the releases page for binary releases for Windows and Linux:
| Platform | Asset |
|---|---|
| Windows (x64) | proxide-<version>-x86_64-pc-windows-msvc.zip |
| Linux (x86-64) | proxide-<version>-x86_64-unknown-linux-gnu.tar.gz |
Each asset has a matching .sha256 checksum file.
The Windows binary requires the Microsoft Visual C++ Redistributable (x64), which is already present on most development machines.
Proxide can also be installed directly from crates.io with:
cargo install proxide
In addition to the instructions below, Proxide provides (hopefully)
comprehensive help through the --help command line argument.
There are few different ways to use Proxide to monitor client traffic. The big choices are in how Proxide intercepts the client traffic and whether the user wants to monitor the traffic in real time or record it for later analysis.
The examples below are written considering the case where the user wants to
monitor traffic in real time using the Proxide UI. Replacing monitor with
capture -f output_file allows the user to capture the traffic directly into a
file for later analysis.
The most straight forward way to run Proxide is to use it to have the clients connect directly to Proxide and have Proxide redirect these connections to a remote server.
proxide monitor -l 5555 -t example.com:8080
Proxide will automatically rewrite outgoing authority information with that
of the target server, making the redirection transparent on the HTTP/2 protocol
level. However if the client includes the server address in the actual payload
or if the server includes its address in the responses, these are not altered,
making the presence of the proxy visible to the parties and possibly breaking
the communication.
In case where it's important that the client is able to use the real server address, but still route the traffic through Proxide, Proxide can be used as a CONNECT proxy. This happens automatically if a target server is not specified.
proxide monitor -l 5555
When acting as a CONNECT proxy, the client needs to be configured to route its
traffic through the proxy. The exact way in which this configuration is made
depends on the client. Many clients support http_proxy environment variable
for this.
http_proxy=http://localhost:5555 ./grpc_application
Previously captured files (and exported sessions) can be viewed with proxide view.
proxide view capture.bin
When Proxide is used to analyze gRPC traffic, it helps to be able to decode the
messages. Proxide requires the service and message definitions to be able to do
this. These definitions can be given to Proxide with the --grpc option. The
option works with both the monitor and view commands.
proxide view capture.bin --grpc /project/src/*.proto
Note that trusting CA certificates may compromise the system security. Please take your time to understand the full implications of this.
Intercepting and decoding TLS traffic requires Proxide to perform a man-in-the-middle attack on the client. This is something TLS is designed to protect against so the user needs to perform some setup to allow this.
First, Proxide needs a CA certificate. This certificate is used for
generating server certificates served to the client. The server certificates
are generated on the fly as Proxide intercepts client connections, but all of
them are signed by the CA certificate. The easiest way to generate such CA
certificate is through the config ca command.
proxide config ca --create
This command creates a proxide_ca.crt and proxide_ca.key pair. Proxide
uses them when monitoring or capturing traffic, and refuses to start if they
are missing. Use --ca-cert and --ca-key to point to CA files elsewhere,
or --no-ca to run without TLS interception.
Clients must send the server name (SNI) in the TLS handshake. Proxide uses it to generate the server certificate. Connections without SNI are dropped.
If connections fail, run Proxide with --log proxide.log and check the log
for the reason.
The second obstacle is ensuring the client won't reject the server certificates Proxide creates. This can be done by having the client ignore certificate issues or specifying the Proxide CA certificate as a trusted root CA certificate for the client.
The exact details on how this is done depend on the client and platform. For
example on Windows many clients use the Windows certificate store. Proxide is
able to add the root CA to this store with the --trust option. If a
certificate is aded to the platform certificate store, it is recommended to
remove it from that store when the debugging session is over. This can be done
with the --revoke option.
proxide config ca --trust
(This can be combined with the --create flag when creating the certificate in
the first place.)
Proxide is currently under development
The basic decoding works, but there are still few "production quality" features missing.
- Better TUI tooling.
- Search/highlight support.
- Switch between different encoders manually (Raw, Headers, gRPC).
- Support streaming JSON/Protobuf/etc. output for graphical UI integration.
- There's some support for this used in integration tests.
- Support for acquiring stacktraces from local requests with thread-id headers.
- Support HTTP/1.x upgrades
- HTTP/1.x support
Releases are built by the Release workflow.
- Update
versioninCargo.tomland commit it tomaster. Keep theversionline near the top of the file, as the workflow reads it from there. - Optional: do a test run by pushing to a
release-test-X.Y.Zbranch:This builds the binaries into a draft release taggedgit push origin master:release-test-0.2.4test-0.2.4. Nothing is published to GitHub or crates.io. Delete the draft release and the branch when done. - Push a tag matching the version:
The workflow checks that the tag matches
git tag 0.2.4 git push origin 0.2.4Cargo.tomland builds the Linux and Windows archives with their.sha256files. It then publishes the GitHub release and runscargo publish.
Publishing to crates.io needs a crates.io API token in the crates_io
repository secret.