mosaicstack/stack

Fork 0

Files

Jason Woltje 68073c6113

ci/woodpecker/pr/ci Pipeline was successful

Details

ci/woodpecker/push/ci Pipeline was successful

Details

docs: augment agent platform architecture plan + task breakdown

- Augmented 2026-03-15-agent-platform-architecture.md with 6 missing
  sections: Teams Architecture, REST Route Specifications, /provider
  OAuth flow (URL+clipboard), preferences mutable migration, Test
  Strategy (per-task), and Phase Execution Order (wave plan)
- Created spin-off plan stubs: gatekeeper-service.md,
  task-queue-unification.md, chroot-sandboxing.md
- Added P8-007 through P8-019 to TASKS.md (13 new tasks)
- Created Gitea issues #160-#172, Phase 8 milestone ms-165
- Updated MISSION-MANIFEST.md (Phase 8 in-progress)
- Updated scratchpad with session 14 decisions

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-15 20:27:44 -05:00

2.9 KiB

Raw Blame History

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/

2.9 KiB Raw Blame History