feat: migrate Linux sandbox to bwrap, add doctor command

[machado144]

Summary

• Phase 1: Replaces the unshare + shell-script sandbox with Bubblewrap (bwrap) for the non-network path. deny_read, deny_exec, and config-dir protection are now declarative bind mounts — no shell escaping, no injection risk, symlinks resolved automatically.
• Phase 2: Network-filtered path (allow_net) no longer uses nested unshare --net inside bwrap's user namespace (fails with EPERM on modern kernels). Instead, bwrap's --unshare-net + --info-fd are used: Go reads the child PID from the info pipe and launches slirp4netns from host-side. Adds --uid 0 --gid 0 --cap-add cap_net_admin,cap_sys_admin so iptables (nf_tables) works inside bwrap (bwrap drops all caps by default; nf_tables requires UID 0 in the user namespace).
• Phase 3: aigate doctor command — checks bwrap, slirp4netns, setfacl, and user-namespace availability, reports versions/paths, and shows exactly which isolation mode will be active.
• Fix: shellEscape was concatenating args with raw spaces; fixed with shellQuote() (single-quote escaping).

Root cause details (Phase 2 EPERM)

Inside bwrap's user namespace, unshare --net fails because bwrap drops all effective capabilities and maps the caller as UID 1000 (not root). Creating a network namespace via unshare --net alone requires UID 0 in the user namespace for nf_tables. The fix uses bwrap's own --unshare-net flag so the namespace is created in the correct context, and adds the two minimal capabilities (cap_net_admin, cap_sys_admin) needed for iptables and bind-mount setup inside the inner script.

Test plan

• go test ./... -count=1 — 157 tests pass
• go test ./... -short -count=1 — 156 pass (real-exec test correctly skipped)
• go vet ./... — clean
• aigate doctor — shows bwrap v0.10.0, slirp4netns v1.3.1, isolation mode: bwrap + slirp4netns
• aigate run -- true — exits 0, no unshare: unshare failed error
• aigate run -- sh -c 'python3 -c "import urllib.request; urllib.request.urlopen(\"https://api.github.com\")"' — HTTP 200 (allowed host)
• aigate run -- sh -c 'python3 -c "import urllib.request; urllib.request.urlopen(\"https://example.com\")"' — connection rejected (blocked host)

🤖 Generated with Claude Code

[github-actions]

StructLint — All checks passed

76 rules validated against .structlint.yaml. No violations found.

_{View full run · Powered by StructLint}

[github-actions]

Core Changes

• Introduced a new aigate doctor command to check sandbox prerequisites and report the active isolation mode on Linux and macOS.
• Migrated the Linux sandbox implementation from shell-script-based unshare to Bubblewrap (bwrap) for improved robustness and security. This includes declarative bind mounts for deny_read, deny_exec, and config directory protection.
• Reworked the network-filtered sandbox on Linux to use bwrap's native --unshare-net and --info-fd in conjunction with slirp4netns, resolving an EPERM issue encountered with nested unshare --net in bwrap's user namespace.
• Fixed a shell escaping vulnerability in shellEscape by introducing shellQuote to correctly handle arguments containing shell metacharacters.

---

Concerns

None. The changes significantly improve the robustness and security of the Linux sandbox implementation and add valuable diagnostic capabilities.

---

Verdict

Approve: The changes are well-implemented, address critical issues, and enhance the overall stability and user experience of the application. The new doctor command is a great addition for diagnostics, and the migration to bwrap for Linux sandboxing is a significant improvement.

---

Code review performed by GEMINI - gemini-2.5-flash.