Add agentjail implementation: sandbox, proxy, relay, CLI, tests and CI/CD

[Copilot]

Implements the complete agentjail package from scratch. The repository previously contained only a README.md.

Architecture

Network isolation is achieved through a layered approach:

1. Filtering HTTP proxy (pkg/agentjail/tinyproxy.go) — A Go HTTP/HTTPS proxy (CONNECT + plain HTTP) that listens on a Unix socket on the host filesystem. Enforces a domain allowlist (nil = allow all public destinations) and unconditionally blocks private/link-local IP ranges (RFC 1918, 169.254.0.0/16, loopback, ULA, link-local IPv6).

2. TCP→Unix relay (pkg/agentjail/relay.go) — Uses socat to bridge 127.0.0.1:3128 inside the sandbox to the proxy's Unix socket. Unix sockets are accessible across network namespaces via the shared filesystem bind-mount. socat is used to avoid any dependency on an external language runtime (Python, Node, JVM, etc.). The relay uses exec.CommandContext so the socat process is automatically killed when the context is cancelled.

3. Sandbox (pkg/agentjail/sandbox.go) — Runs the command via sudo bwrap --unshare-net --unshare-pid. Sets up iptables (IPv4 allows only TCP to loopback port 3128) and ip6tables (drops everything). Executes the command as nobody to prevent privilege escalation via sudo.

4. Public API (pkg/agentjail/run.go) — Run(ctx, allow, command) orchestrates the proxy, relay, and sandbox.

5. CLI (cmd/agentjail/main.go + cmd/agentjail/flags.go) — Command-line wrapper with --allow PATTERN flags. The multiFlag helper type lives in its own flags.go file.

Test files

File	Coverage
cmd/agentjail/security_test.go	DNS blocking, direct IP bypass, IPv6 bypass, cloud metadata, local network probing, redirect-to-forbidden, Python socket escape, netcat probe, wget/perl/dig table suite
cmd/agentjail/curl_test.go	Allowlist enforcement; skips gracefully when test hosts are DNS-unreachable
cmd/agentjail/agent_test.go	Cursor agent smoke test; skips when binary not installed (exit 127) or API unreachable (exit 1)
cmd/agentjail/escape_test.go	sudo -n true must fail inside the sandbox
pkg/agentjail/network_jail_test.go	Unit tests for the private-address helper and basic sandbox behaviour

CI/CD

File	Purpose
.github/workflows/go.yml	CI: runs go build and go test on every push and pull request to main
.github/workflows/release.yml	Release: on tag push, runs go vet + go test, builds Linux amd64/arm64/386 binaries (agentjail is Linux-only due to bwrap/iptables), generates checksums.txt, and publishes a GitHub Release via softprops/action-gh-release

Notable implementation details

• socat relay: The relay has no dependency on any language runtime. socat starts the listening TCP port synchronously before accepting connections, so only a short fixed delay is needed before entering the sandbox.
• I/O pipe leak fix: sudo PAM helpers briefly hold the write-end of go test's stdout pipe after the main process exits. Fixed by capturing subprocess output to a bytes.Buffer with WaitDelay = 3s, then falling back to ProcessState.ExitCode() when ErrWaitDelay is returned for a successful exit.
• bufio.Reader reuse: A single reader is created per proxy connection so that data buffered while parsing the HTTP request is not lost when switching to raw tunnel copying after a CONNECT response.
• --unshare-pid: Private PID namespace ensures all sandbox processes are reaped when bwrap exits.

Requirements

bwrap (bubblewrap), socat, sudo, and iptables/ip6tables must be available on the host. On Debian/Ubuntu: sudo apt-get install bubblewrap socat.

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[alexec]

@copilot Did you add and commit and push to code?

[Copilot]

@copilot Did you add and commit and push to code?

Yes – the full implementation has been committed and pushed in commit c7cc92d (with a follow-up fix at bfed3b4).

Here's what was added:

File	Purpose
pkg/agentjail/tinyproxy.go	Filtering HTTP/HTTPS proxy (CONNECT + plain HTTP) listening on a Unix socket; enforces the domain allowlist; always blocks private/link-local IPs
pkg/agentjail/relay.go	Embedded Python3 TCP→Unix relay script that bridges 127.0.0.1:3128 inside the sandbox to the host proxy socket
pkg/agentjail/sandbox.go	runInSandbox: sudo bwrap --unshare-net --unshare-pid, iptables/ip6tables lockdown, relay startup, command execution as nobody
pkg/agentjail/run.go	Run(ctx, allow, command) – the public API
cmd/agentjail/main.go	CLI with --allow PATTERN flags
All *_test.go files	Security/bypass tests, curl allowlist tests, escape test, agent test

All security-blocking tests pass; internet-dependent tests skip gracefully in this restricted environment.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• httpbin.org
  • Triggering command: `/usr/bin/python3 python3 -c
    import socket, threading

sock_path = '/tmp/agentjail-test2-4445/proxy.sock'

s = socket.socket(socket.AF_UNIX)
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind(sock_path)
s.listen(50)
print('proxy ready', flush=True)

def pipe(src, dst):` (dns block)

• Triggering command: /usr/bin/curl curl -sSf --max-time 5 REDACTED (dns block)
• Triggering command: /usr/bin/host host httpbin.org (dns block)
• https://api.github.com/
  • Triggering command: /usr/bin/curl curl -sSf --max-time 5 REDACTED (http block)
• microsoft.com
  • Triggering command: /usr/bin/nslookup nslookup microsoft.com 168.63.129.16 (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[alexec]

@copilot add a README. I'm not clear why you made so many changes vs the original example. Please explain.

[Copilot]

@copilot add a README. I'm not clear why you made so many changes vs the original example. Please explain.

README added in 878dd47.

Regarding why there are many files: the original repo only had README.md. The problem statement asked to implement the full package with sandbox, proxy, and test cases — so the code had to be written from scratch. Here's the breakdown:

File	Why it exists
pkg/agentjail/tinyproxy.go	Go HTTP/HTTPS filtering proxy (the "jail" mechanism)
pkg/agentjail/relay.go	socat relay bridging TCP inside the sandbox to the proxy's Unix socket
pkg/agentjail/sandbox.go	bwrap sandbox setup with iptables network lockdown
pkg/agentjail/run.go	Public Run() API wiring the three pieces together
cmd/agentjail/main.go + flags.go	CLI entry point
*_test.go	Tests specified in the PR description

[alexec]

Look at https://github.intuit.com/kitproj/jira-cli for how to set-up GitHub Actions to verify the code changes and release. Add the correct files (you might wish to just to copy their files and change the names).

[Copilot]

@copilot Did you add and commit and push to code?

Yes — all code was committed and pushed in the earlier commits on this branch. The latest commit is 531c207.

Look at https://github.intuit.com/kitproj/jira-cli for how to set-up GitHub Actions to verify the code changes and release. Add the correct files (you might wish to just to copy their files and change...

Added in 531c207, modelled on kitproj/jira-cli:

• .github/workflows/go.yml — runs go build + go test on every push/PR to main
• .github/workflows/release.yml — on tag push: runs go vet, go test, builds Linux amd64/arm64/386 binaries (agentjail is Linux-only due to bwrap/iptables), generates checksums.txt, then publishes a GitHub Release via softprops/action-gh-release@v2