Files

claude-bot 30b6187c73 feat(security): security-gate (gitleaks secret-scan + pip-audit) before merge

Add a deterministic (no-LLM) security sub-gate on the deploy-staging -> deploy
edge, run FIRST (before merge-gate ORCH-043 and image-freshness ORCH-058) so it
fails cheaply before any expensive rebase/rebuild, and scans origin/main..HEAD
before rebase so a task is never blamed for a CVE introduced by an updated main.

Why: the autonomous pipeline merged branches into main with no check for a leaked
secret or a vulnerable dependency. For the self-hosting orchestrator (one shared
prod instance serving every project from a shared DB) a single leak/CVE landed in
the prod of all projects (CLAUDE.md self-hosting, section 8).

- New leaf src/security_gate.py (never-raise): gitleaks (offline, fail-closed on
  tool error => secrets guarantee is unconditional) + pip-audit (best-effort;
  unreachable CVE feed degrades fail-open + loud warning by default, strict via
  security_dep_audit_fail_closed). Verdict lives ONLY in 17-security-report.md
  YAML frontmatter (write -> read-back single source of truth); FAIL is
  authoritative; missing/broken frontmatter => fail-closed.
- check_security_gate thin wrapper registered in QG_CHECKS (lazy import, no cycle).
- _handle_security_gate wired FIRST in advance_stage deploy-staging block: FAIL ->
  rollback to development + developer-retry (cap MAX_DEVELOPER_RETRIES); task_desc
  carries verbatim findings (ORCH-046 pattern). No merge-lease release (runs before
  lease acquire). Self-hosting safe: only reads/scans/writes, never deploys.
- Conditional rollout (security_gate_enabled + security_gate_repos; empty scope ->
  self-hosting only). 6 new ORCH_SECURITY_* settings.
- Infra: pinned gitleaks Go binary in Dockerfile (+curl/ca-certificates), pip-audit
  in requirements.txt, versioned .gitleaks.toml at repo root.
- STAGE_TRANSITIONS and DB schema unchanged.

Docs: docs/architecture/README.md (marked realized), CLAUDE.md (artifact 17),
CHANGELOG.md. Tests: test_security_gate.py, test_qg_security.py,
test_stage_engine_security_gate.py + updated registry/edge snapshots.

Refs: ORCH-022

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-06-07 18:04:50 +00:00

5.6 KiB

Raw Blame History

CLAUDE.md — паспорт проекта orchestrator

TL;DR

Мульти-агентный оркестратор разработки. FastAPI-сервис: принимает webhooks от Plane и Gitea, ведёт задачи по конвейеру стадий через Quality Gates, запускает Claude CLI агентов (analyst → architect → developer → reviewer → tester → deployer) на каждой стадии. Оркестратор дорабатывает в том числе сам себя (self-hosting).

Стек

Backend: FastAPI + uvicorn (Python 3.12)
БД: SQLite (src/db.py)
Агенты: Claude CLI (ORCH_CLAUDE_BIN), по одному промпту на роль в .openclaw/agents/
Очередь задач: собственная (SQLite jobs, src/queue_worker.py, ORCH-1)
Контейнеризация: Docker + Compose
CI/CD: Gitea Actions (.gitea/workflows/)
Деплой: docker compose на mva154

Команды

uvicorn src.main:app --reload --port 8500 — поднять локально (dev)
pytest tests/ -q — все тесты
docker compose up -d --build — прод
docker compose --profile staging up -d orchestrator-staging — staging-песочница (8501)

Среды

prod — orchestrator (8500), внешний URL https://openclaw.mva154.duckdns.org/orchestrator/
staging — orchestrator-staging (8501), изолированная БД (./data/staging), только sandbox-проект

Структура

src/ — приложение (main, config, db, stages, stage_engine, queue_worker, projects, usage)
src/agents/launcher.py — запуск Claude CLI агентов
src/qg/checks.py — Quality Gate проверки
src/webhooks/ — приём вебхуков Plane/Gitea
tests/ — pytest
docs/ — документация, ADR, work-items, operations
scripts/ — утилиты (staging_check.py, orchestrator-deploy-hook.sh)

Конвейер (кратко; детали — docs/architecture/README.md)

created → analysis → architecture → development → review → testing → deploy-staging → deploy → done
                          ↑                          │
                          └──── REQUEST_CHANGES ──────┘  (откат на development, max 3)

Конвенции

Conventional Commits (feat:, fix:, docs:, refactor:, test:)
Ветки: feature/ORCH-NNN-slug, fix/ORCH-NNN-slug
ADR per work-item: docs/work-items/<plane-id>/06-adr/ADR-NNN-slug.md
Global ADR (сквозные решения): docs/architecture/adr/adr-NNNN-slug.md
Work items: docs/work-items/<plane-id>/
Машинные вердикты Quality Gate — строго YAML-frontmatter (verdict:, deploy_status:, staging_status:, security_status:), никогда проза

Артефакты задачи (`docs/work-items/<plane-id>/`)

00-business-request.md, 01-brd.md, 02-trz.md, 03-acceptance-criteria.md, 04-test-plan.yaml, 06-adr/ADR-NNN-slug.md, 07-infra-requirements.md, 08-data-requirements.md, 10-tech-risks.md, 12-review.md, 13-test-report.md, 14-deploy-log.md, 15-staging-log.md, 16-post-deploy-log.md (post-deploy наблюдение, ORCH-021), 17-security-report.md (security-гейт: security_status:/secrets/deps, ORCH-022).

Правила для агентов

Перед любым действием прочесть этот файл и docs/architecture/README.md.
Документация = golden source наравне с кодом. Изменил функционал → обнови доку В ТОМ ЖЕ PR. Архитектурное решение → заведи ADR. Обнови CHANGELOG.md.
Никогда не править артефакты других этапов.
Никогда не комментировать ТЗ задним числом — если ТЗ не годится, возвращай в Анализ.
Никогда не закрывать задачу самостоятельно — это делает CI / финальная стадия.
Reviewer проверяет: обновлена ли документация. Нет → REQUEST_CHANGES.
Не использовать --no-verify без явного одобрения Owner.
Секреты — только в .env/.env.staging на хосте, в гит НЕ коммитятся (канон — .env.example).

⚠️ Self-hosting — оркестратор правит САМ СЕБЯ

Задачи проекта ORCH меняют инструмент, который СЕЙЧАС работает в продакшене и обслуживает ДРУГИЕ проекты (enduro-trails) из ОДНОГО инстанса с ОБЩЕЙ БД и общей очередью.

НЕ перезапускать / не ронять прод-контейнер orchestrator в рамках задачи — встанет конвейер всех проектов.
Любой деплой/рестарт self = групповой риск. Детали и топология — docs/operations/INFRA.md.
Стадия deploy-staging (порт 8501) — обязательная страховка перед прод-деплоем орка.

Паспорт проекта orchestrator. Поддерживается агентами при каждой доработке. Изолирован: описывает только этот проект (канон per-repo, см. ORCH-9).

5.6 KiB Raw Blame History Unescape Escape