AWatch-rus/docs/CONTAINMENT_OPERATOR_RUNBOOK_RU.md

AWatch-rus containment operator runbook

Дата: 2026-06-25.

Runbook для безопасной проверки containment-логики. Текущая реализация не блокирует рабочие станции и не меняет сеть. Она только рассчитывает решение и показывает, был бы quarantine рекомендован или отказан.

1. Сборка

cd /mnt/usb_hdd2/Projects/ActivityWatch-Russian
export CARGO_TARGET_DIR=/home/igor/.cache/detmir-adk-rust-target
cargo build --manifest-path adk-rust/Cargo.toml -p containment-engine

2. Smoke в disabled/shadow режиме

cd /mnt/usb_hdd2/Projects/ActivityWatch-Russian
bash scripts/containment_shadow_smoke.sh

Ожидаемо:

• JSON содержит would_mutate=false;
• decision_status=disabled для default example policy;
• нет изменений firewall, pfSense, AD, VLAN, routes.

3. Проверка shadow recommendation

Создайте временный policy с:

{
  "enabled": true,
  "mode": "shadow"
}

на базе configs/containment-policy.example.json, затем выполните:

containment-engine decide \
  --policy /tmp/containment-policy-shadow.json \
  --finding configs/containment-finding.example.json \
  --pretty

Ожидаемо:

• decision_status=shadow_recommended;
• would_mutate=false;
• rollback_plan_id заполнен;
• blockers=[].

4. Manual approval mode

manual_approval должен только поставить решение в состояние manual_approval_required. Он не применяет block сам.

5. Auto mode

В текущей реализации auto может вернуть auto_ready, но would_mutate=false. Это намеренно: decision layer сам не применяет блокировки.

Запрещено считать auto_ready фактической блокировкой. Это только решение control plane.

6. Windows Firewall executor dry-run

Security Finding Inbox показывает подозрительные станции и фиксирует workflow события. Портал не выполняет firewall apply. После approved и apply_requested отдельный процесс security-finding-inbox executor может выполнить контролируемый цикл decide -> plan -> apply -> verify, а при ошибке rollback. По умолчанию executor работает dry-run/fail-closed.

Сгенерируйте план:

cd /mnt/usb_hdd2/Projects/ActivityWatch-Russian
containment-engine windows-firewall plan \
  --request configs/windows-firewall-containment-request.example.json \
  --pretty > /tmp/windows-firewall-plan.json

Проверьте blockers. Для корректного example они должны быть пустыми.

Dry-run apply:

containment-engine windows-firewall apply \
  --plan /tmp/windows-firewall-plan.json \
  --confirm-apply YES \
  --pretty

Ожидаемо:

• execution_status=dry_run_commands_ready;
• would_mutate=false;
• в JSON есть PowerShell-команды New-NetFirewallRule;
• реальные firewall-правила не создаются.

Verify dry-run:

containment-engine windows-firewall verify \
  --plan /tmp/windows-firewall-plan.json \
  --pretty

Rollback dry-run:

containment-engine windows-firewall rollback \
  --plan /tmp/windows-firewall-plan.json \
  --confirm-rollback YES \
  --pretty

7. Real Windows execution rules

Dry-run polling из центрального контура:

security-finding-inbox executor \
  --once \
  --dry-run \
  --containment-engine-bin /usr/local/bin/containment-engine \
  --policy /etc/activitywatch/containment-policy.json \
  --management-allowlist 10.10.10.10,10.10.10.11 \
  --blocked-remote-addresses 10.10.20.0/24,10.10.30.0/24

Реальный Windows Firewall apply допускается только на целевой Windows-станции:

security-finding-inbox.exe executor `
  --once `
  --execute-local `
  --confirm-execute YES `
  --executor-host HOST-EXAMPLE `
  --containment-engine-bin C:\ProgramData\AWatch-rus\containment-engine.exe `
  --policy C:\ProgramData\AWatch-rus\containment-policy.json `
  --management-allowlist 10.10.10.10,10.10.10.11 `
  --blocked-remote-addresses 10.10.20.0/24,10.10.30.0/24

Executor откажется, если нет approved перед apply_requested, finding не suspected_infected/confirmed_infected, management channel не проверен, allowlist/block ranges пустые, host finding не совпадает с executor host для local apply, containment policy возвращает blocker или Windows Firewall plan содержит blockers.

--execute-local разрешён только для отдельного lab Windows host, где заранее проверены:

• доступ с admin jump host;
• доступ к AWatch/Velociraptor management адресам;
• rollback command;
• out-of-band доступ, если firewall rule ошибочен;
• TTL и оператор, ответственный за возврат.

Не использовать широкие блокировки Any/LocalSubnet: Windows Firewall block-правила могут перекрыть allow-правила и отрезать управление.

8. Когда можно расширять real containment executor

Только после выполнения условий:

• есть lab host;
• подтвержден management allowlist;
• есть rollback command;
• есть TTL rollback;
• есть audit log;
• plan, apply, verify, rollback покрыты тестами;
• auto-containment для серверов остается disabled.

9. Проверки перед commit

cd /mnt/usb_hdd2/Projects/ActivityWatch-Russian
python3 scripts/public_secret_pattern_check.py
bash -n scripts/containment_shadow_smoke.sh
bash scripts/containment_shadow_smoke.sh
git diff --check

cd adk-rust
export CARGO_TARGET_DIR=/home/igor/.cache/detmir-adk-rust-target
cargo fmt --all --check
cargo test -p containment-engine
cargo clippy -p containment-engine --all-targets -- -D warnings