Add shadow security finding inbox

docs/CONTAINMENT_POLICY_RU.md

@@ -0,0 +1,146 @@
+# AWatch-rus containment policy
+
+Дата: 2026-06-25.
+
+Этот документ описывает безопасную политику автоматической/полуавтоматической
+изоляции рабочих станций. Containment нужен для быстрого ограничения
+распространения заражения, но не является автоматическим лечением,
+remediation, EDR/XDR или сертифицированной СЗИ.
+
+## Default posture
+
+По умолчанию containment выключен:
+
+```text
+AW_CONTAINMENT_ENABLED=false
+AW_CONTAINMENT_MODE=shadow
+```
+
+`shadow` означает: система рассчитывает рекомендацию и audit, но не меняет
+firewall, pfSense, AD, VLAN, маршруты или состояние рабочих станций.
+
+## Policy file
+
+Default path:
+
+```text
+/etc/activitywatch/containment-policy.json
+```
+
+Repo example:
+
+```text
+configs/containment-policy.example.json
+```
+
+Критичные поля:
+
+- `enabled`: глобальный opt-in;
+- `mode`: `shadow`, `manual_approval`, `auto`;
+- `default_ttl_minutes`: срок quarantine до rollback/review;
+- `require_admin_channel_check`: запрещает блокировку, если управляемый канал
+  не проверен;
+- `allow_auto_for_servers`: по умолчанию `false`;
+- `allowed_actions`: whitelist containment-действий;
+- `management_allowlist`: каналы, которые должны оставаться доступными;
+- `minimum_high_signals_for_auto`: минимальный порог high/critical signals.
+
+## Safety rules
+
+- Не включать `auto` до успешного shadow burn-in.
+- Не включать auto-containment для серверов и domain controllers.
+- Не запускать containment без rollback record.
+- Не запускать containment, если будет потерян admin/management channel.
+- Не применять широкие AD/OU/domain actions.
+- Не удалять файлы, registry keys или процессы как часть containment.
+- Не заявлять, что containment гарантированно остановил заражение.
+
+## Decision threshold
+
+Automatic quarantine допускается только если:
+
+- host role is `workstation`;
+- host не входит в critical infrastructure denylist;
+- есть один `critical` signal или несколько `high` signals;
+- management-channel precheck passed;
+- action есть в `allowed_actions`;
+- rollback record создан успешно.
+
+## Security Finding Inbox handoff
+
+Security Finding Inbox (`docs/SECURITY_FINDING_INBOX_RU.md`) является входной
+очередью для подозрительных рабочих станций. Он хранит findings и workflow
+events в ClickHouse, показывает их в DetMir Portal. Портал не выполняет
+containment самостоятельно.
+
+Workflow `apply_requested` означает только операторский запрос на применение.
+Фактическое применение идет через отдельный процесс
+`security-finding-inbox executor`, который повторно проверяет `approved`,
+запускает `containment-engine decide`, строит Windows Firewall plan, затем
+выполняет `apply`, `verify` и при ошибке `rollback`. Реальная мутация firewall
+разрешена только на целевой Windows-станции при `--execute-local`,
+`--confirm-execute YES` и совпадении `--executor-host` с finding host.
+
+## Current implementation status
+
+Реализован первый безопасный слой:
+
+- Rust CLI `containment-engine`;
+- strict JSON policy/finding parsing;
+- `disabled`, `shadow`, `manual_approval`, `auto` decision states;
+- server/unknown host roles refused for auto mode by default;
+- `would_mutate=false` for current implementation;
+- separate Windows Firewall executor interface:
+  `plan`, `apply`, `verify`, `rollback`;
+- Windows Firewall executor defaults to dry-run command generation unless
+  `--execute-local` and explicit confirmation are used.
+
+pfSense/AD/VLAN mutation paths are not implemented.
+
+## Windows Firewall executor
+
+Executor input example:
+
+```text
+configs/windows-firewall-containment-request.example.json
+```
+
+The executor is deliberately separate from decision making:
+
+```bash
+containment-engine windows-firewall plan \
+  --request configs/windows-firewall-containment-request.example.json \
+  --pretty > /tmp/windows-firewall-plan.json
+
+containment-engine windows-firewall apply \
+  --plan /tmp/windows-firewall-plan.json \
+  --confirm-apply YES \
+  --pretty
+
+containment-engine windows-firewall verify \
+  --plan /tmp/windows-firewall-plan.json \
+  --pretty
+
+containment-engine windows-firewall rollback \
+  --plan /tmp/windows-firewall-plan.json \
+  --confirm-rollback YES \
+  --pretty
+```
+
+Without `--execute-local`, `apply` and `rollback` return generated PowerShell
+commands and `would_mutate=false`.
+
+With `--execute-local`, execution is allowed only on a Windows host and only
+after explicit confirmation. On non-Windows hosts the executor fails closed.
+
+## Windows Firewall guardrails
+
+- `management_allowlist` is mandatory.
+- `blocked_remote_addresses` must be explicit IPs/subnets.
+- Broad block targets such as `Any`, `*`, `LocalSubnet`, `Internet`,
+  `Intranet` are refused.
+- The executor does not change Windows Firewall profile defaults.
+- The executor does not disable interfaces, routes, users, services or
+  processes.
+- Every plan includes rollback through `Remove-NetFirewallRule -Group ...`.
+- A successful dry-run is not evidence that the workstation has been isolated.