Home/Docs/macOS Guide/Proxy rules (macOS)

macOS Guide

Proxy rules (macOS)

Every field of a ProxyBridge rule on macOS: bundle identifiers and process names, hosts and domains, ports, protocol and action. How rules are matched, why UDP rules match on the app only, how wildcard rules behave, and worked examples.

Proxy rules on macOS

A rule says: when this app connects to these hosts and ports over this protocol, do this. Rules decide which traffic is sent through a proxy, left alone, or blocked. Open them with Proxy > Proxy Rules... (⌘R).

The Proxy Rules window listing ten rules with their actions

The rules window

Part What it does
Add Rule Create a new rule
Select All / Deselect All Tick or untick every rule
Export Save the ticked rules to a JSON file (see Export and import rules). Greyed out until a rule is ticked
Import Add the rules from a JSON file
Check box at the start of a row Select the rule for Export
On switch Turn a rule on or off without deleting it
Pencil and trash icons Edit or delete the rule. Delete happens at once, without a question
SR The rule's position in the list
Name, Bundle ID, Target Hosts, Target Ports, Protocol, Action The rule's fields. An empty field shows as Any. The action shows the proxy's name, in green for a proxy, blue for DIRECT, red for BLOCK

A rule change applies to connections opened afterwards. Connections that are already open keep the route they started with: restart the program, or wait for it to open a new connection.

The window is part of the profile that is active. Switch profiles and the list changes with it.

Add or edit a rule

Click Add Rule (or the pencil on a row).

The Add Rule window with a rule for Chrome helpers on ports 80 and 443

Field Meaning Starts as
Rule Name Your label. Optional. Shown in the Name column and stored in the profile empty
Process / Bundle Identifier Which apps the rule is for *
Target hosts Which destinations: IP addresses, ranges and domain names, separated by ; *
Target ports Which destination ports *
Protocol TCP, UDP or BOTH TCP
Action DIRECT, BLOCK, or one of your proxies your first proxy, or DIRECT if there is none

A rule matches only when all of the process, host, port and protocol match.

The editor does not validate what you type. A misspelled entry is not rejected: it simply never matches (for example 80- or ten.0.0.1). After saving, open the Connections tab and check that the traffic you expect is routed the way you intended.

Process names and bundle identifiers

The first field holds one or more patterns. ProxyBridge compares each pattern with two names of the program that opens the connection:

  • its bundle identifier (the code-signing identifier), for example com.apple.Safari or org.mozilla.firefox;
  • its process name, the file name of the executable, for example curl, firefox or Google Chrome Helper.

If either one matches, the program matches.

What you type Matches
* (or empty) Every program
curl A program whose process name or bundle identifier is curl
com.google.Chrome That exact bundle identifier
firefox; curl; wget Any of them. Separate entries with ; (a comma works too). Empty entries are ignored
*chrome* Wildcards: * stands for any text, any number of times. *chrome*, com.google.* and py* all work

How the match works:

  • Matching is not case-sensitive: Firefox, firefox and FIREFOX are the same.
  • * is the only wildcard. ? is not special.
  • A pattern must match the whole name. chrome does not match Google Chrome Helper, but *chrome* does.
  • Paths do not work. A pattern that contains a / is compared with the bundle identifier or process name, neither of which ever contains one, so it never matches. Use the name.
  • A rule can match by bundle identifier or name, so you can write whichever is easier to find.

Finding the right name

Open the Connections tab, start the program, and read the green name in each line. That is the process name when ProxyBridge could find it, otherwise the bundle identifier. Use that text (or a wildcard version of it) in the rule. This matters more on macOS than elsewhere, because one app often makes its connections from helper processes:

App What you usually see in Connections
Google Chrome, Chromium-based browsers A helper process such as Google Chrome Helper or Google Chrome Helper (...), not the main com.google.Chrome process. A rule for exactly com.google.Chrome can miss it. Use *chrome*
Firefox firefox (bundle identifier org.mozilla.firefox)
Safari Typically com.apple.WebKit.Networking, not Safari itself. Check the Connections tab
Visual Studio Code and other Electron apps Helper names such as com.microsoft.VSCode.helper. Use a wildcard like com.microsoft.VSCode*
Terminal tools The tool's name: curl, wget, git, ssh
Python, Node.js, Java scripts The interpreter: python3 or Python, node, java. A rule for the script's file name never matches

Rule of thumb. If a program's traffic stays Direct after you added a rule, look at the exact name in the Connections log, and widen the pattern with *.

Target hosts

Target hosts limits the rule to certain destinations. Leave it as * for any destination. IP addresses and domain names go in the same field, separated by ; (a comma is not a separator here):

10.*.*.*; 192.168.1.1-192.168.1.50; github.com; *.corp.example.com
Kind Example Notes
Any * or empty Every destination
Single IPv4 192.168.1.1
IPv4 with wildcards 192.168.1.*, 10.*.*.* Each of the four numbers is either a value or *. All four parts are required, so 10.* does not work. There is no 10.1-5.*.7 style and no CIDR (/24) notation
IP range 10.0.0.1-10.0.0.254, fe80::1-fe80::ff Inclusive. Both ends must be addresses of the same kind (both IPv4 or both IPv6). Works for IPv4 and IPv6
Single IPv6 ::1, 2001:db8::1 Compared as numbers, so ::1 equals 0:0:0:0:0:0:0:1
IPv6 prefix 2001:db8:* The leading groups, then *. Written without ::
Domain github.com That exact name
Domain with wildcards *.github.com, *google*, api*.example.org * stands for any text

Things to know:

  • *.github.com also matches github.com itself. (The Linux app is stricter; on macOS the apex is covered.)
  • Domain names are compared in lower case.
  • To write a CIDR network, use a range or wildcards instead: 10.0.0.0/8 is 10.*.*.*, 192.168.0.0/16 is 192.168.*.*, and 172.16.0.0/12 is 172.16.0.0-172.31.255.255.
  • A domain with a hyphen (my-site.com) works: ProxyBridge first tries the entry as an IP range, and when that does not fit, uses it as a name.
  • Host and port limits apply to TCP only. See UDP rules.

Domain names need plain DNS

Host names also need Enable DNS to be on in the Proxy menu (it is on by default). With it off, a host name never matches and IP addresses still do. The rule editor shows a note about this.

The connection that reaches ProxyBridge carries only an IP address, because the app has already looked the name up. So ProxyBridge keeps a small list that says which names resolved to which IP address. It fills the list from the Mac's own DNS answers, which it sees through its DNS proxy. This has consequences:

  • The lookup must have gone through the ordinary system DNS over UDP. Apps that use DNS over HTTPS or DNS over TLS (many browsers have a "Secure DNS" setting, and some VPNs and resolvers use encrypted DNS) hide their lookups from ProxyBridge. Their domain rules do not match. Turn encrypted DNS off for those apps, or match on IP addresses instead.
  • The lookup must have happened after ProxyBridge started. The list is empty at start and is kept in memory only. An address an app resolved earlier, or one it connects to repeatedly from a cache, may have no known name until the app looks it up again.
  • Apps that take an address from a config file, or have it built in, never look anything up. Use an IP rule for them.
  • If one IP address has several names (common for CDNs), the rule matches when any of the known names matches. ProxyBridge keeps up to 8 names per address and up to 1024 addresses; the oldest are dropped.
  • If a domain entry stops matching while an IP entry in the same rule still does, a missing DNS lookup is the first thing to suspect.

Target ports

You type Matches
* (or empty) Every port
443 One port
80; 443; 8080 Several ports (, also works as separator)
8000-9000 A range (inclusive)
80; 443; 8000-9000 Ports and ranges together

An entry that is not a number or a range (http, 80-, 9000-8000) is ignored. If no entry in the field is valid, the rule matches no port at all.

Protocol

Choice Matches
TCP TCP connections only (web, most APIs, databases, SSH)
UDP UDP only (DNS, QUIC/HTTP/3, games, voice)
BOTH Either

UDP only works through a SOCKS5 proxy, and not every SOCKS5 proxy supports it. An HTTP proxy cannot carry UDP: a rule that sends UDP to an HTTP proxy leaves that UDP traffic direct, and ProxyBridge writes a warning in the Activity Logs. The editor shows a warning too. A SOCKS5 proxy that accepts UDP is still not a guarantee that QUIC or HTTP/3 will work. See Troubleshooting.

UDP rules match on the app only

macOS hands ProxyBridge a new UDP "flow" without telling it where the datagrams will go. So for UDP:

  • A rule is matched by process or bundle identifier and protocol only. The Target hosts and Target ports are ignored.
  • A rule with the process * and a host or port limit never matches UDP, because there is nothing to compare the limit with.
  • A UDP or BOTH rule with specific programs therefore applies to all UDP traffic of those programs, whatever the destination.

If you write a rule for curl with the hosts 10.*.*.* and the protocol BOTH, TCP connections to 10.x.x.x match it, but all UDP from curl matches it too.

Action

Action What happens to matching traffic
DIRECT Left alone. It goes out normally. Useful for exceptions
BLOCK The connection is closed at once. The app sees the connection fail, or, for UDP, loses its datagrams
A proxy Sent through that proxy. Every proxy from Proxy servers is listed with its name

If a rule points at a proxy that no longer exists (for example the rule came from an imported file), its traffic goes direct, and ProxyBridge writes one error line in the Activity Logs: A rule routes to a proxy that no longer exists, its traffic is going direct.

How rules are matched

Rules are not simply read from top to bottom. ProxyBridge goes through the enabled rules in list order and applies these steps to each new connection:

  1. Skip rules that are switched off.
  2. Skip rules whose protocol does not fit (a TCP rule never sees UDP traffic).
  3. A rule with a specific program (not *) that matches the program, host and port is used immediately.
  4. A rule with the program * and a host or port limit is also used immediately when the connection fits the limit (TCP only).
  5. A rule with the program * and no limits at all (all programs, all hosts, all ports) is a catch-all. It is not used immediately. ProxyBridge remembers the first catch-all and uses it only if nothing else matched.
  6. If nothing matched and there is no catch-all, the connection goes direct and is logged as Direct.

What follows from this:

  • A specific rule always beats a catch-all, whatever their order. You can put a catch-all * → proxy rule anywhere and still exempt individual programs with their own DIRECT rule.
  • Among specific rules, and * rules that have a limit, the first match in the list wins. A broad specific rule above a narrow one hides the narrow one. Put exceptions above the rule they are exceptions to.
  • Only the first catch-all counts. A second catch-all never takes effect.
  • A connection that matches no rule is not an error: it simply goes direct.

The rule list cannot be reordered in the window. There are no up and down buttons. A new rule goes to the end of the list, an imported rule is added at the end. To change the order, delete and re-add the rules in the order you want, or export the profile, edit the order in the JSON file, and import it again (see Profiles).

Always direct

  • ProxyBridge's own traffic (the app and its extension) is never redirected, so the proxy test, update check and the connection to your proxy are not affected by your rules.
  • Anything macOS itself does not give to ProxyBridge cannot be routed. A program that never appears in the Connections log is not reaching ProxyBridge.
  • Connections that match no rule, or a DIRECT rule, are handed back to macOS and go out normally.

Export and import rules

Export saves the ticked rules to a JSON file named ProxyBridge-Rules.json by default. Import reads such a file and adds its rules to the end of the current list (it never removes or replaces anything).

[
  {
    "name": "Chrome to Burp",
    "processNames": "*chrome*",
    "targetHosts": "*",
    "targetPorts": "80; 443",
    "protocol": "TCP",
    "action": "6D1B9A3E-4B7B-4D0A-9A3E-1B2C3D4E5F60",
    "enabled": true
  }
]
Field Meaning
name The rule's name. May be empty
processNames The Process / Bundle Identifier field
targetHosts, targetPorts The two target fields
protocol TCP, UDP or BOTH
action DIRECT, BLOCK, or the internal id of a proxy. That id belongs to a proxy on the Mac where the file was exported
enabled true or false

A rule that uses a proxy cannot move to another profile or another Mac through rules export. The action holds the proxy's id, and the id does not exist elsewhere, so the imported rule would go direct (with the warning above). To move rules and proxies together, use profile export and import instead. Rules export is good for DIRECT and BLOCK rules, and for copying rules inside the same profile setup.

A file that is not valid JSON in this shape is ignored without a message, and nothing is added.

Examples

Goal Process Hosts Ports Protocol Action
Firefox to Burp firefox * 80; 443 TCP Burp
Chrome (any helper) to Burp *chrome* * * TCP Burp
curl through Tor curl * * TCP Tor
Everything to the company proxy, except the browser * * * BOTH Company
... the exception *safari*; com.apple.WebKit.Networking * * BOTH DIRECT
Company network only * 10.*.*.*; *.corp.example.com * TCP Company
Block an app com.example.tracker* * * BOTH BLOCK
Stop a browser's QUIC (UDP) *chrome* (ignored) (ignored) UDP BLOCK

More complete walk-throughs are in Use cases.

Tips

  • Start with one rule for one program and watch the Connections tab. Add more when it works.
  • Use wildcards for programs with helpers: *chrome*, com.microsoft.VSCode*.
  • Put exceptions above broad rules, and remember a catch-all (* with no limits) is always the last resort.
  • Keep DIRECT rules for your proxy tool (Burp Suite, mitmproxy) when you use a catch-all rule, so it does not route itself.
  • When a rule does nothing, read Troubleshooting.