feat: MXC sandbox integration for contained local code execution

[brandwe]

Overview

Implement Phase 1 of the MXC (Microsoft Execution Containers) sandbox integration to add contained local code execution capability to entrabot, pairing identity+attribution with OS-enforced containment.

Design Documents

• Design spec: docs/architecture/DESIGN-mxc-sandbox.md (merged in PR docs: MXC execution-container integration design (Phase 1 plan) #15)
• Platform research: docs/platform-learnings/mxc-windows-sandbox.md (merged in PR docs: MXC (Microsoft Execution Containers) platform research #14)

Phase 1 Scope (Build Now)

Process-level containment via MXC on macOS (Seatbelt) and Windows (processcontainer/AppContainer), driven from Python using the native MXC binary + JSON policy.

Implementation Tasks

• T1: sandbox/base.py — SandboxRunner protocol, dataclasses, error taxonomy
• T2: sandbox/policy.py — Policy builder with positive-allowlist clamping (backend-aware, fail-closed)
• T3: sandbox/binary.py — Binary resolution with SHA256 verification
• T4: sandbox/mac.py + windows.py — Platform-specific runners
• T5: mcp_server.py — run_code tool (opt-in via ENTRABOT_ENABLE_RUN_CODE=1)
• T6: scripts/setup_sandbox.sh + .ps1 — Binary provisioning with self-signing
• T7: sandbox/session.py — Phase 2 stub for future Entra-bound session isolation
• T8: Documentation — ADR-007 + TODOS.md update
• T9: Tests — Full tests/sandbox/ suite + opt-in adversarial integration tests
• T10: sandbox/linux.py — Optional, lower priority

Security Model (Hardened)

✅ Disabled by default (ENTRABOT_ENABLE_RUN_CODE=1 required)
✅ Positive-allowlist-only (no deniedPaths reliance; Windows doesn't support it)
✅ Backend-aware fail-closed (refuses policies with unenforceable primitives)
✅ Binary verification (SHA256 check before exec; untrusted → refuse to run)
✅ No secrets in sandbox (keychainAccess=false hardcoded, not overridable)
✅ Audit-first (fail-closed if audit fails)
✅ Structured argv, no shell (no shell-metachar escapes)
✅ Operator-set ceiling, LLM can only narrow (Learning #54)

Phase 2 (Stub Now, Build Later)

Entra-bound session isolation + Intune governance. Platform surfaces not GA yet (Windows Insider-only, Entra/Intune binding APIs unreleased). Ship seams:

• Backend.SESSION enum value
• session.py stub with Phase-2 requirements docstring
• identity_binding() hook

Success Criteria

• Full test suite passes (pytest -v && ruff check .)
• run_code tool not registered when env flag unset
• Adversarial integration tests pass (symlink escape blocked, secrets unreachable, network isolation enforced, timeout kills tree)
• Binary SHA256 verification prevents tampered binary execution
• Policy clamping prevents LLM from widening beyond operator ceiling
• ADR-007 documents the decision and Phase-2 gating

References

• Build 2026 announcement: Windows Developer Blog, Windows platform security for AI agents (2026-06-02)
• MXC OSS repo: github.com/microsoft/mxc
• Schema: 0.6.0-alpha
• Supersedes: TODOS.md "AppContainer sandbox production implementation" item

[brandwe]

🚀 Status: In Progress

Starting implementation on branch feat/mxc-sandbox-integration.

Current Phase

Phase 1: Process-level containment (macOS Seatbelt + Windows processcontainer)

Next Steps

1. T1: Implement sandbox/base.py protocol and dataclasses
2. T2: Policy builder with positive-allowlist clamping
3. Continue through T3-T10 following TDD

Will update with PRs as each component completes.