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

Linux Guide

How ProxyBridge works on Linux

How the Linux version redirects connections with eBPF: what the kernel decides, what the relay does, how UDP, DNS and domain rules work, what happens when ProxyBridge stops, and the security model.

How ProxyBridge works on Linux

You do not need this page to use ProxyBridge. Read it to understand why some things behave the way they do, to judge the security of the design, or to debug something unusual.

The idea in one picture

ProxyBridge does not capture packets. It hooks the socket calls of programs (connect(), sendmsg(), recvmsg()) with small eBPF programs attached to the root cgroup. When a program calls connect(), the kernel asks: which program is this, and which of your rules apply?

 application          kernel (eBPF hooks)                       ProxyBridge (user space)
 -----------          -------------------                       ------------------------
 connect(dst) ──────► which program is this? which rules apply?
                       no rule / Direct ──► unchanged: no extra cost on the data path
                       Block            ──► connect() fails with "permission denied"
                       Proxy            ──► destination rewritten to 127.0.0.1:relay,
                                            the original destination is saved ──────► relay reads it, talks
                                                                                      SOCKS5 or HTTP CONNECT
                       cannot decide    ──► handed to the relay "to decide"  ────────► full rule engine decides
                                                                                      (and teaches the kernel)

Consequences:

  • No packet queueing, no iptables, no routing changes. The data path of a program that is not redirected is the normal kernel path. There is nothing to undo on your system.
  • Decisions are made once per connection, not per packet.
  • The program thinks it is talking to the real server. getpeername() on a redirected socket returns the original destination.
  • Requires a kernel with BTF and cgroup v2 (5.11 or newer) and root.

The service and the window

The engine needs root; the window does not. ProxyBridge is therefore two programs:

 ProxyBridgeGUI (runs as you)                 proxybridge.service (runs as root)
 the window                                   ProxyBridge --daemon
                  --- requests --->
        /run/proxybridge/ctl.sock             engine, relay,
                  <--- events -----           profile files, settings
  • Requests go from the window to the service: add or edit a proxy or rule, switch a profile, start or stop the engine, read or write a profile file, ask for the live connections, run the proxy test. The window keeps its own copy of your configuration for the screens; the service holds the one that is applied.
  • Events go the other way: connection lines and log lines as they happen, the proxy-test report line by line.
  • A configuration is loaded in one piece. Switching profiles, or a window reconnecting, sends the whole configuration inside a batch, and the service loads it into the kernel once at the end. New connections never see half a rule set.
  • The service survives the window. With Start at Boot on, closing the window leaves the engine running; with it off, closing the window stops the engine. If the service stops, the kernel programs go with it and traffic goes direct (Fail-open).
  • The protocol is a plain length-prefixed list of text fields over a Unix socket, with hard size limits checked before anything is read. It is versioned: a window and a service of different versions refuse each other with a clear message instead of misbehaving.

The command line (ProxyBridge --profile) does not use the service: it is a complete engine of its own for scripts and CI. A window started with sudo on a system without the service also runs its own engine.

What the kernel decides and what the relay decides

The kernel part identifies a program by its executable (device and inode number, which is why renaming a copy of a program does not fool it) and looks up a precompiled class: the ordered list of rules whose process pattern matches that program. Rules are compiled into small, fixed-size lookups:

Decided in the kernel Handled by the relay (user space)
Port lists and ranges, up to 4 entries per rule Longer port lists
IPv4 addresses, networks and ranges, up to 4 per rule, and short host lists Long host lists, patterns such as 192.168.*.* that cannot be turned into a range, IPv6 patterns
Protocol (TCP or UDP) Domain names
Block and Direct The first connection of a program the kernel has not seen yet

For anything the kernel cannot express, the connection is handed to the relay, which runs the complete rule engine (the reference for every rule), decides, and teaches the kernel the answer so later connections of the same kind skip the detour. This is why a very long rule list does not slow TCP down once it has been seen.

For TCP the cost of the detour is one local hop. For UDP the relay re-sends the datagram itself, which has visible side effects; see UDP and the slow path.

TCP

  1. The program connects. The kernel rewrites the destination to the relay's loopback port (24010 by default; the next free pair of ports is used if taken) and keeps the original destination, keyed by the connection's source port.
  2. The relay accepts the connection, looks up where the program really wanted to go, and opens a connection to the proxy.
  3. SOCKS5 proxies get a SOCKS5 CONNECT (with username and password if configured), HTTP proxies get CONNECT host:port, with Basic authentication if configured. If DNS via proxy is on and the name is known, the name is sent, otherwise the address.
  4. After the handshake the relay copies bytes both ways. If the handshake fails, the program's connection is closed. It is never sent directly.

The relay is a single epoll loop per role with bounded resources: a connection cap, idle timeouts, and a pool of handshake workers (8 to 64) so a proxy that accepts connections and never answers cannot stall the rest.

UDP

UDP is harder because one socket can talk to many destinations.

  • The kernel encodes the original destination as a loopback flow address (127.x.y.z) and sends the datagram to the relay.
  • The relay maps the flow address back to the real destination and to the program that opened it, then forwards the datagram through a SOCKS5 UDP association (UDP ASSOCIATE) kept alive by a TCP control connection to the proxy.
  • Replies come back from the flow address, and a recvmsg hook restores the real source address, so the program sees the answer coming from the server it talked to.
  • A flow is dropped after 60 seconds of silence, because the engine cannot see a program close its socket.
  • HTTP proxies cannot carry UDP. A rule that sends UDP to one is logged, and that UDP goes direct.

DNS and domain rules

A program resolves a name and then connects to an address; the kernel only ever sees the address. To support rules and DNS via proxy by name, ProxyBridge builds an address-to-name map from the DNS answers the program received:

  1. If at least one enabled rule has a domain entry, the DNS traffic (port 53, UDP and TCP) of every program covered by such a rule is routed through the relay, which forwards it to the original resolver unchanged and reads the answers.
  2. A and CNAME records are recorded. www.shop.test -> cdn.edge.net -> 198.51.100.7 makes that address match rules for either name.
  3. The mapping is installed in the kernel before the answer is delivered to the program, so even the first connection matches.
  4. Names from /etc/hosts are loaded at start.
  5. The map holds 32,768 addresses, oldest first out. It has no time-to-live, so programs that cache DNS answers keep matching.

Only answers that belong to the question are recorded: the name asked, the CNAMEs chained from it, and A records owned by those names. Unrelated records in a response are ignored. DNS over HTTPS and TLS bypass this, because the answers are encrypted.

Fail-open

The programs are attached through BPF links, which the kernel removes when ProxyBridge exits, is killed or crashes. From that moment:

  • connections go directly, as if ProxyBridge was never there;
  • Block rules no longer block; nothing is proxied;
  • there is nothing to clean up: no iptables rules, no changed settings.

That makes ProxyBridge safe to try, and it also means it is a routing tool, not a firewall. When something must never reach the network, enforce it with a real firewall and use the boot service (which restarts ProxyBridge after a failure).

Connections already relayed when ProxyBridge stops end with it. Connections that were direct stay direct.

Local proxies and loops

When a process on this computer listens on a configured proxy's address and port (Burp, ssh -D, Tor, InterceptSuite), ProxyBridge exempts that process, so a broad rule cannot send the proxy's own connections back into the proxy. The check is refreshed every two seconds and follows the process, not the program name. Log line: process P serves proxy 'name': its own connections are sent direct, not back through the proxy.

Security model

Loading eBPF requires root, so the engine runs as root inside the service. It was designed so that an ordinary local user cannot use it against another user:

  • Who may control the service. The socket accepts connections from every user, but the service asks the kernel who is on the other end (peer credentials) and serves only root and members of the group proxybridge. The group is read from the system at every connection, so adding or removing a member takes effect at once. Anyone else gets a refusal, and the service logs it (journalctl -u proxybridge). Membership is administrative power: such a user can route, block and read the proxy passwords for every user, so keep the group small.

  • The window does not trust the socket blindly. It talks only to a socket owned by root, so a program run by another user cannot impersonate the service and collect your proxy passwords.

  • The service does not trust the window. Every message is bounded before it is read (a frame is at most 8 MiB and must arrive within 30 seconds of its header, at most 4096 fields, at most 16 windows at once), every number and name is checked, a profile sent for saving is fully validated before it touches the disk, profile names cannot name a path or contain control characters, and the profile store is limited in size. A window that stops reading loses events (and is told how many) instead of blocking the engine, and one that lets 64 MiB of answers pile up is disconnected. A batch a window leaves open is applied after 10 seconds, so one window cannot hold back everyone's changes. One proxy test runs at a time. A session ends within seconds when its user is removed from the group.

  • A flood of refused connections is cheap. Any user can connect to the socket, so refusing must cost almost nothing: a user refused a moment ago is not looked up again, the journal gets one line per user per minute, and the log that windows show is untouched.

  • Redirected TCP connections are bound to the client's source address and port. A process that connects to the relay from another loopback address cannot claim someone else's pending connection, and an entry is consumed on first use.

  • UDP flows are tied to their owner. The flow addresses are visible in /proc/net/udp, so the relay checks, for every new client port, which user owns the socket bound to it. A datagram sent into another user's flow is dropped (root excepted). This is best effort rather than proof: when nobody holds the port any more, nothing can be told and the datagram is delivered; programs of one user are not separated from each other. One program can hold at most 2048 of the 4096 UDP sessions and displaces only its own oldest session past that.

  • Decisions use the executable recorded when the connection was opened, not /proc/<pid>/exe read later, so a process that exits and has its PID reused cannot change a pending decision.

  • Everything another user controls is cleaned before display. Program names and DNS names have control characters replaced before they reach the terminal or the window, and profiles with control characters in any field are rejected.

  • Names are checked before they reach a proxy, so a hostile DNS answer cannot inject anything into a SOCKS5 or HTTP request.

  • A proxy that does not exist blocks. A rule that needs a proxy that was deleted blocks its traffic instead of letting it through, and a failed proxy handshake closes the connection.

  • The relay listens on loopback only, and its UDP port is additionally bound to the loopback device. Other network namespaces (containers) are never redirected.

  • Credentials stay out of the process list. Proxy passwords are in profile files (0600, in a 0700 folder, owned by root) and are never taken from the command line.

  • The service is sandboxed. Besides the usual (NoNewPrivileges, ProtectSystem=strict with only /etc/proxybridge writable, ProtectHome, PrivateTmp, PrivateDevices), it is limited to the seven capabilities the engine needs, to unix, internet and netlink sockets, to the native system-call ABI, with no new namespaces and no writable-and-executable memory. The automated tests run the real engine under exactly this sandbox. See Settings. A window started as root without the service only installs a unit when the program and every folder above it are owned by root and not writable by others.

  • Updates never run anything. The update check only reads a feed, opens a page in your browser, and accepts addresses on the project's own sites only.

Known limits of this model, stated plainly:

  • On a machine shared with other users, any local process whose DNS passes through the relay can teach the engine a name-to-address mapping for its own lookups. Since domain rules match by address, another user's resolver answers can influence which addresses a domain rule matches. Run ProxyBridge on machines whose local users you trust.
  • While a configured proxy's port is free (the proxy is not running), any local process that binds it is treated as the proxy. Start the proxy first, or point rules at a proxy on another host, when others share the machine.

Resource use

  • Memory is bounded: fixed-size kernel maps (a few MB in total) and LRU maps for per-flow state.
  • The relay raises its open-file limit and sets a cap on connections; when a cap is reached it drops new connections and says so in the Activity Logs.
  • A rule evaluated in the kernel adds no work to the data path; only new connections are examined.
  • DNS from programs covered by a domain rule takes one extra loopback hop (about 0.1 ms per query).

The binaries

The command line program and the library are statically linked against everything except glibc, so there is nothing to install at run time. The window needs GTK3. Binaries are built against a glibc 2.34 baseline (Ubuntu 22.04, Debian 12, RHEL 9 and newer) with LTO, FORTIFY_SOURCE=3, full RELRO, BIND_NOW, PIE, a stack protector and CET flags, and the build audits this on every run.

The source is in Linux/ of the repository: the kernel part in src/bpf/proxybridge.bpf.c, the relay in src/pb_relay.c, the rule engine in src/pb_rules.c.

Why this design

An earlier eBPF attempt evaluated rules per packet in the kernel and was dropped for memory and latency reasons. The current design decides once per connection, compiles rules into small bounded maps, and sends everything the kernel cannot express to user space once per connection.