docs: add production validation audit

This commit is contained in:
igor04091968
2026-06-07 21:39:32 +03:00
parent 1b817866a4
commit 347347b835
3 changed files with 870 additions and 0 deletions
+407
View File
@@ -0,0 +1,407 @@
# AWatch-rus Production Validation
Дата проверки: 2026-06-07.
Статус: рабочий внутренний pilot-контур подтвержден частично. Контур собирает и
показывает реальные данные, но перед расширением пилота нужно закрыть
deployment/version drift между Demo Freeze v1 и фактически запущенным portal
runtime.
## Executive Summary
Проверка выполнялась read-only по рабочему внутреннему контуру на нескольких
пользователях. Реальные payload, логи, screenshots, IP-адреса, hostname,
логины, ФИО и подразделения в репозиторий не сохранялись.
Подтверждено:
- gateway и portal service доступны;
- базовый portal UI открывается;
- ActivityWatch API доступен и содержит свежие buckets;
- `/portal/api/reports` отвечает по ролям;
- Security events backend в рабочем контуре подключен;
- role gates в существующем portal smoke срабатывают;
- Forensics view и базовые portal tabs открываются;
- Windows runtime содержит активный текущий агентский процесс и watcher-процессы.
Ключевые gaps:
- фактический portal runtime отстает от Demo Freeze v1: отдельные endpoints
`/portal/api/workforce/kpi/explain`, `/portal/api/risk/narrative` и
`/portal/api/actions` на live-контуре возвращают `404`;
- production-hardening endpoints `/healthz`, `/readyz`, `/version`, `/metrics`
не доступны на фактическом portal port; gateway-level `/healthz` отвечает,
но это не заменяет portal production contract;
- request id / correlation id headers на live portal API не возвращаются;
- Executive visual conformance не проходит по текущему freeze smoke: в рабочем
runtime не отображаются новые Pilot v1 блоки Risk Narrative / Explainable KPI
/ Recommended Actions;
- UEBA на live-контуре возвращает `critical` score; нужна ручная проверка
evidence, чтобы отличить реальный риск от шумного правила.
Вывод: контур можно использовать для ограниченного внутреннего просмотра
реальных данных и сбора обратной связи, но не стоит расширять пилот до
10-50 пользователей, пока не закрыт deployment/version drift.
## Scope
Проверялось:
- runtime health;
- gateway/portal topology;
- portal tabs and role views;
- Workforce KPI и related report structure;
- Explainable KPI availability;
- UEBA;
- Risk Narrative availability;
- Executive Action Center availability;
- agent/data flow;
- performance snapshot;
- data hygiene.
Не проверялось:
- destructive recovery;
- restart/redeploy;
- изменение правил scoring;
- изменение collectors;
- production rollout новой версии;
- raw evidence review с персональными данными.
## Environment
Обезличенно:
- пользователей: несколько;
- контур: working internal pilot;
- данные: реальные, но в документе не раскрываются;
- gateway: отдельный reverse-proxy host с внешней авторизацией;
- portal runtime: локальный сервис на gateway host;
- ActivityWatch/worktime: отдельный AW-rus server;
- Windows runtime: RDP host с текущим агентским контуром.
## Runtime Health
Проверено:
| Поверхность | Результат | Комментарий |
| --- | --- | --- |
| Gateway `/healthz` | `200` | Nginx/gateway-level health отвечает |
| Gateway `/portal/` | `401` снаружи | Внешний доступ закрыт авторизацией |
| Portal local `/portal/` | `200` | UI доступен на gateway host |
| Portal local `/portal/api/health` | `200` | API health доступен |
| Portal local `/healthz` | `404` | Production-hardening endpoint не доступен на live runtime |
| Portal local `/readyz` | `404` | Production-hardening endpoint не доступен на live runtime |
| Portal local `/version` | `404` | Production-hardening endpoint не доступен на live runtime |
| Portal local `/metrics` | `404` | Production-hardening endpoint не доступен на live runtime |
| ActivityWatch `/api/0/settings` | `200` | AW API отвечает |
Request/correlation headers:
- `X-Request-Id`: не возвращается live portal API;
- `X-Correlation-Id`: не возвращается live portal API.
Metrics:
- Prometheus metrics format на фактическом portal runtime не подтвержден,
потому что `/metrics` возвращает `404`.
## Portal Validation
Проверено через tunnel к фактическому gateway-local portal port. Screenshots
создавались только во временном каталоге вне репозитория и не коммитились.
Результат `scripts/browser-conformance-smoke.mjs` на live-контуре:
| View | Результат | Комментарий |
| --- | --- | --- |
| Executive | FAIL | Не найдены Pilot v1 blocks: KPI, Explainable KPI, Risk Narrative, Recommended Actions |
| Workforce | FAIL | Не найдены ожидаемые freeze-маркеры KPI/Trend/Explainability |
| Security | FAIL | Не найдены ожидаемые freeze-маркеры security/risk/action blocks |
| Forensics | OK | Расследования, timeline, материалы и аудит отображаются |
Результат `scripts/detmir-portal-tabs-smoke.mjs` на live-контуре:
- базовые tabs открываются;
- loading status доходит до ready;
- role switcher есть;
- Security events доступны;
- manager/security/forensics/admin view checks проходят;
- server role gates проходят;
- Executive dashboard layer и expected management block order не проходят.
## KPI Validation
`/portal/api/reports?role=executive` возвращает валидный JSON и содержит:
- `kpis`: массив агрегированных KPI;
- `workforce`: объект с `department_comparison`, `owner_comparison`, `trend`,
`trend_status`, `insights`;
- `business_risk`;
- `risk_heatmap`;
- `security_events_summary`.
Обезличенные счетчики live response:
- KPI entries: `13`;
- department comparison entries: `1`;
- owner comparison entries: `3`;
- business risk entries: `2`;
- risk heatmap entries: `7`.
Оценка:
- базовый Workforce/Business Risk слой на live-контуре присутствует;
- KPI выглядит как рабочий агрегированный отчет, но текущий UI/API не
соответствует Demo Freeze v1 explainability контракту;
- перед расширением пилота нужно подтвердить свежесть источников по каждому
пользователю и роль ожидаемых подразделений.
## Explainable KPI Validation
Live endpoint:
```text
/portal/api/workforce/kpi/explain -> 404
```
Вывод:
- Explainable KPI реализован и покрыт тестами в текущей кодовой базе;
- на рабочем контуре отдельный endpoint не развернут;
- live UI не показывает ожидаемый блок `Почему такой индекс активности?` в
соответствии с freeze smoke.
Gap:
- deployment/version drift между текущим repository state и live portal runtime.
## UEBA Validation
Live endpoint:
```text
/portal/api/ueba -> 200
```
Обезличенная сводка:
- response `ok=true`;
- severity: `critical`;
- status: `FAIL`;
- score: `100`;
- reason codes: несколько;
- score components: несколько.
Оценка:
- UEBA endpoint работает;
- score `critical` требует ручной проверки evidence;
- без ручной проверки нельзя считать это подтвержденным нарушением;
- высокий score может быть как реальным риском, так и шумом от неполного
покрытия/устаревших источников/политики baseline.
## Risk Narrative Validation
Live endpoint:
```text
/portal/api/risk/narrative -> 404
```
Вывод:
- Risk Narrative реализован в текущей кодовой базе и задокументирован в
`docs/RISK_NARRATIVE_RU.md`;
- на рабочем контуре отдельный endpoint и Executive UI block не соответствуют
Demo Freeze v1 ожиданиям;
- risk narrative нельзя демонстрировать на live-контуре как подтвержденный
deployed capability до обновления runtime.
## Executive Action Center Validation
Live endpoint:
```text
/portal/api/actions -> 404
```
Вывод:
- Executive Action Center реализован в текущей кодовой базе и задокументирован;
- live runtime не отдает отдельный actions endpoint;
- рекомендации в demo/freeze сценарии нельзя заявлять как live-deployed feature
до обновления portal runtime.
## Agent/Data Flow Validation
AW-rus server:
- ActivityWatch server active;
- worktime API service active;
- failed systemd units: `0`;
- ActivityWatch API buckets endpoint отвечает `200`;
- buckets count: `27`;
- latest bucket timestamp близок к моменту проверки;
- oldest bucket timestamp старый, что нормально для исторических/event buckets,
но требует отдельной интерпретации freshness по bucket type.
Windows/RDP runtime:
- текущий `awatch-agent-rs` process активен;
- collector guard process активен;
- watcher/window/telemetry processes активны;
- scheduled tasks для ActivityWatch/AWatch runtime находятся в состоянии
`Ready` или `Running`.
Фактические роли:
```text
legacy/current runtime: awatch-agent-rs и существующие ActivityWatch watchers
new baseline core: adk-rust/crates/awatch-agent, покрыт тестами, но не подтвержден как основной live runtime
```
Backlog/dead-letter:
- явный dead-letter count на AW server: `0`;
- known spool directories на AW server не обнаружены в проверенных путях;
- Windows-side spool/backlog требует отдельной безопасной проверки без вывода
путей и payload.
## Performance Snapshot
Обезличенная сводка:
| API | Status | Время ответа |
| --- | --- | --- |
| `/portal/api/health` | `200` | < 1 ms на gateway-local check |
| `/portal/api/reports?role=executive` | `200` | первый observed run около 9 s, warm-cache run < 10 ms |
| `/portal/api/reports?role=manager` | `200` | < 10 ms на warm-cache run |
| `/portal/api/reports?role=security` | `200` | < 10 ms на warm-cache run |
| `/portal/api/reports?role=forensics` | `200` | < 10 ms на warm-cache run |
Логи:
- recent portal log scan за окно проверки не показал `500`, panic или явных
timeout в sanitized summary;
- ActivityWatch/worktime recent error scan не показал явных ошибок в sanitized
summary.
Ограничение:
- это snapshot, не load test и не sizing report.
## Noise / False Positive Findings
Потенциальный шум:
- UEBA severity `critical` / score `100` без ручной валидации evidence может
выглядеть завышенным;
- stale исторические buckets могут искажать общее восприятие freshness, если не
разделять active, inactive и event-driven bucket types;
- live Executive headline/runtime naming все еще может содержать старую
внутреннюю терминологию, что конфликтует с public naming hygiene.
Не исправлялось в этой задаче:
- scoring rules;
- UEBA thresholds;
- report content logic;
- deployed binary/runtime.
## Documentation Mismatches
Найдены важные расхождения:
1. Документация Demo Freeze v1 описывает production-hardening endpoints
`/healthz`, `/readyz`, `/version`, `/metrics`; live portal runtime их не
отдает на фактическом portal port.
2. Документация и текущая кодовая база описывают standalone endpoints
`/api/workforce/kpi/explain`, `/api/risk/narrative`, `/api/actions`; live
portal runtime на gateway-local path возвращает `404`.
3. Visual smoke текущей freeze-ветки ожидает Executive blocks, которых нет в
live runtime.
4. Public naming hygiene в repository docs закрыт, но live runtime/report text
может сохранять старую внутреннюю терминологию до обновления deployment.
## Security / Privacy Notes
Соблюдено:
- raw logs не коммитились;
- raw JSON payload не коммитился;
- screenshots с реальными данными не коммитились;
- реальные IP/hostname/usernames/ФИО/подразделения в этот документ не внесены;
- проверка выполнялась read-only;
- destructive commands, restarts и deploy не выполнялись.
## Gaps
Критично перед расширением пилота:
1. Закрыть deployment/version drift live portal runtime относительно Demo Freeze
v1.
2. После обновления runtime повторить production-hardening smoke на реальном
контуре.
3. Проверить request id / correlation id headers на live API.
4. Проверить `/metrics` на live runtime и мониторинг low-cardinality metrics.
5. Провести ручной разбор UEBA `critical` с evidence, не меняя правила вслепую.
Желательно до пилотного расширения:
1. Добавить отдельный pilot-feedback контур для замечаний руководителя, ИБ,
эксплуатации и расследователей.
2. Разделить freshness report по bucket types: active, inactive, event-driven,
historical.
3. Подготовить live validation checklist для deploy parity: repo commit,
deployed binary version, endpoint matrix, smoke results.
4. Проверить Windows-side spool/backlog безопасной командой без раскрытия путей
и payload.
Можно перенести после первого ограниченного пилота:
1. Тонкая настройка UEBA thresholds.
2. Расширение Action Center rules.
3. Улучшение dashboard wording по результатам реальной обратной связи.
## Recommended Next Tasks
Не открывать feature roadmap. Следующие задачи должны быть pilot-feedback /
operations oriented:
- `docs/pilot-feedback/BUGS.md` - зафиксировать deployment/version drift как bug;
- `docs/pilot-feedback/FEATURE_REQUESTS.md` - собирать только запросы от
реальных ролей;
- `docs/pilot-feedback/LESSONS_LEARNED.md` - фиксировать, что было непонятно на
показе;
- отдельная operator task: сверить deployed portal binary/commit с freeze branch;
- отдельная operator task: повторить live smoke после controlled deploy.
## Explicit Non-Goals
В рамках TASK_013 не выполнялись:
- новые API;
- новый UI;
- новые collectors;
- ML/LLM;
- DLP/SIEM/EDR claims;
- изменение scoring logic;
- restart/redeploy production services;
- выгрузка персональных данных;
- сохранение real screenshots в git.
## Conclusion
Рабочий внутренний контур AWatch-rus существует и собирает реальные данные.
Portal, ActivityWatch, Security events, UEBA endpoint, Forensics и базовые role
views частично подтверждены.
При этом live runtime не соответствует Demo Freeze v1 по production-hardening
endpoints и новым risk/explain/action endpoints. До расширения пилота нужно
закрыть deployment/version drift и повторить live validation. Текущий статус:
```text
ready for controlled internal review;
not ready for expanded pilot until live runtime parity is restored.
```
+5
View File
@@ -34,6 +34,11 @@ headline, KPI label и CLI help используют публичное назв
- Полная production-приемка требует live validation на стенде заказчика:
доступность, TLS/reverse proxy, источники данных, backup/restore и ownership
действий.
- TASK_013 live validation выявил deployment/version drift: рабочий внутренний
runtime собирает и показывает реальные данные, но не соответствует Demo
Freeze v1 по production-hardening endpoints и отдельным risk/explain/action
endpoints. До расширения пилота нужен controlled deploy/parity check и
повторный live smoke.
## Overall Status
@@ -0,0 +1,458 @@
# docs/roadmap/TASK_013_DETMIR_PRODUCTION_VALIDATION.md
## Цель
Проверить реально работающий контур DetMir/AWatch-rus на нескольких пользователях и собрать фактические эксплуатационные данные.
Задача не про добавление функциональности.
Задача про проверку:
* что реально работает;
* что используется;
* где есть шум;
* где есть расхождение с документацией;
* какие риски есть перед расширением пилота.
---
## Контекст
Проект уже находится в состоянии:
* Demo Freeze v1;
* Pilot-ready;
* Registry-preparation-ready;
* Enterprise-deployment-documented.
При этом существует реально работающий контур DetMir на нескольких пользователях.
Нужно проверить именно его, не подменяя проверку demo/synthetic данными.
---
## Основные правила
Запрещено:
* добавлять новые API;
* добавлять новый UI;
* добавлять новые agent collectors;
* менять архитектуру;
* включать ML/LLM;
* добавлять DLP/SIEM/EDR claims;
* выгружать персональные данные в документы;
* коммитить реальные ФИО, логины, IP, hostname, названия подразделений заказчика;
* коммитить runtime artifacts, логи, дампы, скриншоты с реальными данными.
Разрешено:
* добавлять документацию;
* добавлять checklist;
* добавлять anonymized summary;
* добавлять smoke/validation scripts, если они не раскрывают данные;
* исправлять явные naming/documentation inconsistencies;
* фиксировать gaps как отдельные рекомендации.
---
## Что проверить
### 1. Runtime Health
Проверить работающий контур:
* `/healthz`;
* `/readyz`;
* `/version`;
* `/metrics`.
Зафиксировать:
* доступность;
* response status;
* наличие request id / correlation id;
* отсутствие 500;
* корректность metrics format.
Не сохранять реальные URL, IP, hostname.
---
### 2. Portal Usage Validation
Проверить вручную или через browser smoke:
* Executive Dashboard;
* Workforce view;
* Security view;
* Forensics view;
* Reports view.
Зафиксировать:
* какие страницы реально открываются;
* какие блоки отображаются;
* есть ли пустые/сломанные блоки;
* есть ли 500/404;
* есть ли визуальные проблемы.
Не коммитить screenshots с реальными данными.
Если нужны screenshots — сохранить только локально или сделать обезличенные.
---
### 3. KPI Validation
Проверить:
* Workforce KPI;
* Explainable KPI;
* Department Comparison;
* Trend Status.
Ответить:
* KPI выглядит правдоподобно или нет;
* explainability помогает понять KPI или нет;
* есть ли очевидно ложные/странные объяснения;
* есть ли недостаток данных;
* есть ли `confidence: low`.
---
### 4. UEBA / Risk Narrative / Action Center Validation
Проверить:
* UEBA Score;
* Risk Narrative;
* Recommended Actions.
Зафиксировать:
* есть ли шумные правила;
* есть ли бесполезные рекомендации;
* есть ли рекомендации без достаточной evidence;
* есть ли risk level, который выглядит завышенным;
* есть ли risk level, который выглядит заниженным.
Важно:
не исправлять правила в этой задаче, если это требует изменения логики.
Только зафиксировать findings.
---
### 5. Agent / Data Flow Validation
Проверить текущий runtime:
* работает ли текущий агентский контур;
* есть ли backlog/spool;
* есть ли ошибки flush;
* есть ли dead-letter;
* нет ли потери данных;
* heartbeat поступает или нет;
* данные доходят до портала/отчетов.
Если используются оба:
* `awatch-agent-rs`;
* `adk-rust/crates/awatch-agent`;
зафиксировать их фактические роли:
```text
legacy/current runtime:
new baseline core:
```
---
### 6. Performance Snapshot
Собрать обезличенную сводку:
* примерное число пользователей;
* примерное число событий/записей в сутки, если безопасно доступно;
* размер spool/backlog;
* время генерации report;
* время ответа основных API;
* наличие slow requests;
* наличие ошибок в logs.
Не коммитить raw logs.
---
### 7. Data Hygiene / Sensitive Data Audit
Проверить, что в репозитории и документах после работы не появились:
* реальные ФИО;
* реальные логины;
* реальные IP;
* реальные hostname;
* реальные подразделения заказчика;
* реальные screenshots;
* runtime logs;
* database dumps;
* персональные данные.
---
## Что создать
Создать документ:
```text
docs/DETMIR_PRODUCTION_VALIDATION_RU.md
```
Структура:
```text
# DetMir Production Validation
## Executive Summary
## Scope
## Environment
Обезличенно:
- пользователей: несколько;
- контур: working internal pilot;
- данные: реальные, но в документе не раскрываются.
## Runtime Health
## Portal Validation
## KPI Validation
## Explainable KPI Validation
## UEBA Validation
## Risk Narrative Validation
## Executive Action Center Validation
## Agent/Data Flow Validation
## Performance Snapshot
## Noise / False Positive Findings
## Documentation Mismatches
## Security / Privacy Notes
## Gaps
## Recommended Next Tasks
## Explicit Non-Goals
## Conclusion
```
---
## Что обновить
Обновить:
```text
docs/roadmap/TASK_013_DETMIR_PRODUCTION_VALIDATION.md
```
Добавить секцию:
```text
## Выполнение
```
с кратким итогом.
При необходимости обновить:
```text
docs/ROADMAP_CONFORMANCE_AUDIT_RU.md
```
только если найдены важные расхождения.
---
## Допустимые scripts
Если полезно, добавить:
```text
scripts/detmir-production-validation-smoke.mjs
```
Требования:
* не печатать реальные данные;
* не сохранять payload с персональными данными;
* проверять только статусы, наличие блоков и обезличенные счетчики;
* URL задавать через env:
```bash
DETMIR_VALIDATION_URL=http://127.0.0.1:8720
```
---
## Проверки
Выполнить:
```bash
cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all
cargo build --release
node scripts/deployment-readiness-smoke.mjs
node scripts/pilot-validation-smoke.mjs
AWATCH_PORTAL_SMOKE_URL=http://127.0.0.1:8720 node scripts/awatch-production-hardening-smoke.mjs
```
Если добавлен новый script:
```bash
node --check scripts/detmir-production-validation-smoke.mjs
DETMIR_VALIDATION_URL=http://127.0.0.1:8720 node scripts/detmir-production-validation-smoke.mjs
```
Также выполнить:
```bash
git diff --check
```
и sensitive scan по добавленным/измененным файлам.
---
## Критерии приемки
Задача выполнена, если:
* создан `docs/DETMIR_PRODUCTION_VALIDATION_RU.md`;
* рабочий контур проверен без раскрытия персональных данных;
* health/ready/version/metrics проверены;
* portal проверен;
* KPI/explainability проверены;
* UEBA/Risk Narrative/Action Center проверены;
* agent/data flow проверен;
* performance snapshot зафиксирован обезличенно;
* gaps и recommended next tasks сформированы;
* sensitive data не попали в git;
* все проверки проходят.
---
## Финальный отчет Codex должен содержать
1. Что проверено.
2. Что подтверждено как работающее.
3. Какие gaps найдены.
4. Какие noisy rules/recommendations найдены.
5. Какие privacy/security ограничения соблюдены.
6. Какие документы созданы/обновлены.
7. Какие scripts добавлены.
8. Результаты проверок.
9. Рекомендованные следующие задачи.
---
## Выполнение
Статус: выполнено как production validation / operational audit.
Создан документ:
- `docs/DETMIR_PRODUCTION_VALIDATION_RU.md`.
Проверено без коммита реальных payload/logs/screenshots:
- gateway и portal runtime;
- ActivityWatch API;
- portal API reports;
- portal tabs и role views через browser/tabs smoke;
- Workforce/KPI report structure;
- UEBA endpoint;
- Risk Narrative endpoint availability;
- Executive Action Center endpoint availability;
- Windows/RDP agent runtime;
- AW server service state;
- bucket freshness summary;
- production-hardening endpoint availability;
- sensitive data hygiene.
Подтверждено работающее:
- gateway-level health;
- portal UI на фактическом gateway-local port;
- `/portal/api/health`;
- `/portal/api/reports` по ролям;
- Security events backend;
- `/portal/api/ueba`;
- Forensics view;
- базовые portal tabs;
- server role gates в существующем tabs smoke;
- ActivityWatch API и свежие buckets;
- текущий Windows runtime с `awatch-agent-rs` и watchers.
Найдены gaps:
- live portal runtime отстает от Demo Freeze v1;
- `/portal/api/workforce/kpi/explain`, `/portal/api/risk/narrative`,
`/portal/api/actions` на live-контуре возвращают `404`;
- `/healthz`, `/readyz`, `/version`, `/metrics` не доступны на фактическом
portal port;
- request id / correlation id headers не возвращаются live portal API;
- Executive visual conformance smoke не проходит на live runtime;
- UEBA `critical` требует ручной проверки evidence, чтобы исключить шум.
Scripts:
- новые scripts не добавлялись;
- использованы существующие `scripts/browser-conformance-smoke.mjs`,
`scripts/detmir-portal-tabs-smoke.mjs`,
`scripts/awatch-production-hardening-smoke.mjs`,
`scripts/deployment-readiness-smoke.mjs`,
`scripts/pilot-validation-smoke.mjs`.
Результаты проверок:
- `cargo fmt --all --check` - OK;
- `cargo clippy --all-targets --all-features -- -D warnings` - OK;
- `cargo test --all` - OK;
- `cargo build --release` - OK;
- `node scripts/deployment-readiness-smoke.mjs` - OK;
- `node scripts/pilot-validation-smoke.mjs` - OK;
- live `scripts/browser-conformance-smoke.mjs` - FAIL для Executive,
Workforce, Security; OK для Forensics;
- live `scripts/detmir-portal-tabs-smoke.mjs` - FAIL только на Executive
freeze-layer checks; базовые tabs, role gates, security/forensics/admin OK;
- live `scripts/awatch-production-hardening-smoke.mjs` - FAIL:
`/healthz` на live portal base не возвращает `200`;
- `git diff --check` - OK;
- sensitive scan по добавленным/измененным файлам - OK после исключения
терминологических false positives.
Итог:
- live-контур пригоден для controlled internal review;
- расширять пилот нельзя, пока не закрыт deployment/version drift и не повторен
live smoke после controlled deploy;
- новых claims, API, UI, collectors, ML/LLM и SIEM/DLP/EDR заявлений не
добавлялось.