Home/Docs/macOS Guide/How ProxyBridge works on macOS

macOS Guide

How ProxyBridge works on macOS

How the macOS version redirects connections with a Network Extension: what the app and the system extension each do, how TCP, UDP and DNS are handled, how rules are matched, what is stored where, and the security model.

How ProxyBridge works on macOS

This page explains what happens between a program opening a connection and the data reaching a proxy. You do not need it to use ProxyBridge, but it explains the behaviour you see in the log and the limits.

The idea in one picture

   a program opens a connection (TCP or UDP)
                    |
                    v
   macOS gives it to the ProxyBridge system extension
   (NETransparentProxyProvider: every outbound flow)
                    |
        +-----------+-----------+
        | match your rules      |   bundle id / process name, host, port, protocol
        +-----------+-----------+
                    |
     +--------------+------------------+----------------+
     |              |                  |                |
   DIRECT       no rule             BLOCK             a proxy
     |              |                  |                |
 handed back    handed back      connection        the extension opens its own
 to macOS       to macOS         closed            connection to the proxy,
 (goes out      (goes out                          does the SOCKS5 / HTTP
 normally)      normally)                          handshake and relays the data

The program never knows. It opens a normal socket and sees a normal connection.

The app and the extension

ProxyBridge for macOS has two parts that run as two separate processes:

Part What it is What it does
The app (ProxyBridge.app) A sandboxed SwiftUI app, running as you The window, the menus, your proxies, rules and profiles. It saves them in its preferences, installs the extension, and sends the proxies and rules to the extension. It reads logs back from it
The system extension A Network Extension that macOS runs as root, in the background Receives every outbound connection, decides, relays. It hosts two providers: the transparent proxy and the DNS proxy

Why a system extension: macOS lets a Network Extension see and redirect the traffic of other programs, and it only allows that for software that Apple has signed and that you have approved. That is why the first run asks for your approval, and why ProxyBridge works with all programs, whatever their own proxy settings are.

The app and the extension talk through provider messages (a private channel macOS provides between an app and its extension):

Message From the app, meaning
setProxyConfigs Here is the list of proxies (type, host, port, credentials, the send-hostname option)
setRules Here is the whole rule list. It replaces the old list in one step, so a connection that arrives meanwhile is never matched against a half-built list
clearRules, clearConfig Remove the rules, remove the proxies (sent when you quit)
setTrafficLogging Record connection lines, or not
getLogs Give me up to 100 new log lines (asked once a second while the window is visible)

The extension keeps the proxies and rules in memory only. It stores nothing on disk. When it is stopped, or you quit the app, it forgets them.

The command line is the same app executable. It sends the same messages, from a terminal instead of a window.

What happens to a TCP connection

  1. macOS offers the new connection to the extension (handleNewFlow). The connection carries the destination IP and port, the program's bundle identifier and its process (from which ProxyBridge reads the executable name).
  2. If the program is ProxyBridge itself (the app or the extension), the connection is handed back to macOS untouched, so ProxyBridge never loops back into itself.
  3. ProxyBridge looks up which host names the destination IP was recently resolved from (see DNS).
  4. It goes through the rules (see How rules are matched) and logs one line.
  5. Depending on the result:
    • DIRECT or no rule: the extension says "not mine", and macOS handles the connection normally.
    • BLOCK: the extension closes the connection at once.
    • A proxy: the extension opens its own TCP connection to the proxy and runs a handshake.
  6. SOCKS5 handshake: greeting (offering "no authentication", and "user name and password" if you set both), optional authentication, then CONNECT to the destination. The destination is written as a host name when the proxy's send hostname option is on and a recent DNS answer names this IP, otherwise as the IP. The reply is read to its exact length, so the first bytes the real server sends are not lost.
  7. HTTP handshake: CONNECT host:port HTTP/1.1 (with a Proxy-Authorization: Basic header if you set a user name and password), then the extension reads the reply up to the end of its headers. A 2xx status opens the tunnel, anything else closes the connection and writes the status line in the Activity Logs. Data the proxy sent right behind its reply is passed to the program first.
  8. The extension then relays in both directions until either side closes.
  9. A handshake that has not finished after 20 seconds is cancelled and the connection closed.

When the program finishes sending (a FIN), ProxyBridge sends a FIN to the proxy and, after 3 seconds to let it flush, closes the connection. macOS closes a flow in both directions when its client has finished writing, so a program that half-closes cannot receive a reply. Normal web traffic is not affected.

A connection that is sent to a proxy and fails (the proxy is down, rejects, or is silent) is closed, not sent direct.

What happens to UDP

macOS gives ProxyBridge a UDP flow when a program opens a UDP socket. It does not say where the datagrams will go, so:

  • The rule is chosen from the program and the protocol only (host and port limits cannot be used).
  • DIRECT or no rule: the flow is handed back to macOS.
  • BLOCK: the flow is closed.
  • A SOCKS5 proxy: ProxyBridge sets up a SOCKS5 UDP association for that flow: a TCP control connection (which keeps the association alive) and a UDP channel to the relay the proxy names. Every datagram the program sends gets a SOCKS5 UDP header with its real destination and goes to the relay. Datagrams that come back are unwrapped and handed to the program, from the address they came from. Fragmented UDP datagrams are dropped.
  • An HTTP proxy cannot carry UDP: the flow goes direct, and an error line tells you.
  • A flow that has been idle for 120 seconds is torn down: UDP has no close signal.

A proxy that does not support UDP ASSOCIATE answers command not supported. The proxy test shows this in its step 4.

DNS and domain rules

A TCP connection reaches ProxyBridge with only an IP address; the program has already looked the name up. To support domain rules and the send hostname option, ProxyBridge runs a DNS proxy provider in the same extension:

  • macOS hands the Mac's DNS queries over UDP to the DNS proxy. It forwards each one unchanged to the resolver macOS chose (the one that would have been used anyway) and passes the answer back.
  • It reads the A and AAAA records of each answer and remembers IP address → host name (up to 1024 addresses, 8 names each, newest last). The map is in memory only.
  • The transparent proxy uses it in two places: domain entries in rules (the rule matches when any known name of the destination IP matches), and the send hostname option (the newest name seen within 5 minutes, if it is safe to put in a request).

What the DNS proxy does not do: it does not change your answers, it does not filter or block names, and it does not see DNS over TCP, HTTPS or TLS (those lookups bypass it, so their names are unknown). See Domain names need plain DNS.

The DNS proxy is switched on when ProxyBridge starts, unless the profile has Enable DNS turned off. With it off, ProxyBridge switches its own entry off and never turns it on. The entry stays registered in macOS (visible in System Settings) between runs, on or off.

Logs

The extension keeps its newest 500 log lines in a ring buffer: connection lines (what was decided for each connection) and activity lines (errors and information). The app takes up to 100 per second while its window is visible. See Connections and logs.

Where things are stored

What Where
The app /Applications/ProxyBridge.app
The system extension Inside the app, and activated by macOS (listed by systemextensionsctl list)
The proxybridge command /usr/local/bin/proxybridge, a small launcher that starts the app's executable with --cli
Profiles, proxies, rules, settings The app's sandbox container, see Profiles
What the extension remembers Memory only

Security model

  • The app is sandboxed: it can only read and write its own container and the files you choose in an open or save dialog (this is why the command line cannot read a file path).
  • The extension runs with the rights macOS gives a Network Extension. ProxyBridge's extension holds the full set of network-extension entitlements of its signing profile (a known and accepted limit, see SECURITY.md).
  • Credentials: stored in clear text in the app's preferences and in exported profiles (also an accepted risk). They are sent to the extension over the provider channel, held in memory, and removed with clearConfig when you quit. They go only to the proxy they belong to.
  • Names from DNS are checked before they are written into a proxy request: only letters, digits, ., - and _ are accepted, so a hostile DNS answer cannot add lines to an HTTP CONNECT request.
  • No browsing history on disk: the IP-to-name map is memory only, and the extension removes the file an older version wrote.
  • Update check: an HTTPS request to download.interceptsuite.com. The installer is downloaded over HTTPS and opened with the macOS Installer, which verifies its signature.
  • The command line checks a profile completely before it sends it to the extension, limits its size (4 MB, 100 proxies, 5000 rules), and prints text from the network with control characters removed.

Resource use

  • The matching of a connection is cheap: each rule is parsed once when it is loaded (split lists, lower-cased text, numbers) instead of once per connection.
  • Process names are cached by process id and its version number, so a reused id never shows the previous program's name.
  • The log, the DNS map and the per-flow caches all have fixed limits, so they cannot grow without end.
  • While the main window is hidden, the app does not read the log.

Differences from Windows and Linux

macOS Windows Linux
Mechanism Network Extension (system extension) WinDivert driver and a service eBPF programs and a root service
A program is identified by Bundle identifier or process name Process name or path Program name or path
Network entries in rules IP, wildcard, range, domain (no CIDR) IP, wildcard, CIDR, domain IP, wildcard, range, CIDR, domain
UDP rules Match the app only (macOS gives no destination) See the Windows guide See the Linux guide
Start and pause The running app routes; quit to stop Pause and tray Pause, start and stop the engine
Profile file macOS layout (not shared) Windows and Linux share one layout Windows and Linux share one layout

Why this design

macOS does not let ordinary apps intercept other programs' traffic. A Network Extension is the supported way, and it keeps the user in control: nothing is redirected until you approve the extension, and you can switch it off in System Settings at any time. The app/extension split follows from that. The extension is small, has no window, and does the work; the app holds the configuration and shows what is going on.