macOS Guide
Use cases and examples (macOS)
Worked examples for ProxyBridge on macOS: send a browser or desktop app through Burp Suite or mitmproxy, route curl through Tor, split traffic between proxies, block telemetry and QUIC, send everything except some apps, use it as a connection monitor, and run without a window.
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 also be written as a .pbprofile file and run with the command line.
In all of them the quickest check is the Connections tab: the program should show with the proxy at the end of the line, for example → HTTP 127.0.0.1:8080 (see Connections and logs).
1. A browser through Burp Suite or mitmproxy
Goal: inspect everything a browser sends, without changing the browser's own proxy settings (which some traffic ignores).
- Start Burp Suite (listener
127.0.0.1:8080) ormitmproxy(127.0.0.1:8080). - Proxy > Proxy Settings... > Add: Name
Burp, TypeHTTP, Host127.0.0.1, Port8080. Press Test and check that tests 1 to 3 pass. - Proxy > Proxy Rules... > Add Rule:
| Field | Value |
|---|---|
| Rule Name | Browser to Burp |
| Process / Bundle Identifier | *chrome*; firefox |
| Target hosts | * |
| Target ports | 80; 443 |
| Protocol | TCP |
| Action | Burp |
- Open a site. The Connections tab shows
Google Chrome Helper → example.com:443 → HTTP 127.0.0.1:8080and the request appears in Burp.
Notes:
- HTTPS is readable in Burp only if the browser trusts Burp's CA certificate (install it in the macOS Keychain, or in Firefox's own store). ProxyBridge only moves the connection; it never decrypts anything.
- Browsers send their traffic from helper processes, so the name in the log is not always the app's name. Use wildcards (
*chrome*) and check the log. For Safari, look for the name that appears (typicallycom.apple.WebKit.Networking). - Open pages again after you add the rule: connections that were open before the rule keep the old route.
- Turn off "Secure DNS" in the browser if you also want to use domain rules (see domain names need plain DNS).
2. A desktop app that has no proxy setting
Goal: see what an Electron app or any other program talks to.
- Start the program and open Connections. Find its name (for example
com.microsoft.VSCode.helper,Slack Helper,Spotify). - Add a rule with that name (a wildcard version such as
com.microsoft.VSCode*also catches the other helpers), Target hosts*, Target ports*, ProtocolBOTH(orTCP), Action your proxy. - Restart the program if it had already connected: only new connections are redirected.
Electron apps often use several processes with different names. If some traffic stays Direct, find the other 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 Mac.
ssh -D 1080 -N [email protected] # or run Tor, which listens on 127.0.0.1:9050
Add a SOCKS5 proxy 127.0.0.1:1080 (Tor: 9050), then a rule: Process curl, Hosts *, Ports *, Protocol TCP, Action the proxy.
curl https://example.com # now goes through the tunnel
SSH tunnels and Tor carry TCP only. With Let proxy resolve DNS on (the default), the proxy receives the host name when ProxyBridge saw the lookup, so the far end resolves it.
Why use ProxyBridge for this instead of curl --proxy? A tool's own proxy option works per command. The rule covers every curl that runs, including ones started by scripts and by 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 |
|---|---|
| Rule Name | Company network |
| Process / Bundle Identifier | * |
| Target hosts | 10.*.*.*; 172.16.0.0-172.31.255.255; *.corp.example.com |
| Target ports | * |
| Protocol | TCP |
| Action | the corporate proxy |
Because the process is * and the rule has a host limit, it is matched in list order like any specific rule (it is not a catch-all). Traffic to other destinations matches nothing and goes direct. There is no CIDR notation on macOS: write networks as wildcards or ranges.
Names such as *.corp.example.com work only for connections whose DNS lookup ProxyBridge saw. If an app connects to the IP address directly, add the IP ranges as well (as above).
5. Two proxies at the same time
Goal: browser traffic to Burp, everything from the terminal tools to Tor.
Add both proxies, then two rules:
| Rule | Process | Hosts | Ports | Protocol | Action |
|---|---|---|---|---|---|
| Browsers to Burp | *chrome*; firefox |
* |
80; 443 |
TCP |
Burp |
| Tools to Tor | curl; wget; git |
* |
* |
TCP |
Tor |
The two rules do not overlap, so their order does not matter. If they could overlap, put the more specific rule first (see How rules are matched).
6. Block a program from the network
Goal: stop an app from talking out at all, or stop it from reaching one destination.
All traffic of one app:
| Field | Value |
|---|---|
| Process / Bundle Identifier | com.example.updater* |
| Target hosts / ports | * / * |
| Protocol | BOTH |
| Action | BLOCK |
One destination, whichever program asks:
| Field | Value |
|---|---|
| Process / Bundle Identifier | * |
| Target hosts | telemetry.example.com; *.ads.example.net |
| Protocol | TCP |
| Action | BLOCK |
Order matters for the second one. A rule with process * and a host limit is matched in list order, so any earlier rule that also matches (for example a browser rule with hosts *) wins. Put the BLOCK rule above such rules, and remember it works only for names ProxyBridge learned from DNS (or give the IP ranges).
A blocked connection simply fails in the app. The Connections tab shows it with BLOCK at the end of the line.
7. Send everything through a proxy, except some programs
Goal: all traffic goes through the proxy, but a few apps (and the proxy tool itself) stay direct.
| Rule | Process | Hosts | Ports | Protocol | Action |
|---|---|---|---|---|---|
| Everything | * |
* |
* |
BOTH |
the proxy |
| Keep Burp direct | *burp*; java |
* |
* |
BOTH |
DIRECT |
| Keep Safari direct | *safari*; com.apple.WebKit.Networking |
* |
* |
BOTH |
DIRECT |
The first rule has the process * and no limits, so it is a catch-all: it is used only when nothing else matched. The two DIRECT rules name specific programs, so they win, wherever they are in the list.
Why the DIRECT rule for the proxy tool matters: Burp Suite (and mitmproxy) make their own connections to the internet. Without the exception, those connections would be redirected to Burp itself by the catch-all, in a loop. ProxyBridge exempts only its own traffic, not your proxy tool. Use the exact process name from the Connections tab.
UDP: a BOTH catch-all sends all UDP of all programs to the proxy too. Only do that with a SOCKS5 proxy that supports UDP (see example 9), otherwise use TCP.
8. Watch what your apps connect to, with no rules
Goal: just look.
With no rules at all (an empty profile), every connection goes direct and is still logged. Open the Connections tab, start the app, and read the destinations and process names. Use the search box to filter by app or host. This is a quick way to find the right names for rules, and to see what a program does in the background.
For UDP lines to appear without rules you need at least one SOCKS5 proxy in the profile (see Connections and logs).
9. UDP, QUIC and HTTP/3
Goal: send a program's UDP through a SOCKS5 proxy.
- Use a SOCKS5 proxy that supports UDP ASSOCIATE (press Test and look at test 4:
UDP is supported by this proxy). - Add a rule: Process the program, Protocol
UDP(orBOTH), Action the SOCKS5 proxy. Hosts and ports are ignored for UDP.
What to expect:
- All UDP of the matching program goes through the proxy: the rule cannot select by destination.
- Browsers use QUIC (HTTP/3) on UDP port 443. A SOCKS5 proxy that supports UDP ASSOCIATE does not automatically carry QUIC well: the proxy must relay raw UDP datagrams properly. If pages stall or fail after you route UDP, QUIC is the usual cause. Nexus Proxy is a SOCKS5 proxy built to test exactly this.
- An HTTP proxy cannot carry UDP. UDP rules that point to one go direct, with an error in the Activity Logs.
To make a browser stop using QUIC so that its traffic uses TCP (and your proxy sees it as ordinary HTTPS), block its UDP:
| Field | Value |
|---|---|
| Process / Bundle Identifier | *chrome* |
| Protocol | UDP |
| Action | BLOCK |
The browser falls back to HTTP/2 over TCP. This blocks all of that browser's UDP (including other things that use UDP, such as video calls in the browser), because UDP rules cannot narrow by port.
10. DNS through the proxy
Goal: the proxy resolves the names, so internal or geo-specific names work and the proxy's log shows real host names.
Leave Let proxy resolve DNS (send hostname) on (the default) for that proxy. ProxyBridge then hands the proxy the host name instead of an IP address whenever it saw the app's DNS lookup within the last five minutes.
Things to remember:
- The Mac still does its own lookup first. If the name does not resolve on your Mac at all, the app never connects and ProxyBridge never sees a connection.
- Apps that use encrypted DNS (DNS over HTTPS) are invisible to this. The proxy gets the IP.
- For a proxy that cannot resolve your names, turn the option off.
11. Interpreters: Python, Node.js, Java
A script is not a program name. Python code runs inside python3 (or Python), Node.js inside node, Java inside java. A rule for myscript.py never matches. Use the interpreter, and look at the Connections tab to see the exact name:
| Field | Value |
|---|---|
| Process / Bundle Identifier | python3*; Python* |
| Action | the proxy |
Every program that uses that interpreter is then included, so narrow it with Target hosts and Target ports when you can.
12. A profile per engagement
Goal: switch between Burp, Tor and Client X set-ups in one click.
Create one profile for each (Profile > New Profile...), add proxies and rules inside it, and switch with the Profile menu. Export each one (Profile > Export) and keep the files with your notes. Remove the password from a profile before sharing it. See Profiles.
13. Run without a window
Goal: start routing from the Terminal, or from a script.
proxybridge --profile Lab --verbose 2
Press Ctrl+C to stop. Pipe a profile from a file with cat lab.pbprofile | proxybridge --profile -. See Command line.
For a Mac that should route without a window after login, turn on Settings > Run at Startup and Close to Menu Bar in the profile you want. The app then starts hidden in the menu bar and routes at once.
14. Test how an app behaves when the proxy is broken
Goal: see how a program reacts when its proxy is down.
Route the program to a proxy, then stop the proxy (or set a rule to a proxy on a port where nothing listens). The program's connections fail. They do not fall back to direct: ProxyBridge writes SOCKS5 greeting ... failed or HTTP CONNECT ... failed messages in the Activity Logs and closes the connection. This is useful for checking how an app handles failures and timeouts. A proxy that accepts the connection but then goes quiet is cut after 20 seconds.
What ProxyBridge is not for
- A VPN. It does not encrypt or tunnel anything on its own. It hands connections to the proxy you choose.
- Hiding your DNS lookups. The Mac still does its own lookups.
- Decrypting HTTPS. It only redirects connections. Reading HTTPS needs a tool such as Burp Suite and a trusted CA certificate.
- Per-process traffic that macOS never delivers to it. If a program never appears in the Connections tab, ProxyBridge cannot route it.
More
- Use ProxyBridge with security tools: Burp Suite, mitmproxy and InterceptSuite set-ups.
- Troubleshooting and limits: when something does not work.
