Add shadow security finding inbox
CI / Rust checks (push) Canceled after 0s
CI / Docs and registry checks (push) Canceled after 0s
CI / Smoke checks (push) Canceled after 0s
Coverage / Coverage baseline (push) Canceled after 0s
Security / Cargo audit (push) Canceled after 0s
Security / Cargo deny (push) Canceled after 0s
Security / Secret pattern check (push) Canceled after 0s
Security / Dependency review (push) Canceled after 0s
CI / Rust checks (push) Canceled after 0s
CI / Docs and registry checks (push) Canceled after 0s
CI / Smoke checks (push) Canceled after 0s
Coverage / Coverage baseline (push) Canceled after 0s
Security / Cargo audit (push) Canceled after 0s
Security / Cargo deny (push) Canceled after 0s
Security / Secret pattern check (push) Canceled after 0s
Security / Dependency review (push) Canceled after 0s
This commit is contained in:
@@ -0,0 +1,194 @@
|
||||
# AWatch-rus containment operator runbook
|
||||
|
||||
Дата: 2026-06-25.
|
||||
|
||||
Runbook для безопасной проверки containment-логики. Текущая реализация не
|
||||
блокирует рабочие станции и не меняет сеть. Она только рассчитывает решение и
|
||||
показывает, был бы quarantine рекомендован или отказан.
|
||||
|
||||
## 1. Сборка
|
||||
|
||||
```bash
|
||||
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 режиме
|
||||
|
||||
```bash
|
||||
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 с:
|
||||
|
||||
```json
|
||||
{
|
||||
"enabled": true,
|
||||
"mode": "shadow"
|
||||
}
|
||||
```
|
||||
|
||||
на базе `configs/containment-policy.example.json`, затем выполните:
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
Сгенерируйте план:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
containment-engine windows-firewall verify \
|
||||
--plan /tmp/windows-firewall-plan.json \
|
||||
--pretty
|
||||
```
|
||||
|
||||
Rollback dry-run:
|
||||
|
||||
```bash
|
||||
containment-engine windows-firewall rollback \
|
||||
--plan /tmp/windows-firewall-plan.json \
|
||||
--confirm-rollback YES \
|
||||
--pretty
|
||||
```
|
||||
|
||||
## 7. Real Windows execution rules
|
||||
|
||||
Dry-run polling из центрального контура:
|
||||
|
||||
```bash
|
||||
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-станции:
|
||||
|
||||
```powershell
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
@@ -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.
|
||||
@@ -0,0 +1,813 @@
|
||||
# Low-cost Sigma/Hayabusa/Velociraptor containment addon
|
||||
|
||||
Дата: 2026-06-25.
|
||||
|
||||
Цель: добавить в AWatch-rus дешевый, воспроизводимый и отключаемый слой
|
||||
security containment + forensics для организаций без зрелого SIEM/EDR. Главный
|
||||
смысл модуля - быстро ограничить дальнейшее распространение заражения или
|
||||
подозрительной активности с рабочей станции, сохранив управляемый канал
|
||||
расследования и восстановления.
|
||||
|
||||
Это дополнение не делает AWatch-rus сертифицированной DLP/SIEM/EDR/XDR/СЗИ и
|
||||
не заменяет штатные средства защиты. Автоматическая блокировка здесь означает
|
||||
policy-approved containment/quarantine, а не автоматическое лечение системы.
|
||||
|
||||
## Upstream basis
|
||||
|
||||
- Hayabusa: fast Windows event log forensics timeline generator and threat
|
||||
hunting tool, written in Rust, using Sigma-compatible Hayabusa rules.
|
||||
- Hayabusa supports single-host/live analysis, offline analysis of collected
|
||||
logs, and enterprise-wide use through a Velociraptor artifact.
|
||||
- Hayabusa outputs timeline/results suitable for CSV, JSON/JSONL and HTML
|
||||
reports.
|
||||
- `Windows.Hayabusa.Monitoring` in Velociraptor Curated Sigma is an artifact
|
||||
intended to triage a Windows host and is based on `Windows.Sigma.BaseEvents`.
|
||||
- Velociraptor is an endpoint visibility and collection tool using VQL
|
||||
artifacts. Its normal deployment is server + clients, but it also supports
|
||||
offline collectors and command-line artifact execution.
|
||||
|
||||
Primary references:
|
||||
|
||||
- https://github.com/Yamato-Security/hayabusa
|
||||
- https://github.com/Yamato-Security/hayabusa/wiki/About-Hayabusa
|
||||
- https://github.com/Yamato-Security/hayabusa-rules
|
||||
- https://sigma.velocidex.com/docs/artifacts/windows.hayabusa.monitoring/
|
||||
- https://github.com/Velocidex/velociraptor
|
||||
- https://docs.velociraptor.app/docs/deployment/
|
||||
|
||||
## Product positioning
|
||||
|
||||
Рабочее название модуля:
|
||||
|
||||
```text
|
||||
AWatch-rus Low-Cost Containment Pack
|
||||
```
|
||||
|
||||
Назначение:
|
||||
|
||||
- быстро получить полезный containment + DFIR/threat-hunting слой там, где
|
||||
нет SIEM/EDR;
|
||||
- автоматически или полуавтоматически изолировать подозрительно зараженную
|
||||
рабочую станцию от критичных сегментов;
|
||||
- сохранить минимальный управляемый канал: AWatch-rus/Velociraptor server,
|
||||
администраторский jump/VPN, DNS/NTP при необходимости;
|
||||
- запускать Hayabusa/Sigma-анализ EVTX и Velociraptor artifact collection;
|
||||
- давать владельцу и администратору понятные findings, timeline и evidence;
|
||||
- связывать findings с AWatch-rus cases и operator/forensics views;
|
||||
- оставаться optional и выключаемым без деградации Workforce core.
|
||||
|
||||
Запрещенные claims:
|
||||
|
||||
- не писать, что это SIEM replacement;
|
||||
- не писать, что это DLP replacement;
|
||||
- не писать, что это EDR/XDR;
|
||||
- не писать, что это сертифицированная СЗИ;
|
||||
- не писать, что автоматическое remediation включено;
|
||||
- не писать, что automatic containment гарантированно остановит заражение;
|
||||
- не писать, что threat detection ML/LLM-based;
|
||||
- не писать, что найденные события являются доказанной атакой без ручной
|
||||
проверки.
|
||||
|
||||
Допустимая формулировка:
|
||||
|
||||
```text
|
||||
Optional low-cost containment, security analytics and forensics layer based on
|
||||
open-source Hayabusa/Sigma/Velociraptor workflows.
|
||||
```
|
||||
|
||||
## Containment objective
|
||||
|
||||
Модуль должен отвечать на вопрос:
|
||||
|
||||
```text
|
||||
Как максимально быстро ограничить рабочую станцию, которая выглядит зараженной,
|
||||
чтобы она не заражала соседние машины и не продолжала утечку/распространение?
|
||||
```
|
||||
|
||||
Необходимо разделять:
|
||||
|
||||
- `suspected_infected` - есть правила/сигналы/аномалии, достаточные для
|
||||
карантина по политике организации;
|
||||
- `confirmed_infected` - есть ручное подтверждение администратора/ИБ;
|
||||
- `contained` - станция технически ограничена;
|
||||
- `released` - карантин снят вручную или по документированному rollback.
|
||||
|
||||
Containment actions должны быть обратимыми, журналируемыми и ограниченными по
|
||||
blast radius. По умолчанию допускается `shadow` или `manual_approval`; fully
|
||||
automatic quarantine включается только отдельным флагом и только после
|
||||
allowlist/rollback проверки.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Modes
|
||||
|
||||
1. `disabled`
|
||||
- default для conservative deployment;
|
||||
- все readiness checks возвращают disabled-state;
|
||||
- Workforce/ActivityWatch core не зависит от модуля.
|
||||
|
||||
2. `hayabusa_offline`
|
||||
- текущий базовый режим;
|
||||
- Windows scheduled task экспортирует EVTX zip;
|
||||
- серверный `aw-hayabusa-drop.path` принимает package;
|
||||
- `aw-hayabusa-autoprocess` валидирует zip, process-inbox, quarantine.
|
||||
|
||||
3. `velociraptor_offline_collector`
|
||||
- для бедных/малых контуров без постоянно работающего Velociraptor server;
|
||||
- AWatch-rus собирает/хранит signed offline collector bundle;
|
||||
- запуск collector выполняется вручную или scheduled task;
|
||||
- результаты импортируются как artifact bundle.
|
||||
|
||||
4. `velociraptor_server_clients`
|
||||
- optional managed mode;
|
||||
- Linux server рядом с AW/Proxmox или отдельной VM;
|
||||
- Windows clients ставятся только явным Ansible-флагом;
|
||||
- используется для управляемого запуска `Windows.Hayabusa.Monitoring`.
|
||||
|
||||
5. `containment_shadow`
|
||||
- decision engine считает, что сделал бы, но ничего не блокирует;
|
||||
- безопасный default для пилота;
|
||||
- используется для настройки правил и false-positive анализа.
|
||||
|
||||
6. `containment_manual_approval`
|
||||
- система формирует containment recommendation;
|
||||
- администратор подтверждает действие в CLI/портале;
|
||||
- все действия пишутся в audit trail.
|
||||
|
||||
7. `containment_auto`
|
||||
- система сама применяет заранее разрешенные quarantine-действия;
|
||||
- включается только явным флагом;
|
||||
- требует allowlist, rollback TTL и проверку сохранения admin channel.
|
||||
|
||||
### Boundaries
|
||||
|
||||
Core remains:
|
||||
|
||||
- ActivityWatch server;
|
||||
- Workforce reports;
|
||||
- RDP/window/AFK/worktime collectors;
|
||||
- 1C/ClickHouse analytics;
|
||||
- portal health/readiness;
|
||||
- Hayabusa drop quarantine hardening.
|
||||
|
||||
Optional containment/forensics layer:
|
||||
|
||||
- Hayabusa binary and rules;
|
||||
- Sigma/Hayabusa curated rules cache;
|
||||
- Velociraptor binary/config/artifacts;
|
||||
- Velociraptor clients/offline collectors;
|
||||
- artifact result import;
|
||||
- findings summary and case links;
|
||||
- containment decision engine;
|
||||
- containment executor for approved channels.
|
||||
|
||||
Containment channels:
|
||||
|
||||
- Windows host firewall quarantine:
|
||||
allow only AWatch-rus/Velociraptor server, DNS/NTP if required, and admin
|
||||
jump/VPN;
|
||||
- pfSense/network gateway block:
|
||||
block workstation IP/MAC from lateral/internal segments, keep management
|
||||
exception;
|
||||
- switch/VLAN quarantine when supported:
|
||||
move port/client to quarantine VLAN through explicit integration;
|
||||
- Windows local containment:
|
||||
stop risky shares/services, disable outbound SMB/RDP to peers, collect
|
||||
evidence;
|
||||
- Active Directory actions, if configured:
|
||||
disable only the workstation account or user session by policy, never broad
|
||||
OU/domain actions by default.
|
||||
|
||||
Non-goals:
|
||||
|
||||
- deleting malware;
|
||||
- cleaning registry/files;
|
||||
- killing arbitrary processes based on weak signal;
|
||||
- disabling domain-wide accounts;
|
||||
- blocking servers/shared infrastructure automatically;
|
||||
- hiding the host from administrators.
|
||||
|
||||
No hot-path dependency:
|
||||
|
||||
- portal first screen must not wait for Velociraptor;
|
||||
- Workforce reports must not query Velociraptor;
|
||||
- readiness must not fail when module is disabled;
|
||||
- heavy artifact execution must be timer/manual/background only.
|
||||
|
||||
## Proposed configuration
|
||||
|
||||
Ansible group vars:
|
||||
|
||||
```yaml
|
||||
aw_forensics_pack_enabled: false
|
||||
aw_hayabusa_enabled: true
|
||||
aw_hayabusa_rules_enabled: true
|
||||
aw_hayabusa_rules_version: "pinned"
|
||||
aw_hayabusa_rules_update_enabled: false
|
||||
|
||||
aw_velociraptor_enabled: false
|
||||
aw_velociraptor_mode: "disabled" # disabled|offline_collector|server_clients
|
||||
aw_velociraptor_version: "pinned"
|
||||
aw_velociraptor_server_bind_host: "127.0.0.1"
|
||||
aw_velociraptor_public_enabled: false
|
||||
aw_velociraptor_artifact_pack_enabled: true
|
||||
aw_velociraptor_hayabusa_artifact_enabled: true
|
||||
|
||||
aw_forensics_store_raw_artifacts: false
|
||||
aw_forensics_raw_retention_days: 7
|
||||
aw_forensics_result_retention_days: 90
|
||||
aw_forensics_max_parallel_jobs: 1
|
||||
aw_forensics_max_job_minutes: 30
|
||||
aw_forensics_cpu_quota_pct: 25
|
||||
aw_forensics_io_nice: true
|
||||
|
||||
aw_containment_enabled: false
|
||||
aw_containment_mode: "shadow" # shadow|manual_approval|auto
|
||||
aw_containment_default_ttl_minutes: 60
|
||||
aw_containment_require_admin_channel_check: true
|
||||
aw_containment_allow_auto_for_servers: false
|
||||
aw_containment_allowed_actions:
|
||||
- windows_firewall_quarantine
|
||||
- pfsense_host_block
|
||||
aw_containment_management_allowlist:
|
||||
- "aw_server"
|
||||
- "velociraptor_server"
|
||||
- "admin_jump_host"
|
||||
```
|
||||
|
||||
Runtime env:
|
||||
|
||||
```text
|
||||
AW_FORENSICS_PACK_ENABLED=false
|
||||
AW_HAYABUSA_ENABLED=true
|
||||
AW_VELOCIRAPTOR_ENABLED=false
|
||||
AW_VELOCIRAPTOR_MODE=disabled
|
||||
AW_FORENSICS_STORE_RAW_ARTIFACTS=false
|
||||
AW_CONTAINMENT_ENABLED=false
|
||||
AW_CONTAINMENT_MODE=shadow
|
||||
```
|
||||
|
||||
## Data flow
|
||||
|
||||
### Existing Hayabusa path
|
||||
|
||||
```text
|
||||
Windows EVTX export
|
||||
-> zip + sidecars
|
||||
-> /opt/activitywatch/aw-rus-ops/drop
|
||||
-> aw-hayabusa-autoprocess
|
||||
-> validate package
|
||||
-> accept/process-inbox
|
||||
-> result_dir/latest-intake.json
|
||||
-> case link / portal summary
|
||||
-> quarantine on bad package
|
||||
```
|
||||
|
||||
### New Velociraptor path
|
||||
|
||||
```text
|
||||
Velociraptor artifact run
|
||||
-> Windows.Hayabusa.Monitoring / custom artifact
|
||||
-> Velociraptor result export
|
||||
-> AWatch-rus import directory
|
||||
-> schema validation
|
||||
-> derived findings JSON/SQLite
|
||||
-> optional case link
|
||||
-> portal forensics summary
|
||||
```
|
||||
|
||||
### Containment path
|
||||
|
||||
```text
|
||||
Finding/signals
|
||||
-> confidence and policy evaluation
|
||||
-> containment decision record
|
||||
-> admin-channel precheck
|
||||
-> shadow/manual/auto execution
|
||||
-> verify containment
|
||||
-> case/audit record
|
||||
-> TTL/rollback queue
|
||||
```
|
||||
|
||||
Raw artifacts and derived results must be separated:
|
||||
|
||||
- raw EVTX/result bundles: restricted evidence storage;
|
||||
- derived findings: sanitized AWatch-rus views;
|
||||
- operator notes/case links: case database;
|
||||
- public/demo exports: no raw hostnames, users, IPs, paths or secrets.
|
||||
|
||||
## Security and privacy guardrails
|
||||
|
||||
- Store no secrets in repo, docs, demo data or screenshots.
|
||||
- Do not commit generated Velociraptor config with private keys/client secrets.
|
||||
- Do not expose Velociraptor GUI publicly by default.
|
||||
- Default server bind should be loopback or private VPN-only address.
|
||||
- Require explicit operator action for client deployment.
|
||||
- Require retention policy for raw artifacts.
|
||||
- Require redaction for export/demo packs.
|
||||
- Require audit log for artifact imports, deletes and case links.
|
||||
- Treat Velociraptor outputs as untrusted input: validate schema, size, paths
|
||||
and timestamps before import.
|
||||
- Never execute arbitrary downloaded artifacts without pinning/checksums.
|
||||
- Never run containment if management channel would be lost.
|
||||
- Never auto-contain servers unless explicitly allowed and tested.
|
||||
- Always create rollback record before applying a block.
|
||||
- Always include TTL or manual release path.
|
||||
- Always log who/what triggered containment, which signals were used and which
|
||||
network paths remain allowed.
|
||||
|
||||
## Containment decision model
|
||||
|
||||
Inputs:
|
||||
|
||||
- high/critical Hayabusa/Sigma rule hits;
|
||||
- suspicious Windows event sequence from Velociraptor artifact;
|
||||
- AWatch-rus endpoint signals such as mass file changes, unusual process/file
|
||||
behavior, DLP/security signal spikes;
|
||||
- administrator manual flag.
|
||||
|
||||
Decision fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"host": "HOST",
|
||||
"host_role": "workstation",
|
||||
"state": "suspected_infected",
|
||||
"confidence": "medium|high|critical",
|
||||
"signals": ["hayabusa:rule-id", "velociraptor:artifact"],
|
||||
"recommended_action": "windows_firewall_quarantine",
|
||||
"mode": "shadow|manual_approval|auto",
|
||||
"ttl_minutes": 60,
|
||||
"management_channel_checked": true,
|
||||
"rollback_plan_id": "opaque-id"
|
||||
}
|
||||
```
|
||||
|
||||
Minimum threshold for automatic quarantine:
|
||||
|
||||
- host role is workstation;
|
||||
- host is not in denylist of critical infrastructure;
|
||||
- at least one critical signal or multiple high-confidence signals;
|
||||
- management channel precheck passed;
|
||||
- containment action is in allowlist;
|
||||
- rollback record successfully written.
|
||||
|
||||
## Current implementation status
|
||||
|
||||
Implemented first safe layer:
|
||||
|
||||
- Rust CLI `containment-engine`;
|
||||
- strict JSON parsing for policy/finding input;
|
||||
- example files:
|
||||
`configs/containment-policy.example.json`,
|
||||
`configs/containment-finding.example.json`,
|
||||
`configs/windows-firewall-containment-request.example.json`;
|
||||
- disabled-by-default Ansible/env configuration;
|
||||
- `shadow`, `manual_approval` and `auto` decision states;
|
||||
- automatic containment refused for non-workstation roles by default;
|
||||
- `would_mutate=false` in current implementation;
|
||||
- Windows Firewall executor interface:
|
||||
`plan`, `apply`, `verify`, `rollback`;
|
||||
- Windows Firewall dry-run generates PowerShell `New-NetFirewallRule`,
|
||||
`Get-NetFirewallRule` and `Remove-NetFirewallRule` commands;
|
||||
- Windows Firewall execution is fail-closed without explicit confirmation and
|
||||
`--execute-local`;
|
||||
- Security Finding Inbox:
|
||||
ClickHouse schema, Rust ingest CLI, Hayabusa/Velociraptor source adapters,
|
||||
portal page `Подозрительные станции` and separate executor process for
|
||||
approved `apply_requested` workflow;
|
||||
- smoke script:
|
||||
`bash scripts/containment_shadow_smoke.sh`;
|
||||
- operator/policy docs:
|
||||
`docs/CONTAINMENT_OPERATOR_RUNBOOK_RU.md`,
|
||||
`docs/CONTAINMENT_POLICY_RU.md`.
|
||||
|
||||
Not implemented yet:
|
||||
|
||||
- production-verified Windows Firewall mutation on lab/real workstations;
|
||||
- real pfSense alias/table mutation;
|
||||
- AD/VLAN executor;
|
||||
- TTL rollback service;
|
||||
- portal containment action execution. The current portal records workflow
|
||||
events only and does not mutate firewall/network state; mutation is reserved
|
||||
for `security-finding-inbox executor` with explicit local Windows
|
||||
confirmation.
|
||||
|
||||
## Codex implementation plan
|
||||
|
||||
### Phase 0. Architecture and docs only
|
||||
|
||||
Files:
|
||||
|
||||
- `docs/LOW_COST_SIGMA_HAYABUSA_VELOCIRAPTOR_ADDON_RU.md`;
|
||||
- `docs/PROJECT_STATUS_RU.md`;
|
||||
- `docs/REGISTRY_FUNCTIONAL_SCOPE_RU.md`;
|
||||
- `README.md`.
|
||||
|
||||
Tasks:
|
||||
|
||||
- record addon scope and non-goals;
|
||||
- document upstream references and license/supply-chain review requirement;
|
||||
- state that module is planned/optional until implemented;
|
||||
- keep forbidden SIEM/DLP/СЗИ claims blocked.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- docs mention optional low-cost containment/forensics layer;
|
||||
- no runtime/API/UI/product code change;
|
||||
- secret scan and diff check pass.
|
||||
|
||||
### Phase 1. Inventory current Hayabusa implementation
|
||||
|
||||
Files:
|
||||
|
||||
- `aw-server/hayabusa/README.md`;
|
||||
- `aw-server/hayabusa/aw-hayabusa.sh`;
|
||||
- `adk-rust/crates/hayabusa-tools/`;
|
||||
- `windows/export-evtx-for-hayabusa.ps1`;
|
||||
- `windows/export-upload-hayabusa-to-aw-server.ps1`;
|
||||
- `ansible/deploy_aw_server.yml`;
|
||||
- `ansible/deploy_aw_windows.yml`.
|
||||
|
||||
Tasks:
|
||||
|
||||
- document installed binaries, units, timers, directories and retention;
|
||||
- verify current drop/inbox/quarantine behavior;
|
||||
- add a manifest file for current Hayabusa server bundle;
|
||||
- add a read-only status command if missing.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- `aw-hayabusa doctor` remains green;
|
||||
- bad zip quarantine behavior remains intact;
|
||||
- no change to DLP disabled runtime state.
|
||||
|
||||
### Phase 2. Supply-chain manifest and pinned downloads
|
||||
|
||||
New files:
|
||||
|
||||
- `third_party/forensics/manifest.json`;
|
||||
- `scripts/prepare_forensics_binaries.sh`;
|
||||
- `docs/FORENSICS_SUPPLY_CHAIN_RU.md`.
|
||||
|
||||
Tasks:
|
||||
|
||||
- define pinned versions for Hayabusa, Hayabusa rules and Velociraptor;
|
||||
- define SHA256 checksums and source URLs;
|
||||
- support offline cache directory;
|
||||
- fail closed if checksum mismatch;
|
||||
- never auto-update rules in production unless explicitly enabled.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- dry-run prints planned downloads only;
|
||||
- checksum verification works on cached fixture;
|
||||
- no network required for deploy when cache exists.
|
||||
|
||||
### Phase 3. Optional Velociraptor server install
|
||||
|
||||
New/changed files:
|
||||
|
||||
- `ansible/group_vars/all.yml`;
|
||||
- `ansible/group_vars/all.example.yml`;
|
||||
- `ansible/deploy_aw_server.yml`;
|
||||
- `ops/systemd/velociraptor.service`;
|
||||
- `docs/VELOCIRAPTOR_DEPLOYMENT_RU.md`.
|
||||
|
||||
Tasks:
|
||||
|
||||
- add `aw_velociraptor_enabled=false` default;
|
||||
- install Velociraptor binary only when enabled;
|
||||
- generate config only on target host, not in repo;
|
||||
- bind to loopback/private address by default;
|
||||
- store datastore under `/var/lib/velociraptor`;
|
||||
- store config under `/etc/velociraptor`;
|
||||
- add systemd service with resource limits;
|
||||
- avoid public exposure unless explicitly configured.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- disabled mode creates no running service;
|
||||
- enabled mode installs service and returns local health;
|
||||
- generated config is not committed;
|
||||
- Ansible syntax check passes.
|
||||
|
||||
### Phase 4. Velociraptor client/offline collector packaging
|
||||
|
||||
Files:
|
||||
|
||||
- `ansible/deploy_aw_windows.yml`;
|
||||
- `windows/ActivityWatch.Windows.Common.psm1`;
|
||||
- `windows/validate-deployment.ps1`;
|
||||
- optional `windows/install-velociraptor-client.ps1`.
|
||||
|
||||
Tasks:
|
||||
|
||||
- add explicit deployment mode:
|
||||
`disabled|offline_collector|client_service`;
|
||||
- package client installer/offline collector from pinned binary/config;
|
||||
- install client service only when explicitly enabled;
|
||||
- keep scheduled/manual offline collector for low-cost mode;
|
||||
- log to `C:\ProgramData\AWatch-rus\logs\velociraptor-*.log`;
|
||||
- include service/task checks in validation only when enabled.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- disabled mode leaves Windows host untouched;
|
||||
- offline collector can run and produce an export bundle;
|
||||
- service mode reports healthy enrollment without exposing credentials.
|
||||
|
||||
### Phase 5. Hayabusa/Sigma artifact integration
|
||||
|
||||
Files:
|
||||
|
||||
- `third_party/forensics/artifacts/`;
|
||||
- `scripts/import_velociraptor_artifact_pack.sh`;
|
||||
- `docs/HAYABUSA_SIGMA_RULES_RU.md`.
|
||||
|
||||
Tasks:
|
||||
|
||||
- import/prepare `Windows.Hayabusa.Monitoring` artifact pack;
|
||||
- document mapping to Hayabusa rules;
|
||||
- create curated profile:
|
||||
`low-cost-default`, `incident`, `full`;
|
||||
- add noisy-rule tuning file;
|
||||
- require version metadata in every run.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- artifact pack import is reproducible;
|
||||
- rules profile can be listed without running collection;
|
||||
- config supports small-host low-resource default.
|
||||
|
||||
### Phase 6. AWatch-rus result import
|
||||
|
||||
Prefer Rust.
|
||||
|
||||
New crate or extension:
|
||||
|
||||
- `adk-rust/crates/forensics-importer`;
|
||||
or extend `adk-rust/crates/hayabusa-tools`.
|
||||
|
||||
Tasks:
|
||||
|
||||
- import Hayabusa JSON/JSONL/CSV summary;
|
||||
- import Velociraptor artifact result export;
|
||||
- normalize to derived finding schema:
|
||||
`source`, `host`, `time`, `rule`, `level`, `mitre`, `summary`,
|
||||
`evidence_ref`, `case_id`, `tool_version`, `rules_version`;
|
||||
- reject oversized, malformed and path-traversal payloads;
|
||||
- write derived SQLite/JSON under `/var/lib/activitywatch/forensics`;
|
||||
- do not copy raw artifacts unless `AW_FORENSICS_STORE_RAW_ARTIFACTS=true`.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- unit tests cover malformed JSON, oversized file, path traversal, empty result;
|
||||
- fixture import produces stable output;
|
||||
- raw-sensitive data is not rendered in default portal view.
|
||||
|
||||
### Phase 7. Containment control plane
|
||||
|
||||
Prefer Rust.
|
||||
|
||||
New crate or extension:
|
||||
|
||||
- `adk-rust/crates/containment-engine`;
|
||||
or extend `adk-rust/crates/forensics-importer` with a separate module.
|
||||
|
||||
Tasks:
|
||||
|
||||
- define containment decision schema and audit log;
|
||||
- add policy file:
|
||||
`/etc/activitywatch/containment-policy.json`;
|
||||
- add host role model:
|
||||
`workstation|server|domain_controller|unknown`;
|
||||
- add safe defaults:
|
||||
`enabled=false`, `mode=shadow`, server auto-containment disabled;
|
||||
- implement decision evaluation from imported findings;
|
||||
- implement dry-run/shadow output;
|
||||
- implement manual approval queue;
|
||||
- implement rollback record format.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- unit tests cover workstation/server/unknown host roles;
|
||||
- automatic action is refused for server/unknown role by default;
|
||||
- no action runs if management channel precheck fails;
|
||||
- shadow mode produces audit record and does not mutate host/network.
|
||||
|
||||
### Phase 8. Containment executors
|
||||
|
||||
Executor targets:
|
||||
|
||||
- Windows firewall quarantine through PowerShell/Rust Windows helper;
|
||||
- pfSense alias/table block through explicit API/SSH integration;
|
||||
- optional switch/VLAN integration only behind feature flag.
|
||||
|
||||
Tasks:
|
||||
|
||||
- implement executor interface:
|
||||
`plan`, `apply`, `verify`, `rollback`;
|
||||
- first implemented executor: Windows Firewall explicit management allowlist
|
||||
plus explicit block ranges, without broad `Any`/`LocalSubnet` block and
|
||||
without default firewall profile changes;
|
||||
- apply pfSense host block using IP/MAC only after current lease/identity
|
||||
verification;
|
||||
- store rollback before mutation;
|
||||
- add TTL-based rollback timer;
|
||||
- add emergency release command.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- fixture mode shows exact firewall/pfSense plan;
|
||||
- apply refuses empty allowlist;
|
||||
- verify confirms blocked lateral path and allowed management path;
|
||||
- rollback restores previous rules;
|
||||
- logs contain no secrets.
|
||||
|
||||
### Phase 9. Portal and API integration
|
||||
|
||||
Files:
|
||||
|
||||
- `adk-rust/crates/detmir-portal/`;
|
||||
- `docs/PORTAL_API_CONTRACTS_RU.md`;
|
||||
- `docs/DETMIR_CURRENT_STATE_RU.md`.
|
||||
|
||||
Tasks:
|
||||
|
||||
- add optional forensics module state:
|
||||
`disabled|not_configured|ready|degraded`;
|
||||
- show derived findings count, latest run, severity histogram;
|
||||
- show containment state:
|
||||
`disabled|shadow|recommended|contained|rollback_pending|released`;
|
||||
- show clear action buttons only for authorized admin/security roles;
|
||||
- link to case/evidence only by opaque ID;
|
||||
- do not block Workforce first screen;
|
||||
- do not include raw artifacts in frontend payload.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- with module disabled, portal shows disabled-state and remains fast;
|
||||
- with fixture findings, portal renders summary;
|
||||
- with fixture containment recommendation, portal renders action state without
|
||||
applying action;
|
||||
- Playwright smoke confirms no endless loading and no raw sensitive fields.
|
||||
|
||||
### Phase 10. Health/readiness/checks
|
||||
|
||||
Files:
|
||||
|
||||
- `adk-rust/crates/detmir-check/`;
|
||||
- `adk-rust/crates/detmir-readiness/`;
|
||||
- `scripts/detmir-full-diagnostics/aw-contour-diag.sh`;
|
||||
- `scripts/aw-contour-diag.sh`;
|
||||
- `check-aw-full.sh`.
|
||||
|
||||
Tasks:
|
||||
|
||||
- add optional forensics status checks;
|
||||
- disabled mode must be OK/Skipped, not fail;
|
||||
- add optional containment status checks;
|
||||
- enabled mode checks:
|
||||
Velociraptor service, artifact pack, latest run age, importer health,
|
||||
queue/quarantine counts, containment executor health;
|
||||
- add resource pressure checks for long-running scans.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- disabled mode produces `forensics:mode=disabled`;
|
||||
- disabled containment mode produces `containment:mode=disabled`;
|
||||
- enabled mode fails closed on stale/broken artifact importer;
|
||||
- containment auto mode fails closed if rollback store or admin-channel precheck
|
||||
is unavailable;
|
||||
- checks do not restart services unless explicit autoheal mode exists.
|
||||
|
||||
### Phase 11. Runtime safety and resource budgets
|
||||
|
||||
Files:
|
||||
|
||||
- systemd units/timers;
|
||||
- Ansible vars;
|
||||
- docs runbooks.
|
||||
|
||||
Tasks:
|
||||
|
||||
- enforce `Nice`, `IOSchedulingClass`, CPU quota and timeout for heavy scans;
|
||||
- serialize jobs through lock file;
|
||||
- add cancellation/timeout behavior;
|
||||
- quarantine failed artifact runs;
|
||||
- keep `aw-server-rust`, worktime API, ClickHouse and portal out of the scan
|
||||
critical path.
|
||||
- enforce containment mutation lock so two block/unblock actions cannot race.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- two concurrent scan requests do not run two heavy jobs;
|
||||
- timeout leaves a clear failed run record;
|
||||
- core health remains green under disabled mode.
|
||||
- rollback timer is tested and idempotent.
|
||||
|
||||
### Phase 12. Documentation and operator runbooks
|
||||
|
||||
New docs:
|
||||
|
||||
- `docs/VELOCIRAPTOR_DEPLOYMENT_RU.md`;
|
||||
- `docs/FORENSICS_SUPPLY_CHAIN_RU.md`;
|
||||
- `docs/FORENSICS_OPERATOR_RUNBOOK_RU.md`;
|
||||
- `docs/FORENSICS_RETENTION_POLICY_RU.md`;
|
||||
- `docs/FORENSICS_PRIVACY_GUARDRAILS_RU.md`.
|
||||
- `docs/CONTAINMENT_OPERATOR_RUNBOOK_RU.md`;
|
||||
- `docs/CONTAINMENT_POLICY_RU.md`.
|
||||
|
||||
Tasks:
|
||||
|
||||
- describe installation modes;
|
||||
- describe offline collector workflow;
|
||||
- describe artifact run, import, case link and cleanup;
|
||||
- describe forbidden data in screenshots/demo packs;
|
||||
- document rollback and disable commands.
|
||||
- describe quarantine policy, management allowlist, manual approval, emergency
|
||||
release and TTL rollback.
|
||||
|
||||
Acceptance:
|
||||
|
||||
- admin can install disabled/offline/server modes from docs;
|
||||
- admin can test shadow containment safely before auto mode;
|
||||
- docs clearly say GitHub/public demo is not evidence storage;
|
||||
- no claim of SIEM/DLP/EDR/СЗИ replacement.
|
||||
|
||||
### Phase 13. Tests and gates
|
||||
|
||||
Required checks:
|
||||
|
||||
```bash
|
||||
python3 scripts/public_secret_pattern_check.py
|
||||
bash -n scripts/prepare_forensics_binaries.sh
|
||||
ansible-playbook -i ansible/inventory.ini ansible/deploy_aw_server.yml --syntax-check
|
||||
ansible-playbook -i ansible/inventory.ini ansible/deploy_aw_windows.yml --syntax-check
|
||||
|
||||
cd adk-rust
|
||||
export CARGO_TARGET_DIR=/home/igor/.cache/detmir-adk-rust-target
|
||||
cargo fmt --all --check
|
||||
cargo test -p hayabusa-tools
|
||||
cargo test -p forensics-importer
|
||||
cargo test -p containment-engine
|
||||
cargo clippy -p hayabusa-tools -p forensics-importer -p containment-engine --all-targets -- -D warnings
|
||||
|
||||
cd ..
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Manual/live checks:
|
||||
|
||||
- disabled mode on clean install;
|
||||
- Hayabusa current drop-zone smoke;
|
||||
- Velociraptor offline collector fixture run;
|
||||
- Velociraptor server health if enabled;
|
||||
- containment shadow run with fixture critical finding;
|
||||
- manual approval containment in isolated lab host;
|
||||
- rollback verification;
|
||||
- portal browser smoke with module disabled and with fixture findings;
|
||||
- no public exposure of Velociraptor GUI unless explicitly configured.
|
||||
|
||||
## Codex guardrails
|
||||
|
||||
Codex must not:
|
||||
|
||||
- change Workforce core behavior while adding this module;
|
||||
- re-enable heavy DLP runtime by accident;
|
||||
- expose Velociraptor or Hayabusa outputs publicly;
|
||||
- commit generated secrets, private configs or raw evidence;
|
||||
- auto-block hosts before policy, allowlist, rollback and admin-channel checks
|
||||
exist;
|
||||
- auto-block servers/domain infrastructure by default;
|
||||
- claim completed integration before live/manual evidence exists;
|
||||
- change Rust/API/UI runtime outside the planned files without documenting why.
|
||||
|
||||
Codex should:
|
||||
|
||||
- start with docs/config disabled mode;
|
||||
- implement supply-chain pinning before service deployment;
|
||||
- prefer Rust for import/validation/parsing;
|
||||
- treat containment as a separate audited control plane, not as generic
|
||||
remediation;
|
||||
- keep PowerShell only for Windows install/run wrappers;
|
||||
- add small fixtures and negative tests before live deployment;
|
||||
- update project status after each successfully verified phase.
|
||||
|
||||
## Expected result
|
||||
|
||||
After implementation AWatch-rus should have:
|
||||
|
||||
- installed/pinned Hayabusa and rules workflow;
|
||||
- optional bundled Velociraptor server/client/offline collector modes;
|
||||
- reproducible artifact pack handling for `Windows.Hayabusa.Monitoring`;
|
||||
- derived findings importer into AWatch-rus forensics views;
|
||||
- policy-controlled automated/manual quarantine of suspected infected
|
||||
workstations;
|
||||
- rollback and emergency release path for every containment action;
|
||||
- disabled-by-default safety;
|
||||
- resource-bounded scans;
|
||||
- clear runbooks for poor/small organizations;
|
||||
- honest positioning as low-cost containment, security analytics and forensics, not
|
||||
SIEM/DLP/EDR/СЗИ.
|
||||
@@ -0,0 +1,279 @@
|
||||
# Security Finding Inbox
|
||||
|
||||
Дата: 2026-06-25.
|
||||
|
||||
Security Finding Inbox - это очередь подозрительных рабочих станций для
|
||||
связки Hayabusa/Sigma, Velociraptor, AWatch context и ручных ИБ-сигналов.
|
||||
Очередь нужна для контролируемого процесса:
|
||||
|
||||
```text
|
||||
finding -> triage -> decide -> plan -> approve -> apply_requested -> executor -> verify/rollback
|
||||
```
|
||||
|
||||
Важно: портал inbox сам не применяет Windows Firewall, pfSense, AD или VLAN
|
||||
изменения. Он фиксирует findings и workflow-события. Реальное применение
|
||||
делается отдельным процессом `security-finding-inbox executor`, который
|
||||
вызывает `containment-engine windows-firewall plan/apply/verify/rollback`.
|
||||
По умолчанию executor работает безопасно: dry-run/fail-closed, без локального
|
||||
изменения firewall.
|
||||
|
||||
## Компоненты
|
||||
|
||||
- ClickHouse schema:
|
||||
`clickhouse-1c/security/security_finding_inbox.sql`
|
||||
- normalized finding example:
|
||||
`configs/security/security-finding.example.json`
|
||||
- ingest/workflow CLI:
|
||||
`adk-rust/crates/security-finding-inbox`
|
||||
- executor CLI:
|
||||
`security-finding-inbox executor`
|
||||
- portal API:
|
||||
`/api/security/findings`
|
||||
`/api/security/findings/workflow`
|
||||
- portal page:
|
||||
`Подозрительные станции`
|
||||
|
||||
## ClickHouse tables
|
||||
|
||||
`security_findings`
|
||||
|
||||
- normalized finding records;
|
||||
- source: `hayabusa`, `sigma`, `velociraptor`, `awatch`, `manual`, `dlp`;
|
||||
- states: `new`, `suspected_infected`, `confirmed_infected`, `contained`,
|
||||
`released`, `false_positive`;
|
||||
- recommended action remains a recommendation, not a mutation.
|
||||
|
||||
`security_finding_workflow_events`
|
||||
|
||||
- append-only workflow audit;
|
||||
- event types: `decide_requested`, `plan_requested`, `approved`,
|
||||
`apply_requested`, `verify_requested`, `rollback_requested`, `rejected`,
|
||||
`false_positive`, plus executor audit events:
|
||||
`executor_plan_ready`, `executor_apply_succeeded`,
|
||||
`executor_apply_failed`, `executor_verify_succeeded`,
|
||||
`executor_verify_failed`, `executor_refused`,
|
||||
`executor_rollback_succeeded`, `executor_rollback_failed`;
|
||||
- portal writes only workflow events.
|
||||
|
||||
`security_finding_inbox`
|
||||
|
||||
- latest-state view for portal/dashboard;
|
||||
- filters released/rejected/false-positive rows out of the active queue.
|
||||
|
||||
## Ingest
|
||||
|
||||
Build:
|
||||
|
||||
```bash
|
||||
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 security-finding-inbox
|
||||
```
|
||||
|
||||
Validate sample:
|
||||
|
||||
```bash
|
||||
security-finding-inbox validate \
|
||||
--input configs/security/security-finding.example.json
|
||||
```
|
||||
|
||||
Dry-run ingest:
|
||||
|
||||
```bash
|
||||
security-finding-inbox ingest \
|
||||
--input configs/security/security-finding.example.json \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
Apply schema and ingest into ClickHouse:
|
||||
|
||||
```bash
|
||||
security-finding-inbox ingest \
|
||||
--input configs/security/security-finding.example.json \
|
||||
--clickhouse-url http://10.10.10.2:8123 \
|
||||
--database analytics_1c \
|
||||
--user "$CLICKHOUSE_USER" \
|
||||
--password "$CLICKHOUSE_PASSWORD" \
|
||||
--apply-schema
|
||||
```
|
||||
|
||||
The CLI accepts a single JSON object, JSON array, or JSONL.
|
||||
|
||||
### Real Hayabusa source
|
||||
|
||||
После `aw-hayabusa process-inbox` реальный источник находится в
|
||||
`/opt/hayabusa/state/latest-intake.json`. CLI читает `report_dir`, анализирует
|
||||
`timeline.jsonl`, logon summaries и строит normalized finding:
|
||||
|
||||
```bash
|
||||
security-finding-inbox ingest-hayabusa \
|
||||
--intake /opt/hayabusa/state/latest-intake.json \
|
||||
--min-severity medium \
|
||||
--clickhouse-url http://127.0.0.1:8123 \
|
||||
--database analytics_1c
|
||||
```
|
||||
|
||||
Для автоматического подключения Hayabusa drop/autoprocess:
|
||||
|
||||
```bash
|
||||
AW_SECURITY_FINDING_INBOX_ENABLED=true
|
||||
AW_SECURITY_FINDING_INBOX_BIN=/usr/local/bin/security-finding-inbox
|
||||
AW_SECURITY_FINDING_INBOX_MIN_SEVERITY=medium
|
||||
```
|
||||
|
||||
`AW_SECURITY_FINDING_INBOX_REQUIRED=false` оставляет forensic pipeline живым,
|
||||
если ClickHouse или inbox CLI временно недоступны. В `true`-режиме ошибка
|
||||
ingest считается operational failure.
|
||||
|
||||
### Real Velociraptor source
|
||||
|
||||
Velociraptor artifact JSON/JSONL можно загрузить через generic adapter:
|
||||
|
||||
```bash
|
||||
security-finding-inbox ingest-velociraptor-json \
|
||||
--input /path/to/velociraptor-artifact.jsonl \
|
||||
--default-severity high \
|
||||
--clickhouse-url http://127.0.0.1:8123 \
|
||||
--database analytics_1c
|
||||
```
|
||||
|
||||
Adapter ищет стандартные поля `Hostname`, `Artifact`, `Severity`, `Message`,
|
||||
`User`, `IP`. Если формат артефакта отличается, используйте normalized
|
||||
`security-finding-inbox ingest --input ...`.
|
||||
|
||||
## Portal workflow
|
||||
|
||||
Open:
|
||||
|
||||
```text
|
||||
DetMir Portal -> Подозрительные станции
|
||||
```
|
||||
|
||||
The page shows:
|
||||
|
||||
- host/user/IP/department;
|
||||
- severity/confidence/score;
|
||||
- source/rule;
|
||||
- state and latest workflow status;
|
||||
- recommended action;
|
||||
- workflow buttons.
|
||||
|
||||
Portal buttons record only workflow events:
|
||||
|
||||
- `decide`: request decision calculation;
|
||||
- `plan`: request containment plan;
|
||||
- `approve`: operator approval record;
|
||||
- `apply`: request to perform apply outside the portal;
|
||||
- `rollback`: rollback request record.
|
||||
|
||||
The portal does not run `containment-engine`, PowerShell, firewall commands or
|
||||
network changes.
|
||||
|
||||
## Executor handoff
|
||||
|
||||
Executor читает из ClickHouse только те findings, где:
|
||||
|
||||
- последний workflow event: `apply_requested`;
|
||||
- status: `apply_pending`;
|
||||
- ранее есть `approved`;
|
||||
- еще нет `executor_apply_succeeded`, `executor_apply_failed`,
|
||||
`executor_refused` или rollback terminal event.
|
||||
|
||||
Dry-run executor:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
Linux systemd example for central dry-run/polling mode:
|
||||
|
||||
```text
|
||||
ops/systemd/aw-security-finding-executor.service
|
||||
```
|
||||
|
||||
Real local Windows apply is allowed only when all conditions are true:
|
||||
|
||||
- executor runs on the target Windows workstation;
|
||||
- `--execute-local` is set;
|
||||
- `--confirm-execute YES` is set;
|
||||
- `--executor-host` or local `COMPUTERNAME` matches finding `host`;
|
||||
- containment policy returns `manual_approval_required` or `auto_ready`;
|
||||
- management allowlist and blocked remote ranges are explicit;
|
||||
- generated Windows Firewall plan has no blockers.
|
||||
|
||||
Example on the target Windows host:
|
||||
|
||||
```powershell
|
||||
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 writes `executor_*` workflow events back into ClickHouse. It does not
|
||||
update or delete source findings.
|
||||
|
||||
## Manual containment handoff
|
||||
|
||||
After a finding is approved:
|
||||
|
||||
1. Build or review a containment policy/finding.
|
||||
2. Run:
|
||||
|
||||
```bash
|
||||
containment-engine decide \
|
||||
--policy /etc/activitywatch/containment-policy.json \
|
||||
--finding /path/to/finding.json \
|
||||
--pretty
|
||||
```
|
||||
|
||||
3. Build Windows Firewall request with explicit management allowlist.
|
||||
4. Run:
|
||||
|
||||
```bash
|
||||
containment-engine windows-firewall plan \
|
||||
--request /path/to/windows-firewall-request.json \
|
||||
--pretty > /tmp/fw-plan.json
|
||||
```
|
||||
|
||||
5. Confirm `blockers=[]`.
|
||||
6. Dry-run:
|
||||
|
||||
```bash
|
||||
containment-engine windows-firewall apply \
|
||||
--plan /tmp/fw-plan.json \
|
||||
--confirm-apply YES \
|
||||
--pretty
|
||||
```
|
||||
|
||||
7. Real apply only on the target Windows host:
|
||||
|
||||
```powershell
|
||||
containment-engine.exe windows-firewall apply `
|
||||
--plan C:\Temp\fw-plan.json `
|
||||
--confirm-apply YES `
|
||||
--execute-local `
|
||||
--pretty
|
||||
```
|
||||
|
||||
## Guardrails
|
||||
|
||||
- Do not place raw employee logs, secrets, passwords or customer identifiers in
|
||||
findings.
|
||||
- Do not treat `apply_requested` as successful containment.
|
||||
- Do not run broad `Any`/`LocalSubnet` firewall blocks.
|
||||
- Do not enable automatic action for servers/domain controllers.
|
||||
- Keep GitHub/portal evidence separate from Russian registry release evidence.
|
||||
- Keep DLP optional: Hayabusa/Velociraptor findings can continue while heavy DLP
|
||||
runtime is disabled.
|
||||
@@ -31,7 +31,7 @@ journalctl -u aw-hayabusa-drop.service -n 80 --no-pager
|
||||
curl -fsS http://127.0.0.1:5602/api/0/dlp/cases/30
|
||||
```
|
||||
|
||||
Ожидаемо: `drop` и `incoming` пустые, `latest-intake.json` имеет `status=ok`, `host=SHARKON2025`, а `LastTaskResult` Windows-задачи равен `0`.
|
||||
Ожидаемо: `drop` и `incoming` пустые, `latest-intake.json` имеет `status=ok`, `host=<stable-aw-logical-host-id>`, а `LastTaskResult` Windows-задачи равен `0`. Для текущего DetMir production historical logical id может оставаться `SHARKON2025`, даже если физический `COMPUTERNAME` RDP-сервера изменён.
|
||||
|
||||
## Что получает оператор
|
||||
|
||||
|
||||
Reference in New Issue
Block a user