adr-0012: Security-гейт — secret-scanning + dependency audit перед мержем

Статус: proposed
Дата: 2026-06-07
Задача: ORCH-022
Детальный ADR: docs/work-items/ORCH-022/06-adr/ADR-001-security-gate.md

Контекст

Оркестратор автономен: developer пишет код без человека-фильтра. Перед слиянием ветки в main нет проверки на утёкший секрет (ключ/токен/пароль/приватный ключ) и уязвимую зависимость (CVE). Для self-hosting один общий прод-инстанс обслуживает все проекты с общей БД — секрет/CVE через одну задачу попадает в прод всех (CLAUDE.md §self-hosting, §8). Фактический мерж PR в main делает deployer в начале стадии deploy.

Решение

Детерминированный (без LLM) security-гейт как под-гейт ребра deploy-staging → deploy, рядом с merge-gate (ORCH-043) и image-freshness (ORCH-058), исполняемый ПЕРВЫМ среди edge-под-гейтов (ДО merge-gate). STAGE_TRANSITIONS не меняется; в QG_CHECKS добавлен check_security_gate. Паттерн — как у соседей: leaf-модуль src/security_gate.py (never-raise) + тонкая обёртка в QG_CHECKS + врезка _handle_security_gate в advance_stage.

Secret-scanning (gitleaks, offline): скан origin/main..HEAD; любой секрет вне аллоулиста (.gitleaks.toml) → вклад в FAIL. Offline → гарантия «секрет всегда блокирует» не зависит от сети.
Dependency audit (pip-audit, OSV/PyPI): severity ≥ security_dep_block_severity (дефолт HIGH) → FAIL; ниже / UNKNOWN → warning. Недоступность фида → fail-open + громкий warning (анти-петля; флаг security_dep_audit_fail_closed для строгого режима).
ПЕРВЫМ на ребре, ДО merge-gate: дёшево фейлить до дорогих rebase/rebuild; скан ветки ДО rebase не «обвиняет» задачу в CVE, притащенной обновившимся main (анти-петля ORCH-061); до захвата merge-lease → при FAIL lease освобождать не нужно.
Артефакт 17-security-report.md с YAML-frontmatter (security_status, secrets_found, deps_blocking, deps_warning, deps_audit_degraded); вердикт читается ТОЛЬКО из frontmatter (канон), negative-токен авторитетен; битый/нет → fail-closed.
FAIL → откат на development + developer-retry (общий _developer_retry_count, cap 3, затем set_issue_blocked + Telegram); task_desc несёт дословные находки (ORCH-046).
Условность (как ORCH-35/43/58): security_gate_enabled + security_gate_repos; пусто → реально только self-hosting (orchestrator), прочие репо — no-op pass.
never-raise, таймаут security_scan_timeout_s, гейт не деплоит/не рестартит прод.

Альтернативы

Вариант R (review-стадия): diff может разойтись с мержем в main; merge-edge — последняя страховка. Отклонено.
Вариант C (CI-job через check_ci_green): пороги/severity/аллоулист/артефакт плохо выражаются статусом коммита; коуплинг с раннером. Отклонено для v1 (точка расширения).
Новая стадия security: «пустая» стадия без агента не имеет триггера (как в ORCH-043). Отклонено.
fail-closed dep-audit / аудит после rebase: ложные откаты → петля. Отклонено.
Новая колонка retry в БД: не нужна (переиспользуем _developer_retry_count).

Последствия

Класс «тихо влитый секрет/CVE» закрыт: секреты — безусловно (offline), CVE — best-effort при доступности фида. Самоприменение CLAUDE.md §8 без человека.
Плата: ещё один «скрытый» под-гейт ребра (нет в STAGE_TRANSITIONS); внешние инструменты (gitleaks в образе, pip-audit в зависимостях); время скана на каждом прогоне (ограничено таймаутом); v1 — Python-only (SAST/мульти-стек — follow-up WI).
Сквозное изменение (новый QG + edge-под-гейт) → arch:major-change; прод-деплой ORCH-022 — строго через staging-гейт (8501), без рестарта прод-контейнера.

Связи

adr-0006 (merge-gate — паттерн edge-под-гейта/отката), adr-0008 (image-freshness — условность/never-raise/fail-closed), adr-0003 (условный гейт / is_self_hosting_repo), adr-0009 (анти-петля ложных FAIL, ORCH-061), ORCH-046 (дословный reason в task_desc), ORCH-9/15 (мульти-стек — будущая зависимость), ORCH-2 (worktree-изоляция).

5.6 KiB Raw Permalink Blame History Unescape Escape