From 4ca1c30bc64e4c1c6a1862b1afb0277cd482d5f1 Mon Sep 17 00:00:00 2001 From: igor04091968 Date: Wed, 3 Jun 2026 08:21:59 +0300 Subject: [PATCH] docs(public): complete registry-facing docs --- INSTALL_FOR_EXPERT_RU.md | 53 +++++++++++++++++++++++++++++++++++++++ PRODUCT_DESCRIPTION_RU.md | 26 +++++++++++++++++++ README.md | 3 +++ THIRD_PARTY_COMPONENTS.md | 27 ++++++++++++++++++++ docs/runbook.md | 44 ++++++++++++++++---------------- 5 files changed, 131 insertions(+), 22 deletions(-) create mode 100644 INSTALL_FOR_EXPERT_RU.md create mode 100644 PRODUCT_DESCRIPTION_RU.md create mode 100644 THIRD_PARTY_COMPONENTS.md diff --git a/INSTALL_FOR_EXPERT_RU.md b/INSTALL_FOR_EXPERT_RU.md new file mode 100644 index 0000000..be7c91d --- /dev/null +++ b/INSTALL_FOR_EXPERT_RU.md @@ -0,0 +1,53 @@ +# Установка экземпляра для эксперта + +Этот документ дает короткий воспроизводимый путь проверки экземпляра без +привязки к личному стенду разработчика. + +## 1. Подготовка + +1. Склонировать репозиторий. +2. Создать приватную конфигурацию: + + ```bash + cp private-config/deploy.env.example private-config/deploy.env + ``` + +3. Создать локальный Ansible inventory на основе: + + ```bash + cp ansible/inventory.example.ini ansible/inventory.ini + ``` + +4. Заполнить адреса, учетные данные и токены конкретного тестового стенда. + +## 2. Сборка + +```bash +cd adk-rust +cargo build --release --workspace +``` + +## 3. Проверки до установки + +```bash +scripts/quality-gate.sh +ansible-playbook --syntax-check -i ansible/inventory.ini ansible/deploy_aw_server.yml +``` + +## 4. Установка + +Базовый серверный путь описан в `docs/INSTALL_RU.md`. Конкретный playbook +выбирается по проверяемой схеме: серверный runtime, Windows collectors, +Grafana dashboards или портал оператора. + +## 5. Smoke-проверка + +После установки: + +```bash +detmir-check +detmir-status +``` + +Ожидаемый результат: статус `OK`, отсутствуют критичные service failures и +stale/dead buckets для обязательных источников. diff --git a/PRODUCT_DESCRIPTION_RU.md b/PRODUCT_DESCRIPTION_RU.md new file mode 100644 index 0000000..6f8e007 --- /dev/null +++ b/PRODUCT_DESCRIPTION_RU.md @@ -0,0 +1,26 @@ +# Описание программного продукта DetMir / AWatch-rus + +`DetMir` на базе `AWatch-rus` - программный комплекс операционного контроля, +технического аудита и мониторинга ИТ-инфраструктуры. + +## Назначение + +Продукт предназначен для централизованного контроля состояния рабочих мест, +серверных сервисов, ActivityWatch telemetry, рабочих интервалов, операторских +runbook-проверок и прикладных событий расследования. + +## Основные функции + +- сбор и нормализация ActivityWatch telemetry; +- контроль свежести данных и состояния сборщиков; +- учет активности пользователей и удаленных сессий; +- витрины Grafana и портал оператора; +- runbook automation, health-check, SLO и безопасный auto-heal; +- evidence workflow для прикладных инцидентов; +- аудит действий оператора. + +## Позиционирование + +Продукт относится к классу средств управления ИТ-службой, +ИТ-инфраструктурой и ИТ-активами. Продукт не заявляется как +сертифицированная DLP, SIEM, EDR/XDR или средство защиты информации. diff --git a/README.md b/README.md index 969184f..336d57f 100755 --- a/README.md +++ b/README.md @@ -39,6 +39,9 @@ evidence и Hayabusa используются как прикладные мод - [Позиционирование для реестра российского ПО](docs/DETMIR_RUSSIAN_SOFTWARE_REGISTRY_POSITIONING_RU.md) - [Сведения для подачи в реестр](REGISTER_RU_SOFTWARE.md) +- [Описание продукта](PRODUCT_DESCRIPTION_RU.md) +- [Установка для эксперта](INSTALL_FOR_EXPERT_RU.md) +- [Сторонние компоненты](THIRD_PARTY_COMPONENTS.md) - [Архитектура](docs/ARCHITECTURE_RU.md) - [Установка](docs/INSTALL_RU.md) - [Руководство администратора](docs/ADMIN_GUIDE_RU.md) diff --git a/THIRD_PARTY_COMPONENTS.md b/THIRD_PARTY_COMPONENTS.md new file mode 100644 index 0000000..96b8ed4 --- /dev/null +++ b/THIRD_PARTY_COMPONENTS.md @@ -0,0 +1,27 @@ +# Сторонние компоненты + +Основной перечень сторонних компонентов ведется в +`docs/THIRD_PARTY_LICENSES_RU.md`. + +## Runtime и инфраструктура + +- ActivityWatch; +- Rust crates ecosystem; +- Grafana; +- Prometheus / InfluxDB compatible metrics stack; +- Ansible; +- PowerShell / Windows Task Scheduler; +- SQLite; +- Hayabusa и связанные DFIR-инструменты при включении модуля расследования. + +## Правило поставки + +В публичную поставку не входят production inventory, пароли, токены, домены, +IP-адреса конкретного экземпляра, customer runtime data и локальные операторские +пути. Такие параметры задаются в приватной конфигурации экземпляра. + +## Лицензии + +Для собственных частей проекта используется лицензия, указанная в `LICENSE`. +Лицензии сторонних компонентов должны проверяться перед коммерческой поставкой +и фиксироваться в составе release package. diff --git a/docs/runbook.md b/docs/runbook.md index f6c460f..d5015eb 100755 --- a/docs/runbook.md +++ b/docs/runbook.md @@ -415,17 +415,17 @@ Acceptance для этого сценария: - артефакты трассируются от `HOST` до `report_dir`; - follow-up не тащит сырые forensic данные в обычные AW buckets. -Known-good live proof `2026-05-21`: +Example regression proof template: -- `host=SHARKON2025` -- `case_id=30` -- `intake_id=20260521T125653Z_SHARKON2025-phase17-rerun3` -- `sha256=e86b9abbfc1d706ac706c6c8a89509ab17023344c50880641e9175f73f1198d4` -- `report_dir=/opt/hayabusa/reports/SHARKON2025/20260521T125654Z_incident_20260521T125653Z_SHARKON2025-phase17-rerun3` +- `host=` +- `case_id=` +- `intake_id=` +- `sha256=` +- `report_dir=/opt/hayabusa/reports//` - `latest-intake.json` status: `ok` - AW-rus case linkage stored under `forensics.hayabusa` -Что реально нашли в production validation: +Типовые проблемы, найденные при validation: - Windows zip с backslash path separators давал `unzip` warning rc=1; wrapper не должен валить intake на таком предупреждении. - timeline режимы должны использовать `rules/config`, а не корень rules directory. @@ -445,16 +445,16 @@ readlink -f /opt/hayabusa/state/latest-run ```sh curl -fsS http://127.0.0.1:5600/api/0/buckets | jq -r 'keys[] | select(test("^aw-dlp-"))' -curl -fsS http://127.0.0.1:5600/api/0/buckets/aw-dlp-incidents_SHARKON2025 | jq '{end:.metadata.end}' +curl -fsS http://127.0.0.1:5600/api/0/buckets/aw-dlp-incidents_ | jq '{end:.metadata.end}' ``` Контролируемый тест ingest: ```sh TS=$(date -u +%Y-%m-%dT%H:%M:%S.000Z) -PAYLOAD=$(jq -nc --arg ts "$TS" '{timestamp:$ts,duration:0,data:{ruleId:"selftest-dlp-incident",action:"alert",severity:"low",message:"Self-test DLP incident from runbook",signalType:"self_test",username:"AUTOTEST",sessionId:0,hostname:"SHARKON2025",source:"self-test"}}') -curl -fsS -X POST 'http://127.0.0.1:5600/api/0/buckets/aw-dlp-incidents_SHARKON2025/heartbeat?pulsetime=60' -H 'Content-Type: application/json' --data "$PAYLOAD" -curl -fsS 'http://127.0.0.1:5600/api/0/buckets/aw-dlp-incidents_SHARKON2025/events?limit=5' | jq '.[0].data' +PAYLOAD=$(jq -nc --arg ts "$TS" '{timestamp:$ts,duration:0,data:{ruleId:"selftest-dlp-incident",action:"alert",severity:"low",message:"Self-test DLP incident from runbook",signalType:"self_test",username:"AUTOTEST",sessionId:0,hostname:"",source:"self-test"}}') +curl -fsS -X POST 'http://127.0.0.1:5600/api/0/buckets/aw-dlp-incidents_/heartbeat?pulsetime=60' -H 'Content-Type: application/json' --data "$PAYLOAD" +curl -fsS 'http://127.0.0.1:5600/api/0/buckets/aw-dlp-incidents_/events?limit=5' | jq '.[0].data' ``` Если API видит событие, а bucket-страница в UI показывает старые `First/last event`, нажать `Обновить` на странице bucket и раскрыть `Events`. @@ -562,13 +562,13 @@ Get-CimInstance Win32_Process | 1. Поставить `incidentCapture.screenshotEnabled = false` в `deployment-config.json` (для каждого StateRoot). 2. Запустить `Start-ScheduledTask -TaskName 'ActivityWatch Recovery'`. -### SHARKON2025: `Активное время = 0s`, хотя `window`-события есть +### Windows host: `Активное время = 0s`, хотя `window`-события есть Симптом: - в Activity view за день видно `Worktime = 0s`; - `Top Window Titles / Top Categories / Category Tree` пустые; -- при этом bucket `aw-watcher-window_SHARKON2025` содержит свежие события. +- при этом bucket `aw-watcher-window_` содержит свежие события. Подтвержденная причина: @@ -577,43 +577,43 @@ Get-CimInstance Win32_Process | Быстрый recovery (с Linux admin host): -1. Проверить учетку входа. Для этого кейса рабочая учетная запись: `SHARKON2025\Администратор` (не `Administrator`). +1. Проверить учетку входа. Рабочую учетную запись задавать как параметр экземпляра: `\`. 2. Поднять remote execution через `wmiexec.py` с auth-file: ```sh -cat > /tmp/sharkon_ru.auth << 'EOF' -username = Администратор +cat > /tmp/detmir-windows.auth << 'EOF' +username = password = -domain = SHARKON2025 +domain = EOF -chmod 600 /tmp/sharkon_ru.auth +chmod 600 /tmp/detmir-windows.auth ``` 3. Запустить recovery task: ```sh -wmiexec.py -nooutput -A /tmp/sharkon_ru.auth \ +wmiexec.py -nooutput -A /tmp/detmir-windows.auth \ "powershell -NoProfile -Command \"Start-ScheduledTask -TaskName 'ActivityWatch Recovery'\"" ``` 4. Запустить все launch tasks: ```sh -wmiexec.py -nooutput -A /tmp/sharkon_ru.auth \ +wmiexec.py -nooutput -A /tmp/detmir-windows.auth \ "powershell -NoProfile -Command \"Get-ScheduledTask | Where-Object TaskName -like 'ActivityWatch Launch *' | ForEach-Object { Start-ScheduledTask -TaskName \$_.TaskName }\"" ``` 5. Подождать 10-20 секунд и проверить API на AW server (`:5600`): ```sh -curl -fsS 'http://:5600/api/0/buckets/aw-watcher-afk_SHARKON2025/events?limit=30' \ +curl -fsS 'http://:5600/api/0/buckets/aw-watcher-afk_/events?limit=30' \ | jq '{latest:.[0].timestamp, statuses:(group_by(.data.status)|map({status:.[0].data.status,count:length}))}' ``` Ожидаемо после фикса: - в свежих AFK-событиях появляется `status=not-afk`; -- `aw-watcher-window_SHARKON2025` продолжает обновляться; +- `aw-watcher-window_` продолжает обновляться; - после обновления страницы UI дневная сводка перестает быть `0s`. ### Сервис не стартует