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

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).

  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. Press Test and check that tests 1 to 3 pass.
  3. 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
  1. Open a site. The Connections tab shows Google Chrome Helper → example.com:443 → HTTP 127.0.0.1:8080 and 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 (typically com.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.

  1. Start the program and open Connections. Find its name (for example com.microsoft.VSCode.helper, Slack Helper, Spotify).
  2. Add a rule with that name (a wildcard version such as com.microsoft.VSCode* also catches the other helpers), Target hosts *, Target ports *, Protocol BOTH (or TCP), Action your proxy.
  3. 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.

  1. Use a SOCKS5 proxy that supports UDP ASSOCIATE (press Test and look at test 4: UDP is supported by this proxy).
  2. Add a rule: Process the program, Protocol UDP (or BOTH), 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