Enterprise AI Agent Sandbox

A security framework for plugging sandboxed execution into agentic AI workflows. Drop the connector into any folder where Claude Code, Codex, Cursor, or other AI agents run — all privileged commands are escalated to a human approver, executed outside the agent's context, and the output is fed back to the model so it can continue.

Архитектура

• Хуки Claude Code перехватывают вызовы инструментов, передают привилегированные операции человеку-одобрителю и возвращают захваченный вывод внутри решения deny, чтобы инструмент никогда не выполнялся с привилегиями агента.

• MCP-сервер (run_privileged, check_request, sandbox_status) обеспечивает тот же цикл через Model Context Protocol — работает с Claude Code, Codex, Cursor, Windsurf.

• Очередь папок (.sandbox/escalations/) — это шина: атомарные файловые операции (os.replace, os.rename) координируют одобрение между четырьмя независимыми процессами (подпроцесс хука, MCP-сервер, терминал одобрителя, панель управления).

• Механизм политик классифицирует команды оболочки, записи файлов, сетевые запросы и чтения — четыре триггера эскалации с человеком в цикле как высшим уровнем.

Related MCP server: Approval Gate

Быстрый старт

# Install the connector
python -m pip install -e ".[dev]"

# Initialize a folder
sandbox init . --claude --mcp

# In one terminal: watch for escalations
sandbox watch .

# In another: use Claude Code or the MCP tools as normal
# Privileged commands will appear in the `watch` terminal for approval

Как это работает

1. Агент пытается выполнить команду — хук PreToolUse от Claude Code перехватывает её.

2. Хук классифицирует и эскалирует — команды оболочки, не входящие в белый список, попадают в очередь папок.

3. Человек одобряет в sandbox watch — одобритель выполняет команду вне агента.

4. Вывод возвращается модели — обёрнут в permissionDecision:"deny" с stdout в строке причины.

5. Агент продолжает — он получил результат, но сам никогда не имел привилегий.

Канал MCP работает аналогично: run_privileged возвращает результат инструмента с захваченным выводом.

Вехи

• ✅ Веха 0 — Основы (исправление ошибок, ограничение путей, восстановление аудита)

• ✅ Веха 1 — Цикл (хук PreToolUse, очередь папок, одобрение через CLI)

• ✅ Веха 2 — Канал MCP (run_privileged, check_request, sandbox_status)

• ✅ Веха 3 — Запись папки (восстанавливаемые оригиналы, цепочка аудита, PostToolUse)

• ✅ Веха 4 — Другие триггеры (полный классификатор, запомненные решения, контекст SessionStart)

• ✅ Веха 5 — Поверхности (REST-маршруты, удаление, документация)

Все вехи завершены. См. docs/CONNECTOR.md для полного технического описания.

Тестирование

# Run all tests (117 passing)
python -m pytest -q

# Test the loop with a real hook subprocess and background approver
python -m pytest tests/integration/test_connector_loop.py -v

# Test the MCP channel
python -m pytest tests/integration/test_mcp_tools.py -v

Структура проекта

src/sandbox/
├── connector/           # Folder connector (queue, hooks, policy, MCP)
├── launcher/            # M1 jailed launcher (job objects, jail, shims)
├── audit/               # Chained audit log with tamper detection
├── broker/              # Non-AI privilege executor
├── fs/                  # Path containment and validation
├── agents/              # Multi-agent sandbox orchestrator
├── api/                 # FastAPI routes and WebSocket
└── ...

Ключевые проектные решения

• Папка — это шина: Атомарные файловые операции на NTFS координируют четыре независимых процесса (без состояния в памяти, без открытых портов, переживает перезапуски)

• deny переносит вывод: Инструмент никогда не выполняется в агенте; вывод вставляется обратно в строку причины

• Одобрение через CLI в первую очередь: Без графического интерфейса, работает через SSH, без зависимости от браузера

• Отказ по умолчанию: Внутренние ошибки блокируют, а не молча разрешают

• Неудаляемая самозащита: .sandbox/** в запретах на запись и \.sandbox в запретах оболочки повторно внедряются при каждой загрузке политики — агент не может удалить свои собственные ограничения

Лицензия

[Будет определено]