Руководство по интеграции
### Введение
В автономных системах на базе ИИ-агентов выполнение генерируемого кода несет критические риски безопасности (удаление файлов, утечка API-ключей, ботнет-активность). Традиционный подход совмещения проверки кода (статический анализ) и запуска (песочница) в одном модуле создает хаос, повышает накладные расходы и усложняет аудит. **ReviewerSandboxDecoupled** разделяет эти зоны на статический шлюз (ReviewerGate) и динамическую среду исполнения (SandboxPreflight), связывая их строгим JSON-контрактом.
### Разделение обязанностей (Separation of Concerns)
1. **ReviewerGate (Статический анализатор)**:
* Анализирует текст скрипта перед запуском без его фактического выполнения.
* Проверяет AST (абстрактное синтаксическое дерево) на запрещенные вызовы (`os.system`, `subprocess`, `rmtree`).
* Выявляет признаки обфускации и bypass-команд (скрытые shell-редиректы `>`).
* Выносит вердикт: `PASS`, `REVIEW_REQUIRED`, `DENY`.
2. **SandboxPreflight (Динамическая песочница)**:
* Запускает код в изолированной легковесной среде (gVisor / Firecracker / Docker-контейнер).
* Ограничивает доступ к файловой системе (read-only root), сети (запрет внешних запросов кроме разрешенного списка) и системным вызовам (seccomp-фильтрация).
* Мониторит поведение процесса в реальном времени, блокируя подозрительную активность.
* Выносит вердикт: `ADMIT`, `QUARANTINE`, `DENY`.
### JSON-Контракт Вердикта
Оба шлюза обмениваются структурированным вердиктом по схеме `ReviewerSandboxVerdictContract`. Контракт содержит:
* `subject`: Хеш SHA256 проверяемого скрипта/запроса.
* `reviewer`: Решение статического анализатора, список проверок и затребованные права.
* `sandbox`: Решение песочницы, профиль изоляции и фактические лимиты ресурсов.
* `final`: Итоговое решение системы (`ALLOW`, `QUARANTINE`, `DENY`) и следующее автоматическое действие.
Это позволяет снизить ложные срабатывания (false positives): если статический анализатор сомневается в коде, динамическая песочница может запустить его в режиме повышенной изоляции (`ADMIT_RESTRICTED`), отслеживая реальные вызовы.
В автономных системах на базе ИИ-агентов выполнение генерируемого кода несет критические риски безопасности (удаление файлов, утечка API-ключей, ботнет-активность). Традиционный подход совмещения проверки кода (статический анализ) и запуска (песочница) в одном модуле создает хаос, повышает накладные расходы и усложняет аудит. **ReviewerSandboxDecoupled** разделяет эти зоны на статический шлюз (ReviewerGate) и динамическую среду исполнения (SandboxPreflight), связывая их строгим JSON-контрактом.
### Разделение обязанностей (Separation of Concerns)
1. **ReviewerGate (Статический анализатор)**:
* Анализирует текст скрипта перед запуском без его фактического выполнения.
* Проверяет AST (абстрактное синтаксическое дерево) на запрещенные вызовы (`os.system`, `subprocess`, `rmtree`).
* Выявляет признаки обфускации и bypass-команд (скрытые shell-редиректы `>`).
* Выносит вердикт: `PASS`, `REVIEW_REQUIRED`, `DENY`.
2. **SandboxPreflight (Динамическая песочница)**:
* Запускает код в изолированной легковесной среде (gVisor / Firecracker / Docker-контейнер).
* Ограничивает доступ к файловой системе (read-only root), сети (запрет внешних запросов кроме разрешенного списка) и системным вызовам (seccomp-фильтрация).
* Мониторит поведение процесса в реальном времени, блокируя подозрительную активность.
* Выносит вердикт: `ADMIT`, `QUARANTINE`, `DENY`.
### JSON-Контракт Вердикта
Оба шлюза обмениваются структурированным вердиктом по схеме `ReviewerSandboxVerdictContract`. Контракт содержит:
* `subject`: Хеш SHA256 проверяемого скрипта/запроса.
* `reviewer`: Решение статического анализатора, список проверок и затребованные права.
* `sandbox`: Решение песочницы, профиль изоляции и фактические лимиты ресурсов.
* `final`: Итоговое решение системы (`ALLOW`, `QUARANTINE`, `DENY`) и следующее автоматическое действие.
Это позволяет снизить ложные срабатывания (false positives): если статический анализатор сомневается в коде, динамическая песочница может запустить его в режиме повышенной изоляции (`ADMIT_RESTRICTED`), отслеживая реальные вызовы.