docs: A1 generalization (0 analogs of max_workers=0) + ADR-0001 sandbox threat model draft

Author: MSCodeBase Agent

AGENT_DIARY.md

@@ -19,6 +19,7 @@
 **Fix:** `max(1, min(4, (os.cpu_count() or 4) // 2))` + регрессионный тест test_run_survives_single_cpu_host (валидирован: без фикса — ровно ValueError, stash-прогон).
 **Guard:** тест; безопасный паттерн уже был в resource_monitor.py:133.
 **Pattern:** NEW (P-003 — отсутствие нижней границы воркеров при делении числа ядер пополам).
+**Обобщение (§3.5):** grep по src/ — cpu_count: 4 места (runner:261 FIXED; resource_monitor:133 `max(1, ...)` SAFE; llama_install:95/810 — конфиг-значение cores, не делитель SAFE). ThreadPoolExecutor: 7 мест, все max_workers фиксированы ≥1 или защищены (error_handler:58=4; runner:502=1; health:49=1; agentic_search:551=1; engine:48=2; task_queue:78 default=2, единственный инстанциатор =2). ProcessPoolExecutor/multiprocessing как экзекуторы — 0. Аналогов уязвимого паттерна `min(N, cpu//2)` без `max(1, ...)`: **0** — P-003 закрыт как единичный экземпляр.
 **verified_from_clean_state:** ✅ да — полный pytest 762 passed, ruff clean; CI-прогон после push подтвердит.
 
 ## [2026-08-05 01:50] — Tech debt: subprocess text=True без encoding ×7 закрыт + пин ruff (DONE)

KNOWN_ISSUES.md

@@ -12,12 +12,19 @@
 
 ---
 
+## 2026-08-05 — A2: sandbox execute_script — модель угроз (ADR-0001, ждёт решения владельца)
+
+**Symptom:** внешний аудит: blacklist-модель sandbox принципиально обходима (чистый Python без OS-изоляции); вопрос — для какого класса ввода defense-in-depth достаточна.
+**Verdict:** обвязка аккуратна (AST + runtime __import__-перехват + минимальный env без os.environ — executor.py:306-321), но seccomp/namespaces нет. ast.Delete запрещён целиком (executor.py:73) — возможно ломает легитимный `del` локальной переменной.
+**Fix:** кода не меняли (Danger Zone). Создан docs/adr/0001-sandbox-threat-model.md (Draft) — варианты A: defense-in-depth (рекомендация), B: OS-изоляция (2-4 нед), C: гибрид с threat classifier.
+**Status:** 🟡 ждёт решения владельца (OPEN_QUESTION) | **Guard:** ADR-0001; executor.py не трогать до решения.
+
 ## 2026-08-05 — A1 (внешний аудит): ThreadPoolExecutor max_workers=0 на 1-CPU (FIXED)
 
 **Symptom:** `_max_workers = min(4, (os.cpu_count() or 4) // 2)` → на 1-CPU хосте `1//2 = 0` → `ThreadPoolExecutor(max_workers=0)` кидает ValueError → full reindex падает ДО парсинга (intel_trigger_reindex mode=full). Живые сценарии: VPS с 1 ядром, cgroup-ограниченный контейнер CI, WSL.
 **Root Cause:** отсутствие нижней границы воркеров при делении cpu_count на 2; безопасный паттерн `max(1, ...)` уже был в resource_monitor.py:133.
 **Fix:** `max(1, min(4, (os.cpu_count() or 4) // 2))` (index_project_runner.py:261) + регрессионный тест test_run_survives_single_cpu_host (mock os.cpu_count→1).
-**Status:** ✅ Fixed | **Guard:** тест валидирован — без фикса воспроизводится ровно ValueError (stash-прогон); полный pytest 762 passed.
+**Status:** ✅ Fixed | **Guard:** тест валидирован — без фикса воспроизводится ровно ValueError (stash-прогон); полный pytest 762 passed. Обобщение §3.5: аналогов уязвимого паттерна 0 — все остальные воркеры src/ фиксированы ≥1 или защищены `max(1, ...)` (cpu_count: 4 места; ThreadPoolExecutor: 7 мест).
 
 ## 2026-08-05 — A3 (внешний аудит): 626 except Exception — тихих глотателей не подтверждено (REFUTED, метод сохранён)
 

docs/adr/0001-sandbox-threat-model.md

@@ -0,0 +1,92 @@
+# ADR-0001: Threat Model for execute_script sandbox
+
+**Status:** Draft — ожидает решения владельца (OPEN_QUESTION)
+**Дата:** 2026-08-05
+**Автор:** агент (по итогам внешнего аудита и верификации A2)
+
+## Context
+
+`sandbox/executor.py` честно декларирует в докстринге (executor.py:14):
+
+> NOT a security boundary for untrusted code. Defense-in-depth for agent tools.
+
+Текущая реализация — два слоя защиты:
+
+1. **AST-валидация** (deny-лист): запрещены `eval`/`exec`, `importlib`, `pkgutil`,
+   `runpy`, `ast.Delete` (executor.py:73 — «Can delete variables»), опасные
+   атрибуты и т.д.
+2. **Runtime-перехват**: подмена `__import__` + allowlist модулей + выполнение
+   в subprocess с `_build_minimal_env` (executor.py:306), который **намеренно НЕ
+   копирует `os.environ`** (executor.py:309: «Deliberately does NOT copy
+   os.environ — parent secrets (API keys, ...)» не утекают в дочерний процесс).
+   Исключения-минимум: `SYSTEMROOT`, `SYSTEMDRIVE`, `TEMP`, `TMP`.
+
+Внешний аудит (2026-08-05) подтвердил: обвязка сделана аккуратно, но это
+классическая blacklist-модель на чистом Python-интерпретаторе **без ОС-изоляции**
+(нет seccomp, namespaces, gVisor). История Python sandbox escape
+(`object.__subclasses__` цепочки, frame-объекты в трейсбеках исключений,
+format-string трюки) показывает, что такие deny-листы со временем протекают.
+
+**Открытый вопрос для владельца:** для какого класса ввода эта defense-in-depth
+защита считается достаточной? Есть ли путь, по которому в executor попадает
+ввод из внешнего/недоверенного источника (не сгенерированный агентом сниппет
+внутри уже доверенного MCP-процесса)?
+
+**Побочное наблюдение (не блокер):** `ast.Delete` блокируется целиком — даже
+`del x` для локальной переменной запрещён. Это может быть побочный эффект
+широкой формулировки, ломающий легитимный код агента. Если владелец выберет
+Вариант A — рассмотреть сужение до `del` глобальных/атрибутных имён.
+
+## Decision
+
+**Рекомендация агента: Вариант A** — сохранить текущую defense-in-depth,
+зафиксировать границы модели угроз в этом ADR, **не расширять** поверхность
+без нового решения владельца.
+
+Решение финально принимает владелец. До решения `executor.py` не редактируется
+(зафиксировано в `.agent_task_state.md` Danger Zone).
+
+## Alternatives considered
+
+### Вариант A: Defense-in-depth (текущий)
+- **Применимо:** доверенные сниппеты (генерированные агентом) внутри уже
+  доверенного MCP-процесса
+- **Guard:** AST-валидация + blacklist + runtime `__import__`-перехват +
+  subprocess-изоляция с минимальным env
+- **Ограничение:** не защищает от агента-вредителя и от недоверенного внешнего
+  ввода (если такой путь появится)
+- **Усилия:** 0 (текущее состояние); документирование границ — 1 коммит
+- **Риск:** если появится недоверенный источник ввода, blacklist может протечь
+  (нужно будет поднять до B)
+
+### Вариант B: OS-изоляция
+- **Применимо:** недоверенный ввод (внешний агент, CI-артефакты, пользовательский
+  код из репозиториев)
+- **Guard:** container/microVM + seccomp (или изолированный runtime)
+- **Усилия:** 2-4 недели, новая зависимость, усложнение инсталляции и поддержки
+  Windows-платформы (проект активно поддерживает Windows)
+- **Ограничение:** в чистом виде избыточно для текущего единственного вызова
+  (execute_script → доверенные сниппеты)
+
+### Вариант C: Гибрид
+- **Применимо:** оба класса ввода одновременно
+- **Guard:** threat classifier на входе: доверенные пути → Вариант A,
+  недоверенные → Вариант B
+- **Усилия:** выше, чем B (два пути + классификатор)
+- **Ограничение:** классификатор сам становится поверхностью атаки (ошибка
+  классификации = неверный путь выполнения)
+
+## Impact
+
+- **При Варианте A (рекомендация):** изменения кода нет. Фиксируются границы:
+  executor — инструмент для доверенных сниппетов агента, не для пользовательского
+  кода. `KNOWN_ISSUES`/README получают явную строку о границах. Новый
+  недоверенный путь ввода → немедленное переоткрытие ADR (эскалация до B/C).
+- **При Варианте B/C:** новая зависимость, изменения в `install.py`,
+  платформенная матрица CI расширяется. Отдельная фича со своим планом.
+
+## Status
+
+Draft — ожидает решения владельца. Связанный OPEN_QUESTION зафиксирован в
+`.agent_task_state.md` (A2). После решения — обновить этот раздел
+(✅ Accepted / ❌ Rejected / superseded) и при необходимости правки executor.py.