Pin the Roots or Don't Merge: A Fail-Closed Agent Egress Checklist

A developer has published a fail-closed egress checklist for teams shipping coding agents into shared CI or shared machines, requiring every filesystem root, network host, and executable an agent can reach to be named in a committed allowlist before a merge is permitted. The proposal pairs an agent-egress.yml manifest with a CI validator and trace comparator that fail the pipeline when the manifest is missing, the trace is absent or out of bounds, or secret-like values appear in tool arguments. The author frames the checklist as a proposed local gate to be tested on a sample manifest before adoption in a protected branch.

You should not merge an agent change until every filesystem root, network host, and executable it can reach is named in a committed allowlist. If that file is missing, the pipeline fails. That is the whole policy. An LLM in a pull request is not the risk by itself. The risk is the tools you wired to it. Shell. HTTP. MCP. Those tools turn a suggestion into a process with credentials, a working directory, and a network stack. This checklist is for teams shipping coding agents into shared CI or a shared box. Copy it. Fail closed. Do not treat a green unit test as proof that the agent stayed inside the repo. You are not shipping a prompt. You are shipping a runtime. If the agent can run a command, it can read files the reviewer never opened. If it can fetch a URL, it can leave your VPC with a token sitting in an environment variable. If it can call an MCP server, it can grow new verbs the next time that server updates. Name the boundary. Then prove the run stayed inside it. Treat agent egress like a production firewall change: Do not negotiate item 4 in Slack. If the packet is incomplete, the merge is incomplete. Use this as a PR template. Every box needs an artifact, not a vibe. agent id is stable across PRs not tmp or test . If the id changes, treat it as a new service. New service, new review. workspace roots lists every directory the agent may read or write. $HOME . No /tmp unless a job-scoped directory is created in CI and destroyed after. A root of . is acceptable for a docs bot. It is not acceptable for an agent that also mounts secrets. binaries is an allowlist of executable basenames, not $PATH . bash -lc , sh -c , python -c are either forbidden or require a second reviewer. npm , pip , curl | sh are denied unless the PR is specifically about dependency changes. You do not need a perfect sandbox to start. You need a list you can grep. network.mode is deny or allowlist . Never open . .cloud . Host allowlists are not a full network policy. They are the minimum you can enforce in application CI. env allow names every variable the process may read. SECRET , TOKEN , PASSWORD , PRIVATE are denied unless explicitly listed. If a secret appears in a tool argument, the run is a failed run. Rotate. Then fix the allowlist. max steps is set. max wall clock sec is set. max tool calls per step is set. Unbounded loops are not “research mode” in a merge pipeline. They are an open invoice and an open shell. If the server can add a tool without a digest change, it does not belong in this pipeline. A checklist without files is theater. Require these paths, or fail: | Gate | Required file | Fail closed when | |---|---|---| | Manifest present | agent-egress.yml | file missing or empty | | Schema valid | CI validator log | unknown keys, empty lists while a capability is enabled | | Trace exists | artifacts/agent-trace.jsonl | no file, or zero tool events while tools were enabled | | Trace in bounds | CI comparator log | path, host, binary, or env outside the manifest | | Bounds held | trace summary | max steps or wall clock exceeded | | Secret scan | CI log | secret-like names in argv or stdout | Store the trace next to the manifest. Reviewers should be able to open one folder and see both the policy and the run. Label: this is a proposed local gate. Run it on a sample manifest before you trust it in a protected branch. agent-egress.yml : version: 1 agent id: docs-triage owner: platform-ci workspace roots: - . write roots: - ./artifacts binaries: - git - python3 network: mode: allowlist hosts: - api.github.com env allow: - GITHUB TOKEN - CI max steps: 20 max wall clock sec: 180 max tool calls per step: 3 mcp servers: ci/check agent egress.py : bash /usr/bin/env python3 """Fail closed if the agent egress manifest is missing or incomplete.""" from future import annotations import argparse import sys from pathlib import Path try: import yaml except ImportError: print "MISSING DEP: PyYAML is required", file=sys.stderr sys.exit 2 REQUIRED = "version", "agent id", "owner", "workspace roots", "write roots", "binaries", "network", "env allow", "max steps", "max wall clock sec", "max tool calls per step", "mcp servers", FORBIDDEN ROOT MARKERS = "$HOME", "~", "/tmp", "/var", "C:\\" def fail msg: str - None: print f"FAIL: {msg}", file=sys.stderr sys.exit 1 def main - None: parser = argparse.ArgumentParser parser.add argument "--manifest", default="agent-egress.yml" parser.add argument "--fail-closed", action="store true", default=True args = parser.parse args path = Path args.manifest if not path.is file : fail f"manifest not found: {path}" raw = path.read text encoding="utf-8" .strip if not raw: fail "manifest is empty" data = yaml.safe load raw if not isinstance data, dict : fail "manifest must be a mapping" missing = k for k in REQUIRED if k not in data if missing: fail f"missing keys: {missing}" if not data "agent id" or data "agent id" in {"tmp", "test", "default"}: fail "agent id must be stable and non-placeholder" roots = data "workspace roots" if not roots: fail "workspace roots must not be empty" for root in roots: if not isinstance root, str or any m in root for m in FORBIDDEN ROOT MARKERS : fail f"refusing root: {root r}" writes = data "write roots" if not writes: fail "write roots must not be empty" binaries = data "binaries" if not binaries: fail "binaries allowlist must not be empty" if any b in {"bash", "sh", "zsh", "cmd", "powershell"} for b in binaries : fail "shell binaries require a separate exception PR" network = data "network" if network.get "mode" not in {"deny", "allowlist"}: fail "network.mode must be deny or allowlist" if network "mode" == "allowlist" and not network.get "hosts" : fail "allowlist mode requires hosts" if int data "max steps" < 1 or int data "max wall clock sec" < 1: fail "loop bounds must be positive" print f"PASS: {path} agent id={data 'agent id' }" if name == " main ": main Run it locally the same way CI will: python3 -m pip install pyyaml python3 ci/check agent egress.py --manifest agent-egress.yml --fail-closed echo $? expected: 0 on a complete file, 1 on any gap CI job sketch: name: agent-egress-gate on: pull request: paths: - "agent-egress.yml" - "ci/check agent egress.py" - " / agent " jobs: gate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: python3 -m pip install pyyaml - run: python3 ci/check agent egress.py --manifest agent-egress.yml --fail-closed Keep the path filter honest. If your agent code lives outside agent , drop the filter. A skipped gate is an open gate. The manifest is policy. The trace is evidence. You still need a comparator. Proposed event shape one JSON object per line : {"ts": "2026-09-11T12:00:00Z", "type": "tool", "name": "run terminal cmd", "binary": "git", "argv": "status" , "cwd": ".", "host": null} Comparator rules you can implement in a short script: cwd must resolve under binary must be in host must be in network.hosts when not null. <= max steps . type fails. Do not ignore fields you do not understand. If you cannot produce a trace, you cannot merge. “The vendor UI does not export logs” is a vendor problem, not a reason to skip the gate. Drafting the first allowlist from a recorded trace is tedious. A coding assistant is useful there: it can turn a JSONL file into a candidate YAML. It is not useful as the gate. Disclosure: This article was prepared as part of MonkeyCode's product outreach. If you need a throwaway workspace to generate those traces without pointing the agent at production, MonkeyCode’s free model access and free server option are enough to iterate on the manifest. Keep the validator in your CI. The model does not get a vote. This checklist does not replace OS sandboxes, seccomp, or a real egress proxy. Path allowlists lose if the process can follow a symlink you did not resolve. Host allowlists lose if a listed host issues a redirect you do not follow in the comparator. MCP pins lose if the server mutates tools behind the same digest. Loop bounds do not stop a single dangerous command. They stop a runaway. You still need binary and argv policy for the dangerous command. The validator above does not parse traces. Ship the comparator before you claim production readiness. Until then, label the gate manifest-only in the PR so reviewers know what they are not seeing. network.mode: open . Ask one question: if this agent process is still running in ten minutes, which roots, hosts, and binaries can it still touch? If you cannot answer from a file in the repo, do not merge. Pin the roots. Attach the trace. Fail closed.