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

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:

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:

#!/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 $?

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.