28 KiB
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.Monitoringin Velociraptor Curated Sigma is an artifact intended to triage a Windows host and is based onWindows.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
Рабочее название модуля:
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;
- не писать, что найденные события являются доказанной атакой без ручной проверки.
Допустимая формулировка:
Optional low-cost containment, security analytics and forensics layer based on
open-source Hayabusa/Sigma/Velociraptor workflows.
Containment objective
Модуль должен отвечать на вопрос:
Как максимально быстро ограничить рабочую станцию, которая выглядит зараженной,
чтобы она не заражала соседние машины и не продолжала утечку/распространение?
Необходимо разделять:
suspected_infected- есть правила/сигналы/аномалии, достаточные для карантина по политике организации;confirmed_infected- есть ручное подтверждение администратора/ИБ;contained- станция технически ограничена;released- карантин снят вручную или по документированному rollback.
Containment actions должны быть обратимыми, журналируемыми и ограниченными по
blast radius. По умолчанию допускается shadow или manual_approval; fully
automatic quarantine включается только отдельным флагом и только после
allowlist/rollback проверки.
Architecture
Modes
-
disabled- default для conservative deployment;
- все readiness checks возвращают disabled-state;
- Workforce/ActivityWatch core не зависит от модуля.
-
hayabusa_offline- текущий базовый режим;
- Windows scheduled task экспортирует EVTX zip;
- серверный
aw-hayabusa-drop.pathпринимает package; aw-hayabusa-autoprocessвалидирует zip, process-inbox, quarantine.
-
velociraptor_offline_collector- для бедных/малых контуров без постоянно работающего Velociraptor server;
- AWatch-rus собирает/хранит signed offline collector bundle;
- запуск collector выполняется вручную или scheduled task;
- результаты импортируются как artifact bundle.
-
velociraptor_server_clients- optional managed mode;
- Linux server рядом с AW/Proxmox или отдельной VM;
- Windows clients ставятся только явным Ansible-флагом;
- используется для управляемого запуска
Windows.Hayabusa.Monitoring.
-
containment_shadow- decision engine считает, что сделал бы, но ничего не блокирует;
- безопасный default для пилота;
- используется для настройки правил и false-positive анализа.
-
containment_manual_approval- система формирует containment recommendation;
- администратор подтверждает действие в CLI/портале;
- все действия пишутся в audit trail.
-
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:
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:
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
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
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
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:
{
"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_approvalandautodecision states;- automatic containment refused for non-workstation roles by default;
would_mutate=falsein current implementation;- Windows Firewall executor interface:
plan,apply,verify,rollback; - Windows Firewall dry-run generates PowerShell
New-NetFirewallRule,Get-NetFirewallRuleandRemove-NetFirewallRulecommands; - 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 approvedapply_requestedworkflow; - 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 executorwith 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 doctorremains 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=falsedefault; - 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.Monitoringartifact 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 extendadk-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 extendadk-rust/crates/forensics-importerwith 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/LocalSubnetblock 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:
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/СЗИ.