Home/Docs/Linux Guide/Use cases and examples (Linux)

Linux Guide

Use cases and examples (Linux)

Worked examples for ProxyBridge on Linux: send a browser or desktop app through Burp Suite or mitmproxy, route curl through Tor, split traffic between proxies, block telemetry, test QUIC and HTTP/3, run in CI or at boot.

Use cases and examples

Each example says what you want, what to set up, and how to see that it works. Fields are written the way they appear in the rule editor. Every example can be built in the window or written in a .pbprofile file and run with the command line.

In all of them, the quickest check is the Connections tab: your program should appear with via <your proxy> (see Connections and logs).

1. A browser through Burp Suite or mitmproxy

Goal: inspect everything Firefox sends, without changing Firefox's own proxy settings (which Firefox may also ignore for some traffic).

  1. Start Burp Suite (listener 127.0.0.1:8080) or mitmproxy (127.0.0.1:8080).
  2. Proxy > Proxy Settings... > Add: Name Burp, Type HTTP, Host 127.0.0.1, Port 8080.
  3. Proxy > Proxy Rules... > Add:
Field Value
Name Firefox to Burp
Process Name firefox
Target Host *
Target Port 80;443
Protocol TCP
Action Burp
  1. Open a site in Firefox. The Connections tab shows firefox (PID:...) -> ...:443 via HTTP 127.0.0.1:8080, and the request shows up in Burp.

Notes:

  • HTTPS is intercepted only if the tool's CA certificate is trusted by the application (import Burp's CA into Firefox). ProxyBridge only moves the connection; it does not decrypt anything.
  • Use chromium;google-chrome;firefox to cover several browsers in one rule. Snap and Flatpak browsers may run under a different program name (check the Connections tab for the real name).
  • A rule for * as the process would also catch the proxy tool itself; ProxyBridge exempts a program that listens on a configured proxy address, so this is safe, but naming the browsers is clearer.

2. A desktop app that has no proxy setting

Goal: see what an Electron app, a game launcher or any other program talks to.

  1. Start the program, open Connections and find its name (for example slack, discord, Steam). Names are case-sensitive.
  2. Add a rule with that Process Name, Target Host *, Port *, Protocol BOTH (or TCP), Action your proxy.
  3. Restart the program if it opened its connections before the rule existed: only new connections are redirected.

Electron and helper-process programs often make connections from child processes with other names (slack plus slack --type=utility, both showing as slack, or helpers such as chrome_crashpad_handler). If some traffic stays direct, find the helper's name in the log and add it to the same rule with ;.

3. A command-line tool through Tor or an SSH tunnel

Goal: send curl through a SOCKS5 proxy on the same machine.

ssh -D 1080 -N [email protected]      # or: tor, which listens on 127.0.0.1:9050

Add a SOCKS5 proxy 127.0.0.1:1080 (Tor: 9050), then a rule: Process Name curl, Target Host *, Port *, Protocol TCP, Action the proxy.

curl https://example.com                    # now goes through the tunnel

SSH tunnels and Tor carry TCP only. With DNS via proxy ticked (the default) the proxy receives the name, so the lookup happens on the far end.

Why use ProxyBridge for this instead of curl --proxy? A tool's own proxy option is per command; the rule covers every curl that runs, including ones started by scripts and other programs.

4. Route by destination, not by program

Goal: everything that talks to the company network uses the corporate proxy; everything else stays direct.

Field Value
Name Company network
Process Name *
Target Host 10.0.0.0/8;172.16.0.0/12;*.corp.example.com
Target Port *
Protocol BOTH
Action Corporate SOCKS5

Domain entries such as *.corp.example.com work when the program looks the name up with ordinary DNS (not DNS over HTTPS) and it matches by the address the answer contained. See Proxy rules. Anything that does not match is untouched.

5. Two proxies at the same time

Goal: browsers through Burp, a command-line client through a different proxy, and the rest direct.

Rules, in this order:

# Process Name Target Port Action
1 firefox;chromium * 80;443 Burp (HTTP)
2 curl;wget;git * * Tor (SOCKS5)

Rules are checked from the top, and the first one that matches decides, so put narrow rules above broad ones. A broad rule above a narrow one hides the narrow one; see rule order.

6. Block a program from the network

Goal: stop an application from phoning home.

  1. Run the program for a moment and read its destinations in Connections (or just know its process name).
  2. Add a rule: Process Name telemetry-agent, Target Host *, Port *, Protocol BOTH, Action Block.

Its connections now fail at once with a "permission denied" style error, and each attempt is logged as via BLOCK. Block only one site by setting Target Host to the address (198.51.100.23) or, if the program resolves it with normal DNS, to the domain.

ProxyBridge is a routing tool, not a firewall. When it stops, everything goes direct, including what you blocked. Use a real firewall when enforcement matters. See How it works.

7. Keep one program out of a broad rule

Goal: proxy everything on the machine, except the package manager.

# Process Name Target Action
1 apt;apt-get;dpkg * Direct
2 * * Burp

The first rule matches first for apt, and stops there. Everything else falls to rule 2.

8. UDP, QUIC and HTTP/3

Goal: see a program's UDP traffic (DNS, QUIC, games) in an intercepting or testing proxy.

  1. You need a SOCKS5 proxy that supports UDP ASSOCIATE. HTTP proxies, SSH tunnels and most SOCKS5 servers cannot carry UDP. Nexus Proxy is made for this test.
  2. In Proxy Settings... select the proxy and run Start Test. Step 5 must say OK: UDP ASSOCIATE accepted.
  3. Add a rule: Process Name curl (or your app), Target Host *, Port 443, Protocol UDP (or BOTH), Action the proxy.
  4. Try it:
curl --http3-only https://example.com/

The Connections tab shows the flow with (UDP) at the end, and Live Connections shows its Sent and Received bytes growing. If curl on your system has no HTTP/3 support, curl -V will not list HTTP3; use a browser with QUIC enabled instead.

Things to remember:

  • A rule for TCP only leaves QUIC alone. Browsers try QUIC first and fall back to TCP, so for browser traffic you often want a separate UDP 443 rule, or a Block rule on UDP 443 so the browser falls back to TCP and your TCP rule catches everything.
  • Applications that keep one UDP socket for many destinations work too; each destination becomes its own flow.
  • UDP through an HTTP proxy cannot work. See UDP, QUIC and HTTP/3.

9. DNS through the proxy

Goal: the lookups of a program go through the proxy too, so the local resolver does not see them.

DNS is ordinary traffic on port 53, so a rule for the program with Port * and Protocol BOTH already includes its lookups. The proxy has to support UDP for that (SOCKS5 with UDP ASSOCIATE), because most lookups are UDP. If you want the lookups to stay local, add a rule above it for the same program with Port 53 and Action Direct. A profile can also switch the whole thing off with "DnsViaProxy": false.

A program that uses DNS over HTTPS bypasses all this, because its lookups look like ordinary HTTPS to a web server.

Separately, each proxy's DNS via proxy option decides whether the proxy is given the name of the server (so the proxy resolves it) or the address your program already looked up. See Proxy servers.

10. Interpreters: Python, Node, Java

Scripts run under the interpreter, so the process name is python3, node or java, not the script name. A rule for python3 therefore proxies every Python program. To proxy one script only, narrow the rule by destination (Target Host and Port) instead. Versioned names such as python3.12 are separate from python3; list both: python3; python3.12. A pattern with a / compares the full path of the program, which tells apart two interpreters with the same file name (a virtual environment's python3).

11. A profile per engagement

Goal: keep a separate setup for each client.

  • Profile > New Profile... → client-a, add its proxy and rules.
  • Profile > Duplicate Profile... → client-b, then change what differs.
  • Profile > Switch Profile swaps the whole setup at once; connections that are already open keep their old route.
  • Profile > Export Profile... to put the profile with the engagement's notes. Remove passwords first.

12. Run without a window

Goal: the same rules on a server, in CI or at boot.

sudo ProxyBridge --profile client-a --verbose 2        # in a terminal

or switch on Settings > Start at Boot: the ProxyBridge service then applies your active profile when the machine starts and keeps routing with no window and no login. Prepare the profile in the window once (or copy a .pbprofile into /etc/proxybridge/profiles/). See Command line and Settings.

13. Test how an app behaves when the proxy is broken

Add a rule to a proxy that is not running, or one that refuses logins, and watch the application. A connection whose proxy handshake fails is closed, never sent direct, so the application sees a failed connection, and the Activity Logs tab says why (connect to ... failed: Connection refused, authentication failed). Useful for checking error handling, retries and timeouts.

What ProxyBridge is not for

It routes the connections of programs on this computer to a proxy that you choose. It does not hide your identity, make traffic anonymous or encrypt anything by itself; those depend on the proxy you point it at. Use it only on systems and traffic you are allowed to test.

More