Jason Woltje
d5a1791dc5
All checks were successful
ci/woodpecker/push/ci Pipeline was successful
Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>
61 lines
2.9 KiB
Markdown
61 lines
2.9 KiB
Markdown
# Chroot Agent Sandboxing — Process Isolation for Agent Tool Execution
|
|
|
|
> **Status:** Stub — deferred. Referenced from `2026-03-15-agent-platform-architecture.md` (Phase 7 Workspaces → Chroot Agent Sandboxing).
|
|
> Implement after Workspaces (P8-015) is complete. Requires workspace directory structure and `WorkspaceService` to be operational.
|
|
|
|
**Date:** 2026-03-15
|
|
**Packages:** `apps/gateway`
|
|
|
|
---
|
|
|
|
## Problem Statement
|
|
|
|
Agent sessions can use file, git, and shell tools. Path validation in tools is defense-in-depth but insufficient alone — an agent with shell access can run `cat /opt/mosaic/.workspaces/other_user/...` and bypass gateway RBAC.
|
|
|
|
Chroot provides OS-level enforcement: tool processes literally cannot see outside their workspace directory.
|
|
|
|
---
|
|
|
|
## Design (Sweet Spot)
|
|
|
|
Chroot strikes the balance between full container isolation (too heavy per session) and path validation only (escape-prone):
|
|
|
|
- Gateway spawns tool processes inside a chroot rooted at the session's `sandboxDir`
|
|
- Requires `CAP_SYS_CHROOT` capability on the gateway process (not full root)
|
|
- Chroot environment provisioned by `WorkspaceService` on workspace creation (minimal deps: git, shell utils, language runtimes as needed)
|
|
- Alternative for Docker deployments: Linux `unshare` namespaces (lighter, no chroot env setup)
|
|
|
|
---
|
|
|
|
## Scope (To Be Designed)
|
|
|
|
- [ ] Chroot environment provisioning — `WorkspaceService.provisionChroot(workspacePath)` on project creation
|
|
- [ ] Minimal chroot deps — identify required binaries/libs per tool type (file: none; git: git binary; shell: bash, common utils)
|
|
- [ ] Gateway capability — document `CAP_SYS_CHROOT` requirement; Dockerfile and docker-compose.yml changes
|
|
- [ ] Tool process spawning — modify `createShellTools`, `createFileTools`, `createGitTools` to spawn via chroot wrapper
|
|
- [ ] Docker alternative — `unshare --mount --pid --user` namespace wrapper as fallback for environments without chroot capability
|
|
- [ ] Defense-in-depth layering — chroot + path validation both active; neither alone is sufficient
|
|
- [ ] Chroot cleanup — integrate with `SessionGCService` / workspace deletion
|
|
- [ ] AppArmor/SELinux profiles (v2) — restrict gateway process file access patterns for multi-tenant hardening
|
|
|
|
---
|
|
|
|
## Security Constraints
|
|
|
|
- What lives **inside** the chroot (agent-accessible): workspace files, git repo, language runtimes
|
|
- What lives **outside** the chroot (gateway-only, never agent-accessible): Valkey connection, PG connection, other users' workspaces, gateway config, OTEL endpoint, credentials
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
- Workspaces (P8-015) — chroot is rooted at workspace directory; workspace must exist first
|
|
- Tool hardening (P8-016) — path validation stays active as defense-in-depth alongside chroot
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- Original design context: `docs/plans/2026-03-15-agent-platform-architecture.md` → "Chroot Agent Sandboxing" section
|
|
- Current tool implementations: `apps/gateway/src/agent/tools/`
|