Skip to content

Process Rules ​

A process rule routes a connection by the program that opened it: send git and cargo through a proxy, keep a game launcher direct, block an updater. Process rules sit in [route].rules next to every other rule and follow the same first-match order.

toml
[route]
rules = [
  "PROCESS-NAME,cargo,work",
  "PROCESS-NAME-REGEX,^(ssh|git-remote-https?)(\\.exe)?$,work",
  'PROCESS-PATH,C:\Program Files\Steam\steam.exe,DIRECT,include-children',
  "FINAL,DIRECT",
]

Read this page before writing process rules. A rule that looks right but names the program the way your platform does not report it never matches, and nothing warns you.

Rule types ​

TypeComparesPattern
PROCESS-NAMEthe executable's file nameexact text, or a wildcard if it contains * or ?
PROCESS-PATHthe executable's full pathexact text, or a wildcard if it contains * or ?
PROCESS-NAME-WILDCARDthe executable's file namealways a wildcard
PROCESS-PATH-WILDCARDthe executable's full pathalways a wildcard
PROCESS-NAME-REGEXthe executable's file nameregular expression
PROCESS-PATH-REGEXthe executable's full pathregular expression

A rule is TYPE,pattern,target, optionally followed by include-children (below). The target is DIRECT, REJECT, a proxy or a proxy group.

How a pattern matches ​

Every process rule follows the same rules, whether it stands alone, sits inside AND/OR/NOT, or is an entry of a rule set:

  • Case never matters. PROCESS-NAME,chrome.exe, Chrome.EXE and CHROME.exe are the same rule. Case folding covers ASCII letters only; other characters must be written exactly.
  • Exact text must equal the whole name or path.
  • Wildcards match the whole value. * matches any run of characters, including / and \, so /Applications/Slack.app/* covers every file under the bundle. ? matches one byte. There is no escaping and there are no character classes.
  • Regular expressions are PCRE2 and search anywhere in the value: REGEX,chrome also matches chromedriver. Anchor with ^ and $ to match the whole value. Matching ignores ASCII case.
  • An unknown process matches no process rule, of any type. When Specola cannot tell which program opened a connection, every process rule is skipped and matching continues with the next rule. NOT((PROCESS-NAME,x)) is therefore true for an unknown process.

Writing the pattern ​

  • The rule is split on commas, so a pattern cannot contain a comma, except inside parentheses: PROCESS-NAME-REGEX,^(py{1,2})$,X works, PROCESS-NAME-REGEX,^py{1,2}$,X does not. Parentheses must be balanced.
  • Spaces at the start and end of the pattern are removed; spaces inside are kept (PROCESS-NAME,Google Chrome,X).
  • Windows paths contain backslashes. Write those rules as TOML literal strings, in single quotes, so the backslashes stay as they are: 'PROCESS-PATH,C:\Windows\System32\curl.exe,X'. Inside a regular expression, a literal dot or backslash needs a regex escape; in a double-quoted TOML string that escape is written twice: "PROCESS-NAME-REGEX,^curl\\.exe$,X".
  • A regular expression that does not compile is reported when the profile loads, with the rule and the position of the error.

What Specola sees as the name and path ​

Specola matches the strings the operating system reports, without rewriting them.

NamePath
Windowsfile name with .exe: chrome.exe, git-remote-https.exefull Win32 path with backslashes: C:\Program Files\Google\Chrome\Application\chrome.exe
macOSthe executable inside the bundle, not the .app: Google Chrome, Google Chrome Helper (Renderer)/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
Linuxfile name of the resolved executable: cargo, python3.12/proc/<pid>/exe with symlinks resolved: /usr/bin/python3.12

Things that catch people out:

  • Windows: PROCESS-NAME,chrome never matches; the name is chrome.exe. Use PROCESS-NAME,chrome.exe, or (\.exe)? in a regular expression to cover all platforms.
  • macOS: apps run several executables. A browser's network traffic often comes from its helper processes, not the main one. Match the bundle with a path wildcard, PROCESS-PATH-WILDCARD,/Applications/Google Chrome.app/*,X, or the main process with include-children.
  • Linux: symlinks are resolved. python3 is reported as python3.12 when /usr/bin/python3 links to it, so match ^python3 with a regular expression. A program that was upgraded while it runs is still reported under its file name.
  • Linux containers (eBPF only): a process in another PID namespace has no path, only its kernel name, cut to 15 characters. PROCESS-PATH rules never match it.
  • Protected Windows processes may report no name or path; they count as unknown.

Copy names and paths from the Connections page: it shows the process name and path of each connection exactly as rules see them.

Which connections carry a process ​

Where the connection comes fromWindowsmacOSLinux
Local HTTP/SOCKS5 port, from this computeryesyesyes
Local HTTP/SOCKS5 port, from another device (allow-lan)nonono
Enhanced Mode TCPyes (TUN)yes (TUN)yes (eBPF)
Enhanced Mode UDPbest effort (TUN)best effort (TUN)yes (eBPF)
Router gateway, LAN clients——no
  • Local port: Specola looks up which program owns the client socket. Only connections from the same computer have one. The local port carries TCP only (SOCKS5 CONNECT and HTTP).
  • TUN (Windows, macOS): Specola looks up the owner of each new flow in the system's socket table. For TCP this is exact. For UDP the table holds only the local address and port, so a socket that sends to many destinations, or one that closes at once, can come out unknown.
  • eBPF (Linux): the kernel records the process when the socket is created, so every captured connection has one. See what eBPF captures.
  • LAN clients and the router gateway have no local process. Route them with SRC-IP-CIDR, SRC-MAC or SRC-DEVICE instead.

When the process is unknown, process rules are skipped; the connection is matched by the remaining rules and ends at FINAL.

Order and combinations ​

Process rules take part in the normal first-match order. A domain rule above a process rule wins when both match:

toml
rules = [
  "DOMAIN-SUFFIX,corp.example.com,office",  # corp traffic of every program, git included
  "PROCESS-NAME,git,work",                  # everything else git opens
  "FINAL,DIRECT",
]

Combine a process with a destination using logical rules. Each part is wrapped in parentheses:

toml
rules = [
  # Only curl's connections to example.com
  "AND,((PROCESS-NAME,curl),(DOMAIN-SUFFIX,example.com)),work",
  # Either browser
  "OR,((PROCESS-NAME,firefox),(PROCESS-NAME,chrome.exe)),work",
  # Port 443 of every program except the updater
  "AND,((DST-PORT,443),(NOT,((PROCESS-NAME,updater)))),work",
]

Process rules can also be entries of a rule set; an entry has no target and no options:

toml
[route]
rules = ["RULE-SET,dev-tools,work,include-children", "FINAL,DIRECT"]
rule-set = [
  { name = "dev-tools", type = "inline", behavior = "classical", rules = [
      "PROCESS-NAME,cargo", "PROCESS-NAME,go", "PROCESS-NAME-REGEX,^node(\\.exe)?$",
  ] },
]

Process rules cannot be tested on the Rules page: its test checks a destination only, without a process.

include-children ​

include-children makes a rule also match the programs the named process started, and the ones those started:

toml
rules = [
  'PROCESS-PATH,C:\Program Files (x86)\Steam\steam.exe,DIRECT,include-children',
  "PROCESS-NAME,Terminal,work,include-children",
]

How it works:

  • A connection matches if its own process or any of its ancestors satisfies the rule. Specola walks up the chain of parents from the connection's process.
  • The rule keeps its place in the list. An include-children rule matched through an ancestor still loses to an earlier rule that matched the process itself, and beats every later rule.
  • It works on rules that test a process, including AND/OR that contain one, and on RULE-SET, where it applies to every process rule in the set. A rule-set entry cannot carry it.
  • It needs the local process tree, so it has no effect for LAN clients and the router gateway.

How far up Specola looks:

PlatformAncestors
Windowsparent chain, up to 24 levels
macOSparent chain up to launchd, plus the "responsible" process: helpers of an app count as its children, and programs started from Terminal count as Terminal's
Linux, local portparent chain up to, not including, PID 1, 24 levels
Linux, eBPFparent chain up to 64 levels, including PID 1

Do not name a process that starts everything: explorer.exe on Windows, launchd on macOS, systemd (PID 1) on Linux. Such a rule matches almost every connection.

Combine include-children with NOT with care: NOT((PROCESS-NAME,bash)),X,include-children means "this process or one of its ancestors is not bash", which nearly always holds.

Pinned members on Linux eBPF ​

On Linux eBPF, a process rule that targets a proxy group picks one member the first time it matches and keeps it:

  • url-test does not switch to a faster member, fallback does not fail over, load-balance does not spread, for the connections of that rule.
  • Choosing a different member of a select group does not move them.
  • Two process rules that target the same group may keep different members.

This keeps an application on one exit, so its public address does not change in the middle of a session. The choice is made again when proxies, groups or rules change and the profile is reloaded. If you want failover for a program on Linux, target a proxy, or route the program with a domain or IP rule. Windows and macOS do not pin: every connection asks the group.

What Linux eBPF captures ​

On Linux, Enhanced Mode decides in the kernel which connections reach Specola at all. A process rule can only act on a connection that is captured:

  • Process names in PROCESS-NAME and PROCESS-NAME-WILDCARD rules, and existing files in exact PROCESS-PATH rules, become kernel candidates. The kernel compares the file name of the process's executable, ignoring case like Specola does. Their connections are captured; Specola then evaluates the full rule list.
  • Rules the kernel cannot bound make every process a candidate: regular expressions, NOT, path wildcards, a PROCESS-PATH file that does not exist when the profile loads, names of 64 bytes or more, more than 64 candidates, and any include-children rule. So do rules that do not test a process or a destination address at all, such as DST-PORT, NETWORK, SRC-*, IP-ASN, or an AND/OR without a process part: any program may hit them, so every program must reach Specola. Everything then goes through Specola; that is correct but costs throughput.
  • Destinations on loopback, private networks (10/8, 172.16/12, 192.168/16), link-local, multicast, broadcast and the computer's own addresses are never captured, so process rules cannot route them. IPv6 is not captured.
  • Specola itself is never captured, nor is the Specola app when it is the program that started Core.
  • Processes in another network namespace (most containers) are not captured at all.
  • A connection no candidate selects follows FINAL in the kernel: when FINAL is DIRECT it is not captured, unless [enhanced-mode.ebpf] unmatched-traffic = "core".

On Windows and macOS, TUN captures by route, not by process: process rules apply to everything that enters TUN and to nothing that exclude-routes or a more specific local route keeps out of it.

DNS ​

Process rules never decide a DNS answer. DNS queries usually come from the system resolver, not from the app (the DNS Client service on Windows, mDNSResponder on macOS, often systemd-resolved on Linux), and they carry no process. The connection that follows the answer is routed by process as usual.

  • PROCESS-NAME,app,REJECT blocks the app's connections, not its DNS lookups.
  • On TUN, a Fake-IP connection that a process rule sends DIRECT is resolved again by Specola.
  • On Linux eBPF, names that no domain or IP rule decides get Fake-IP answers, so their connections are captured and evaluated with the process.

Specola's own traffic ​

  • Specola's connections to proxies never enter Enhanced Mode, so no rule routes them.
  • On Linux eBPF the Specola app is not captured either, when it is the program that started Core. On TUN and the local port the app's connections are routed like any other program.

Troubleshooting ​

A process rule that never fires is almost always one of these:

  1. The name is not what the platform reports. Open Connections, find a connection of the program and copy its process name or path. From a terminal:
    • Windows: Get-Process -Name chrome | Select-Object Name, Path (the rule name adds .exe)
    • macOS: ps -o comm= -p <pid> (the last path component is the name)
    • Linux: readlink /proc/<pid>/exe
  2. The connection carries no process: it comes from another device, from the router gateway, or it is a short UDP exchange on TUN. See which connections carry a process.
  3. An earlier rule matches first. Move the process rule up, or look at the rule named in Connections.
  4. On Linux eBPF the connection is not captured: the destination is local or private, or nothing selects the process and FINAL is DIRECT. See what eBPF captures.
  5. On Linux eBPF a group never changes member for that program: that is pinning.

Recipes ​

toml
rules = [
  # Developer tools on every platform (Windows adds .exe)
  "PROCESS-NAME-REGEX,^(git|git-remote-https?|ssh|cargo|rustup|go|node|npm|pnpm)(\\.exe)?$,work",

  # A macOS app with all its helpers
  "PROCESS-PATH-WILDCARD,/Applications/Slack.app/*,work",

  # A game launcher and every game it starts stay direct
  'PROCESS-PATH,C:\Program Files (x86)\Steam\steam.exe,DIRECT,include-children',

  # Everything started from a terminal window on macOS
  "PROCESS-NAME,Terminal,work,include-children",

  # Block an updater
  "PROCESS-NAME-WILDCARD,*updater*,REJECT",

  "FINAL,DIRECT",
]

See also Rules for the rule syntax and the other rule types, and Linux eBPF and TUN for Enhanced Mode.