English | 简体中文 | 繁體中文 | Русский | Français | 日本語 | Deutsch

Original

Linux tool network guard

AgenticPenTest target validation is paired with a kernel firewall for local tool processes. The trusted application coordinator gates every tool behind a root-owned host broker. The broker creates a finite systemd service with IPAddressDeny=any, subtracts denied CIDRs from allowed CIDRs, verifies both cgroup ingress and egress BPF attachments, and moves the waiting launcher into that cgroup before releasing it. Descendant processes inherit this filter. Existing host-loopback targets retain their meaning with host networking.

Host setup

Requires Linux, unified cgroup v2, systemd system services, kernel cgroup-BPF, Python 3, util-linux setpriv and a non-root Node coordinator. A property being accepted by systemd is insufficient: every launch queries the kernel for both installed BPF hooks. An unsupported host fails with NETWORK_EXECUTOR_UNSUPPORTED; a tool does not run. Policy-protected tool executions require approval from the registered broker before a process can start.

Mount only the guard socket directory read-only into the workbench container using the optional network-guard overlay:

docker compose -f compose.yaml \
  -f deploy/docker/compose.network-guard.yaml up -d

The application remains non-root with dropped capabilities and no-new-privileges. Do not mount the Docker socket or delegate writable cgroup access to the container. The broker runs on the host; it is not an application server and accepts no arbitrary host command, path, environment or systemd property. Its only executable payload is a fixed /usr/bin/sleep guardian.

After creating or recreating the workbench container, find its Node process's host PID (not its init PID), then register that process from the checkout:

docker top YOUR_WORKBENCH_CONTAINER -eo pid,ppid,uid,comm,args
sudo python3 deploy/network-guard/install.py --caller-pid NODE_HOST_PID
sudo systemctl status agenticpentest-network-guard.service

For source deployment use the Node server's host PID. Refresh registration after every restart, including source service restarts. The installer copies the broker into a root-owned host location and atomically stores PID, process start time, UID, PID namespace and cgroup identity. Restarting without refreshing registration fails closed. Existing API sessions/data need no changes. Default limits are 32 simultaneous guards and 7200 seconds; --max-jobs and --max-seconds adjust bounded host limits. Per-tool defaults additionally set MemoryMax=1GiB, TasksMax=256 and CPUQuota=200% because moving a worker to its guard cgroup removes it from Docker's resource accounting. Use --memory-max-mib, --tasks-max and --cpu-quota-percent to set host-side bounds. Original seccomp, capabilities and no-new-privileges flags remain attached to the process. Rebinding intentionally terminates existing guarded jobs.

The service preserves its runtime directory across broker restarts so the read-only Docker bind continues to see the current socket. When upgrading an older installation that did not preserve this directory, reinstall the host guard, restart the workbench container once, then register its new Node PID. Check that System settings → Network restrictions reports the executor ready; an active systemd service alone does not prove the container can reach it.

Integration

const child = spawnNetworkGuarded(executable, argv, {
  cwd, env, stdio: ['ignore', 'pipe', 'pipe'], detached: true, timeout: 60000,
  networkPolicy: {
    restricted: true,
    allowedCIDRs: verifiedPolicy.allowedCIDRs,
    deniedCIDRs: verifiedPolicy.deniedCIDRs,
  },
});
child.on('error', handleExecutorError);
child.stdout.on('data', handleOutput);
await child.networkGuardReady;

Only trusted coordinator code supplies a verified policy. Never take it directly from HTTP/MCP input or a tool. Child processes can connect to the Unix socket but cannot authenticate as the registered coordinator, even with the same UID. The launcher's original stdin is untouched; parent input waits in its normal pipe until the tool starts. fd3 carries launch approval and is closed before starting the tool. Arbitrary inherited file descriptors and shell wrapping are rejected. Loader/preload environment hooks are restored only after the firewall exists; tool proxy variables are removed. No broker socket descriptor reaches a tool.

The coordinator holds its broker channel during execution. EOF, cancellation, coordinator death, a broker restart or the deadline stops the complete cgroup. Pass networkPolicy.expiresAt from a verified time-limited grant; the host also caps the unit lifetime to that timestamp, so long-running tools cannot outlive it. Processes cannot escape by forking or starting a new process group. The host broker authenticates every request with kernel SO_PEERCRED, and checks the launcher is a direct child in the same UID, PID namespace and original cgroup.

Network boundary

This firewall constrains IP peers reached directly by local tools. Application target/DNS/redirect validation must remain enabled. A permitted internal host that deliberately relays traffic is itself an internal IP peer; configure trusted proxies/tunnels with equivalent destination restrictions. Existing inherited IP sockets would bypass socket-creation rules, so this adapter accepts only normal stdio pipes/inherit/ignore and opens tool sockets after approval. Remote execution needs a separately trusted remote guard; do not imply this host's cgroup protects an SSH server, WebShell or another machine. Host administrators can modify their own kernel/application code; this is an enforcement boundary for the managed runtime, not copy protection against its administrator.

Verification

node tests/network-guard.mjs
# Isolated real host enforcement; requires passwordless sudo:
node tests/network-guard.mjs --real
# Static installer contract, followed by isolated real Docker bind regression:
node tests/network-guard-mount.mjs
node tests/network-guard-mount.mjs --real --image YOUR_INSTALLED_WORKBENCH_IMAGE

The real test temporarily adds a documentation-only address to loopback, verifies an unrestricted control can reach its TCP/UDP echo servers, then proves the guarded tool and its descendants cannot. It also tests allowed loopback access, proxy-environment removal, wrong-caller rejection, no execution before approval and cancellation cleanup. It removes its own alias and broker. No Internet target or production workspace is used.

Systemd reference: IP address access lists.

---

Complete source document, translated with offline machine assistance where needed. Code and identifiers remain verbatim. Original legal and license texts prevail. Translation corrections are welcome through Issues.