Skip to content

Force Proxy to any Windows/MacOS/Linux Application TCP and UDP traffic

test(linux): security, churn and exemption tests; document the security model

anof-cyberbdeb45833567
diff --git a/.github/workflows/build-linux.yml b/.github/workflows/build-linux.yml
index 48c223c..83c9c00 100644
--- a/.github/workflows/build-linux.yml
+++ b/.github/workflows/build-linux.yml
@@ -164,7 +164,7 @@ jobs:
uname -r
ls /sys/kernel/btf/vmlinux && mount | grep -q "type cgroup2" || { echo "kernel lacks BTF or cgroup2: skipping"; exit 0; }
fail=0
- for t in e2e e2e_rules e2e_domains api_live; do
+ for t in e2e e2e_rules e2e_domains e2e_security api_live; do
echo "::group::$t"
sudo env PB_DIR="$PWD/Linux/output" BPFTOOL="$BPFTOOL" bash "Linux/tests/$t.sh" || fail=1
echo "::endgroup::"
diff --git a/Linux/README.md b/Linux/README.md
index f2c2353..a47d912 100644
--- a/Linux/README.md
+++ b/Linux/README.md
@@ -258,6 +258,7 @@ Rules are evaluated **in order and the first match wins** (put specific rules be
- Process names are case-sensitive on Linux
- Interpreted programs (python, node, java) are identified by the interpreter binary, e.g. `python3.12`
- A `PROXY` rule whose proxy does not exist is treated as `BLOCK` (traffic never leaks around a missing proxy)
+- A local proxy is never proxied through itself: processes that listen on a configured proxy address (for example Burp, mitmproxy, Tor or `ssh -D` on 127.0.0.1) are exempted automatically, so a rule with process `*` cannot create a loop. The exemption is per process, not per program, and is refreshed every two seconds
- Press `Ctrl+C` to stop ProxyBridge; the kernel hooks are removed automatically, even if ProxyBridge crashes
## Domain rules
@@ -281,6 +282,14 @@ Cost: DNS from covered processes takes one extra loopback hop (about +90 µs per
Add as many `--proxy` entries (CLI) or proxies (GUI) as you need; each rule chooses its own with `PROXY=name`. Proxy hosts may be IP addresses or **host names** (resolved with a 5 s deadline and a cache, so a slow resolver cannot stall traffic). A rule that references a proxy that no longer exists blocks instead of leaking.
+## Security model
+
+- **Redirected TCP connections** are bound to the client's source address and port. A process that connects to the relay from a different loopback address (for example `127.0.0.2`) cannot claim another process's pending flow, and an entry is consumed on first use.
+- **Redirected UDP flows** are addressed by a loopback flow address that the relay maps back to the original destination. These addresses are not secret (they are visible in `/proc/net/udp`), so on a **multi-user host** another local user can send datagrams to the relay's UDP port and have them forwarded to a destination that some other process is already talking to, through the same proxy. Run ProxyBridge on machines you trust locally.
+- A rule that needs a proxy that does not exist **blocks** instead of letting traffic through.
+- The relay listens on loopback only (UDP is additionally bound to the `lo` device). Other network namespaces (containers) are never redirected.
+- Proxy passwords are kept in `/etc/proxybridge/config.ini` (mode 0600, root). On the command line, `--proxy user:pass@host` is wiped from the process list after parsing, but a shell history can still keep it; prefer the GUI or a config file for secrets.
+
## Use Cases
- Redirect proxy-unaware applications (games, desktop apps) through InterceptSuite/Burp Suite for security testing
@@ -314,7 +323,7 @@ Add as many `--proxy` entries (CLI) or proxies (GUI) as you need; each rule choo
These addresses and ports are used by system components, network discovery, and essential Linux services.
-- **UDP Proxy Requirements**: UDP traffic only works when a SOCKS5 proxy is configured. If an HTTP proxy server is configured, ProxyBridge will ignore UDP proxy rules and route UDP traffic as direct connection instead. This limitation does not affect UDP rules with BLOCK or DIRECT actions.
+- **UDP Proxy Requirements**: UDP traffic only works through a SOCKS5 proxy. A rule that sends UDP to an HTTP proxy cannot be honoured, so that UDP traffic goes DIRECT; ProxyBridge logs a warning naming the rule when it is created or the engine starts. Use a SOCKS5 proxy, or a TCP-only rule plus a separate `UDP ... BLOCK` rule, if direct UDP is not acceptable. This limitation does not affect UDP rules with BLOCK or DIRECT actions.
**Important UDP Considerations**:
- Configuring a SOCKS5 proxy does not guarantee UDP will work. Most SOCKS5 proxies do not support UDP traffic, including SSH SOCKS5 proxies.
@@ -510,6 +519,8 @@ cd ../../tests && sudo ./e2e.sh # end-to-end with real kernel
sudo ./e2e_domains.sh # domain rules with a real resolver client (root, needs dig)
sudo ./e2e_rules.sh # every rule form + every proxy type, incl. HTTP auth and UDP rules (root)
sudo ./api_live.sh # library API: edit/move/disable/delete rules and proxies on the live datapath (root)
+sudo BPFTOOL=$(command -v bpftool) ./e2e_security.sh # relay hand-off cannot be hijacked from another loopback address (root)
+sudo ./churn.sh 3000 # rule/proxy churn with live traffic: memory, fds and threads must stay flat (root)
sudo ./e2e_openssh.sh # interoperability with a real third-party SOCKS5 server (OpenSSH ssh -D), 40 MB each way (root)
sudo NODE=$(command -v node) NEXUS_JS=/path/to/nexus-proxy/script.js ./e2e_nexus.sh # against Nexus Proxy, a real forwarding SOCKS5 server with UDP (root)
sudo ./scale.sh 10000 # 10,000 concurrent proxied connections (root)
diff --git a/Linux/tests/api_live.sh b/Linux/tests/api_live.sh
index 45f71b6..308fa24 100755
--- a/Linux/tests/api_live.sh
+++ b/Linux/tests/api_live.sh
@@ -7,4 +7,4 @@ WORK=$(mktemp -d); trap 'kill $FAKE 2>/dev/null; wait 2>/dev/null; rm -rf $WORK'
gcc -Wall -Wextra -O1 -g -I"$ROOT/src" -o "$WORK/api_live_test" "$HERE/api_live_test.c" -L"$PB_DIR" -lproxybridge -lpthread || exit 1
python3 "$HERE/fake_proxies.py" "$WORK/log" >/dev/null 2>&1 & FAKE=$!
sleep 1
-LD_LIBRARY_PATH="$PB_DIR" "$WORK/api_live_test"
+env LD_LIBRARY_PATH="$PB_DIR" ${PB_PRELOAD:+LD_PRELOAD="$PB_PRELOAD"} "$WORK/api_live_test"
diff --git a/Linux/tests/churn.sh b/Linux/tests/churn.sh
new file mode 100755
index 0000000..82ba525
--- /dev/null
+++ b/Linux/tests/churn.sh
@@ -0,0 +1,17 @@
+#!/bin/bash
+# Rule/proxy churn with live traffic. Needs root, curl, python3, gcc. sudo tests/churn.sh [iterations]
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"; ROOT="$(dirname "$HERE")"
+PB_DIR="${PB_DIR:-$ROOT/output}"
+[ -f "$PB_DIR/libproxybridge.so" ] || { echo "Build first: (cd Linux && ./build.sh), or set PB_DIR"; exit 1; }
+WORK=$(mktemp -d); trap 'kill $FAKE $TRAFFIC 2>/dev/null; wait 2>/dev/null; rm -rf $WORK' EXIT
+gcc -Wall -Wextra -O1 -g -I"$ROOT/src" -o "$WORK/churn_test" "$HERE/churn_test.c" -L"$PB_DIR" -lproxybridge -lpthread || exit 1
+python3 "$HERE/fake_proxies.py" "$WORK/log" >/dev/null 2>&1 & FAKE=$!
+sleep 1
+( while :; do
+ curl -s -m 2 http://192.0.2.5/ >/dev/null
+ python3 -c "
+import socket
+s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM); s.settimeout(1)
+s.sendto(b'x', ('192.0.2.9', 5300)); s.recv(100)" 2>/dev/null
+ done ) & TRAFFIC=$!
+env LD_LIBRARY_PATH="$PB_DIR" ${PB_PRELOAD:+LD_PRELOAD="$PB_PRELOAD" PB_SANITIZED=1} "$WORK/churn_test" "${1:-3000}"
diff --git a/Linux/tests/churn_test.c b/Linux/tests/churn_test.c
new file mode 100644
index 0000000..2d82f50
--- /dev/null
+++ b/Linux/tests/churn_test.c
@@ -0,0 +1,82 @@
+// Rule/proxy churn while traffic flows: memory, descriptors and threads must stay flat.
+#define _GNU_SOURCE
+#include <dirent.h>
+#include <malloc.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include "../src/ProxyBridge.h"
+
+static long status_kb(const char *key)
+{
+ FILE *f = fopen("/proc/self/status", "r");
+ char line[256];
+ long v = -1;
+ size_t n = strlen(key);
+ while (f && fgets(line, sizeof line, f))
+ if (!strncmp(line, key, n)) { v = strtol(line + n, NULL, 10); break; }
+ if (f) fclose(f);
+ return v;
+}
+
+static int count_dir(const char *path)
+{
+ DIR *d = opendir(path);
+ int n = 0;
+ struct dirent *e;
+ while (d && (e = readdir(d))) n += e->d_name[0] != '.';
+ if (d) closedir(d);
+ return n;
+}
+
+struct sample { long rss_kb, heap_kb; long threads; int fds; };
+
+static struct sample sample(void)
+{
+ struct mallinfo2 mi = mallinfo2();
+ return (struct sample){ status_kb("VmRSS:"), (long)((mi.uordblks + mi.hblkhd) / 1024), status_kb("Threads:"), count_dir("/proc/self/fd") };
+}
+
+int main(int argc, char **argv)
+{
+ int iterations = argc > 1 ? atoi(argv[1]) : 5000;
+ char err[256];
+ uint32_t pa = ProxyBridge_AddProxy("a", PROXY_TYPE_SOCKS5, "127.0.0.1", 19080, "", "", err, sizeof err);
+ uint32_t pb = ProxyBridge_AddProxy("b", PROXY_TYPE_SOCKS5, "127.0.0.1", 19081, "bob", "pw", err, sizeof err);
+ ProxyBridge_AddRule("curl", "192.0.2.0/24", "*", RULE_PROTOCOL_TCP, RULE_ACTION_PROXY, pa, err, sizeof err);
+ ProxyBridge_AddRule("python3*", "192.0.2.0/24", "5300", RULE_PROTOCOL_UDP, RULE_ACTION_PROXY, pb, err, sizeof err);
+ ProxyBridge_AddRule("*", "*.example.test", "*", RULE_PROTOCOL_TCP, RULE_ACTION_PROXY, pa, err, sizeof err);
+ if (!ProxyBridge_Start()) { fprintf(stderr, "start failed\n"); return 2; }
+ sleep(1);
+
+ struct sample warm = { 0 };
+ int warm_at = iterations / 10;
+ for (int i = 0; i < iterations; i++) {
+ char hosts[64];
+ snprintf(hosts, sizeof hosts, "10.%d.%d.0/24;*.churn%d.test", i % 200, (i / 200) % 200, i % 7);
+ uint32_t r1 = ProxyBridge_AddRule("wget;curl", hosts, "80;443;8000-9000", RULE_PROTOCOL_BOTH, RULE_ACTION_PROXY, i % 2 ? pa : pb, err, sizeof err);
+ uint32_t r2 = ProxyBridge_AddRule("*chrome*", "198.51.100.0/24", "*", RULE_PROTOCOL_TCP, RULE_ACTION_BLOCK, 0, err, sizeof err);
+ ProxyBridge_EditRule(r1, "wget", "203.0.113.0/24", "*", RULE_PROTOCOL_TCP, RULE_ACTION_DIRECT, 0, err, sizeof err);
+ ProxyBridge_MoveRule(r2, 0);
+ ProxyBridge_DisableRule(r1);
+ ProxyBridge_EnableRule(r1);
+ uint32_t p = ProxyBridge_AddProxy("tmp", i % 2 ? PROXY_TYPE_HTTP : PROXY_TYPE_SOCKS5, "127.0.0.1", 19082, "", "", err, sizeof err);
+ ProxyBridge_EditProxy(p, "tmp2", PROXY_TYPE_SOCKS5, "localhost", 19083, "u", "p", err, sizeof err);
+ ProxyBridge_DeleteRule(r1);
+ ProxyBridge_DeleteRule(r2);
+ ProxyBridge_DeleteProxy(p);
+ if (i % 500 == 499) { ProxyBridge_Stop(); ProxyBridge_Start(); } /* full restart cycles */
+ if (i == warm_at) warm = sample();
+ if (i % 1000 == 999) { struct sample s = sample(); printf("iteration %d: rss=%ld KB heap in use=%ld KB threads=%ld fds=%d\n", i + 1, s.rss_kb, s.heap_kb, s.threads, s.fds); fflush(stdout); }
+ }
+ struct sample end = sample();
+ ProxyBridge_Stop();
+ long rss_growth = end.rss_kb - warm.rss_kb, heap_growth = end.heap_kb - warm.heap_kb;
+ printf("warm-up: rss=%ld heap=%ld KB threads=%ld fds=%d | end: rss=%ld heap=%ld KB threads=%ld fds=%d | growth: rss %ld KB, heap in use %ld KB\n",
+ warm.rss_kb, warm.heap_kb, warm.threads, warm.fds, end.rss_kb, end.heap_kb, end.threads, end.fds, rss_growth, heap_growth);
+ int sanitized = getenv("PB_SANITIZED") != NULL; /* sanitizer quarantines distort both numbers */
+ int ok = (sanitized || heap_growth < 256) && end.fds <= warm.fds + 2 && end.threads <= warm.threads + 1;
+ printf("%s\n", ok ? "PASS heap, descriptors and threads stay flat under churn" : "FAIL growth under churn");
+ return !ok;
+}
diff --git a/Linux/tests/e2e_nexus.sh b/Linux/tests/e2e_nexus.sh
index 0321421..b404d5e 100755
--- a/Linux/tests/e2e_nexus.sh
+++ b/Linux/tests/e2e_nexus.sh
@@ -63,7 +63,6 @@ sha_for() { python3 -c "$EXPECT_PY" "$1"; }
stdbuf -oL "$PB_DIR/ProxyBridge" --verbose 2 \
--proxy n1=socks5://127.0.0.1:1080 --proxy n2=socks5://nx:[email protected]:1081 \
- --rule "node:*:*:BOTH:DIRECT" \
--rule "curl:10.77.1.3:*:TCP:DIRECT" \
--rule "curl:10.77.1.4:*:TCP:BLOCK" \
--rule "curl:10.77.1.1:18701-18703:TCP:PROXY=n2" \
@@ -112,6 +111,13 @@ inlog $NX1LOG "[CONNECT] 10.77.1.6:18700" && ok " n1 carried the domain-matched
inlog $NX1LOG "[CONNECT] 10.77.1.53:53" && ok " n1 carried the DNS-over-TCP query" || bad " DNS/TCP did not go through n1"
grep -q "10.77.1.5 (app.example.test)" "$WORK/pb.out" && ok " connection log names the domain" || bad " no domain in the connection log"
+echo "== the proxy's own process is exempted automatically (no DIRECT rule for node exists)"
+inlog $NX2LOG "[CONNECT] 10.77.1.5:18700" && ok " nexus's own outbound connections were not sent back through itself" || bad " proxy loop"
+before=$(grep -cF "[CONNECT] 10.77.1.5:18700" "$NX2LOG")
+"$NODE" -e "require('net').connect(18700,'10.77.1.5').on('connect',function(){this.end()}).on('error',()=>{})"; sleep 1
+after=$(grep -cF "[CONNECT] 10.77.1.5:18700" "$NX2LOG")
+[ "$after" -gt "$before" ] && ok "another node process (not the proxy) is still proxied: exemption is per process, not per binary" || bad "unrelated node process bypassed the rules"
+
echo "== TCP: many connections, big transfers, integrity"
cpids=(); for i in $(seq 1 100); do (O http://10.77.1.1:18700/ > "$WORK/p$i.out") & cpids+=($!); done; wait "${cpids[@]}" 2>/dev/null
okc=$(grep -l "origin-1" "$WORK"/p*.out 2>/dev/null | wc -l); [ "$okc" = 100 ] && ok "100 parallel connections through n1" || bad "only $okc/100 parallel connections succeeded"
diff --git a/Linux/tests/e2e_rules.sh b/Linux/tests/e2e_rules.sh
index 38a9ebf..c13dcb4 100755
--- a/Linux/tests/e2e_rules.sh
+++ b/Linux/tests/e2e_rules.sh
@@ -57,6 +57,9 @@ start_pb \
--rule "python3*:203.0.113.160:*:BOTH:PROXY=a"
sleep 1
+echo "== diagnostics"
+grep -q "sends UDP to HTTP proxy 'c', which cannot carry UDP" "$WORK/pb.out" && ok "a UDP rule pointing at an HTTP proxy is reported in the log" || bad "no warning for UDP over an HTTP proxy"
+
echo "== host forms (process: curl)"
via "single IP" http://192.0.2.10/ A 192.0.2.10:80
via "CIDR /24" http://192.0.2.200/ A 192.0.2.200:80
diff --git a/Linux/tests/e2e_security.sh b/Linux/tests/e2e_security.sh
new file mode 100755
index 0000000..f550a42
--- /dev/null
+++ b/Linux/tests/e2e_security.sh
@@ -0,0 +1,58 @@
+#!/bin/bash
+# Security checks on the relay hand-off. Needs root, bpftool, python3. sudo tests/e2e_security.sh
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"; ROOT="$(dirname "$HERE")"
+PB_DIR="${PB_DIR:-$ROOT/output}"
+[ -x "$PB_DIR/ProxyBridge" ] && [ -f "$PB_DIR/libproxybridge.so" ] || { echo "Build first: (cd Linux && ./build.sh), or set PB_DIR"; exit 1; }
+BPFTOOL="${BPFTOOL:-bpftool}"; command -v "$BPFTOOL" >/dev/null || { echo "bpftool not found (set BPFTOOL)"; exit 1; }
+[ "$(id -u)" = 0 ] || { echo "run as root"; exit 1; }
+export LD_LIBRARY_PATH="$PB_DIR"
+WORK="$(mktemp -d)"; PLOG="$WORK/proxy.log"; : > "$PLOG"; PASS=0; FAIL=0
+ok() { echo " PASS $1"; PASS=$((PASS+1)); }
+bad() { echo " FAIL $1"; FAIL=$((FAIL+1)); }
+cleanup() { kill $FAKE $PB 2>/dev/null; wait 2>/dev/null; rm -rf "$WORK"; }
+trap cleanup EXIT
+
+python3 "$HERE/fake_proxies.py" "$PLOG" >/dev/null 2>&1 & FAKE=$!
+sleep 1
+stdbuf -oL "$PB_DIR/ProxyBridge" --verbose 1 --proxy a=socks5://127.0.0.1:19080 --rule "curl:192.0.2.1:*:TCP:PROXY=a" > "$WORK/pb.out" 2>&1 & PB=$!
+for _ in $(seq 40); do grep -q "ProxyBridge started" "$WORK/pb.out" && break; sleep 0.25; done
+RELAY=$(sed -n 's/.*relay tcp:\([0-9]*\) udp.*/\1/p' "$WORK/pb.out" | head -1)
+[ -n "$RELAY" ] || { echo "ProxyBridge did not start"; cat "$WORK/pb.out"; exit 1; }
+
+PORT=40123
+# plant the kind of entry the kernel creates for a redirected connection from 127.0.0.1:PORT -> 192.0.2.99:80 via proxy 1
+HEXKEY=$(python3 -c "import struct,socket;print(' '.join('%02x'%b for b in socket.inet_aton('127.0.0.1')+struct.pack('<I',$PORT)))")
+HEXVAL=$(python3 - <<PY
+import struct, socket
+v = bytes(10) + b"\xff\xff" + socket.inet_aton("192.0.2.99") + struct.pack("<HHI", 80, 1, 4242) + bytes([2, 6, 0, 0]) + struct.pack("<II4xQ", 0, 0, 0)
+print(" ".join("%02x" % b for b in v))
+PY
+)
+plant() { "$BPFTOOL" map update name by_port key hex $HEXKEY value hex $HEXVAL >/dev/null 2>&1; }
+planted() { "$BPFTOOL" map lookup name by_port key hex $HEXKEY >/dev/null 2>&1; }
+
+try_connect() { # source ip -> prints "closed" or "open"
+python3 - "$1" $PORT $RELAY <<'PY'
+import socket, sys
+src, port, relay = sys.argv[1], int(sys.argv[2]), int(sys.argv[3])
+s = socket.socket(); s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1); s.bind((src, port)); s.settimeout(3)
+try:
+ s.connect(("127.0.0.1", relay)); s.sendall(b"GET / HTTP/1.0\r\n\r\n"); d = s.recv(100)
+ print("closed" if not d else "open:" + d[:30].decode(errors="replace"))
+except (ConnectionError, socket.timeout) as e:
+ print("closed")
+PY
+}
+
+plant && planted && ok "test setup: a pending flow entry for 127.0.0.1:$PORT is in the kernel map" || { bad "could not plant the map entry (bpftool map update)"; exit 1; }
+r=$(try_connect 127.0.0.2); [ "$r" = closed ] && ok "a process connecting from 127.0.0.2 with the same source port is refused" || bad "foreign source address was served ($r)"
+grep -q "192.0.2.99" "$PLOG" && bad "the foreign connection reached the proxy" || ok "nothing reached the proxy for the foreign connection"
+planted && ok "the legitimate pending entry survived the attempt" || bad "the foreign attempt consumed the victim's entry"
+r=$(try_connect 127.0.0.1); sleep 1
+grep -q "A TCP 192.0.2.99:80" "$PLOG" && ok "the legitimate source (127.0.0.1) claims the entry and is proxied" || bad "legitimate connection was not proxied ($r)"
+planted && bad "the entry was not consumed" || ok "the entry is consumed after use (no replay)"
+r=$(try_connect 127.0.0.1); [ "$r" = closed ] && ok "a second connection with no pending entry is refused" || bad "relay served a connection without a pending entry ($r)"
+
+echo; echo "passed=$PASS failed=$FAIL"
+[ "$FAIL" = 0 ] || { echo "--- proxy log"; cat "$PLOG"; exit 1; }
diff --git a/Linux/tests/hookbench.sh b/Linux/tests/hookbench.sh
index 9bcb12c..767a8d7 100755
--- a/Linux/tests/hookbench.sh
+++ b/Linux/tests/hookbench.sh
@@ -7,7 +7,7 @@ export LD_LIBRARY_PATH="$PB_DIR"
IP=10.77.0.1 # alias on lo: local like loopback, but not caught by the implicit-loopback bypass
ip addr add $IP/32 dev lo 2>/dev/null
trap 'ip addr del $IP/32 dev lo 2>/dev/null' EXIT
-run() { for i in 1 2 3; do $HB tcp $IP 19555 20000; done; for i in 1 2 3; do $HB udp $IP 19556 1000000; done; }
+run() { for i in 1 2 3; do $HB udp $IP 19556 1000000; done; }
echo "### A: ProxyBridge not running"; run
start() { stdbuf -oL "$PB_DIR/ProxyBridge" "$@" > /tmp/pbbench.out 2>&1 & PB=$!; for _ in $(seq 40); do grep -q "ProxyBridge started" /tmp/pbbench.out && break; sleep 0.25; done; }
echo "### B: running, 20 rules for other programs (this binary: empty class -> immediate direct)"