diff --git a/README.md b/README.md index ec6bc44..b4d44a1 100755 --- a/README.md +++ b/README.md @@ -252,6 +252,7 @@ collectors. - [Customer discovery questions](docs/CUSTOMER_DISCOVERY_QUESTIONS_RU.md) - [Pilot success criteria](docs/PILOT_SUCCESS_CRITERIA_RU.md) - [Competitive positioning](docs/COMPETITIVE_POSITIONING_RU.md) +- [Roadmap conformance audit](docs/ROADMAP_CONFORMANCE_AUDIT_RU.md) - [Production readiness портала](docs/PRODUCTION_READINESS_RU.md) - [Explainable Workforce KPI](docs/EXPLAINABLE_KPI_RU.md) - [Executive Action Center](docs/EXECUTIVE_ACTION_CENTER_RU.md) diff --git a/adk-rust/crates/detmir-portal/src/main.rs b/adk-rust/crates/detmir-portal/src/main.rs index 3bf1f7e..a15cff4 100644 --- a/adk-rust/crates/detmir-portal/src/main.rs +++ b/adk-rust/crates/detmir-portal/src/main.rs @@ -152,7 +152,7 @@ struct CachedSnapshot { } #[derive(Clone, Debug, Parser)] -#[command(about = "Read-only DetMir operator/manager/owner web portal")] +#[command(about = "Read-only AWatch-rus operator/manager/owner web portal")] struct Cli { #[arg(long, default_value = "127.0.0.1:8720", env = "DETMIR_PORTAL_BIND")] bind: String, @@ -3357,11 +3357,11 @@ fn build_reports( let recommended_actions = actions_from_center(&action_center); let headline = if summary.operator_ok && summary.severity == "OK" && metrics.open_incidents == 0 { - "Контур DetMir работает штатно, критичных действий не требуется" + "AWatch-rus работает штатно, критичных действий не требуется" } else if metrics.open_incidents > 0 { - "Контур DetMir работает, есть открытые вопросы для оператора" + "AWatch-rus работает, есть открытые вопросы для оператора" } else { - "Контур DetMir требует технической проверки" + "AWatch-rus требует технической проверки" }; let mut executive_points = Vec::new(); executive_points.push(format!( @@ -3505,7 +3505,7 @@ fn build_reports( { "title": "Надежность контура", "items": [ - report_item("DetMir status", snapshot.detmir_status.status.clone(), snapshot.detmir_status.summary.clone()), + report_item("AWatch-rus status", snapshot.detmir_status.status.clone(), snapshot.detmir_status.summary.clone()), report_item("Сбор данных", collection.status.clone(), collection.text.clone()), report_item("Качество данных", agent_quality.quality_status.clone(), format!("источник={}, сессии={}, активные={}, удаленные={}", agent_quality.collector_source, agent_quality.sessions_collected_total, agent_quality.active_sessions_total, agent_quality.rdp_sessions_total)), report_item("Достоверность показателей", agent_quality_explain.status.clone(), format!("участвует в показателях={}, {}", agent_quality_explain.kpi_accepted, agent_quality_explain.recommendation)), @@ -7201,7 +7201,7 @@ fn render_report_markdown( context: ReportMarkdownContext<'_>, ) -> String { let mut text = String::new(); - text.push_str("# DetMir оперативный отчет\n\n"); + text.push_str("# AWatch-rus оперативный отчет\n\n"); text.push_str(&format!("Дата снимка: {}\n\n", snapshot.generated_at_utc)); text.push_str(&format!("Итог: {headline}\n\n")); append_risk_narrative_markdown(&mut text, context.risk_narrative); diff --git a/docs/ROADMAP_CONFORMANCE_AUDIT_RU.md b/docs/ROADMAP_CONFORMANCE_AUDIT_RU.md new file mode 100644 index 0000000..1a71dcd --- /dev/null +++ b/docs/ROADMAP_CONFORMANCE_AUDIT_RU.md @@ -0,0 +1,450 @@ +# Roadmap Conformance Audit + +Дата аудита: 2026-06-07. + +Аудируемый срез: `origin/main` после TASK_011. + +Цель: проверить соответствие roadmap, README, документации, API, портала, +отчетов, агента и smoke-проверок фактическому состоянию AWatch-rus. Новая +функциональность в рамках аудита не добавлялась. + +## Executive Summary + +AWatch-rus в целом соответствует Pilot v1 roadmap как Workforce-first платформа +с Security Analytics и Forensics-контуром. Подтверждены production hardening +endpoints, Explainable KPI, Risk Narrative, Executive Action Center, Rust Agent +baseline, demo pack, registry readiness package, enterprise deployment package +и pilot validation package. + +Критичных conformance-блокеров на проверенном срезе не выявлено. Несколько +устаревших человеко-читаемых product-name claims были исправлены в runtime: +генерируемый отчет теперь начинается с `# AWatch-rus оперативный отчет`, а +headline, KPI label и CLI help используют публичное название AWatch-rus. + +Главные остаточные gaps: + +- TASK_001-TASK_004 не имеют явной секции `Выполнение`, хотя артефакты по ним + в коде и документации присутствуют. +- Для Risk Narrative нет отдельного `docs/RISK_NARRATIVE_RU.md`; функциональность + подтверждена кодом, OpenAPI, TypeScript, UI и Markdown, но документация + распределена по связанным материалам. +- Portal verification в TASK_011 выполнен через код, статические UI-маркеры и + production smoke; отдельный полноценный Playwright visual run не входил в + обязательный список команд TASK_011. +- Полная production-приемка требует live validation на стенде заказчика: + доступность, TLS/reverse proxy, источники данных, backup/restore и ownership + действий. + +## Overall Status + +Статус: `ready for controlled pilot validation`. + +Оценка соответствия roadmap: высокая, но не финальная production acceptance. + +Что подтверждено проверками: + +- Rust workspace собирается, форматируется, проходит clippy и unit tests. +- Production endpoints `/healthz`, `/readyz`, `/version`, `/metrics` работают на + актуальном release-бинаре. +- `/api/reports`, `/api/workforce/kpi/explain`, `/api/risk/narrative` и + `/api/actions` проходят smoke-проверку контрактов. +- Request id и correlation id возвращаются в HTTP headers. +- Query limits и role gates проверяются smoke. +- Demo, registry, deployment, screenshots, roadmap, reports и runbooks проходят + статические smoke-проверки. + +## Confirmed Implemented Items + +### Production Hardening + +Подтверждено: + +- `GET /healthz`; +- `GET /readyz`; +- `GET /version`; +- `GET /metrics`; +- request id / correlation id; +- Prometheus text metrics; +- query limits for heavy API; +- report date range limits; +- role gates smoke; +- documentation in `docs/PRODUCTION_READINESS_RU.md`; +- smoke in `scripts/awatch-production-hardening-smoke.mjs`. + +Evidence: + +- `adk-rust/crates/detmir-portal/src/production/`; +- `adk-rust/crates/detmir-portal/src/main.rs`; +- `scripts/awatch-production-hardening-smoke.mjs`. + +### Explainable KPI + +Подтверждено: + +- `GET /api/workforce/kpi/explain`; +- response model with `kpi_score`, `confidence`, `coverage`, `factors`, + `top_applications`, `warnings`, `recommendations`; +- deterministic factors; +- role-filtered response; +- UI blocks `Почему такой индекс` / `Почему такой индекс активности?`; +- Markdown section `## Почему такой индекс`; +- documentation in `docs/EXPLAINABLE_KPI_RU.md`. + +Evidence: + +- `adk-rust/crates/detmir-portal/src/workforce_kpi_explain.rs`; +- `adk-rust/crates/detmir-portal/src/static/app.js`; +- `adk-rust/crates/detmir-portal/src/contracts/openapi.json`; +- `adk-rust/crates/detmir-portal/src/contracts/typescript.d.ts`. + +### Risk Narrative + +Подтверждено: + +- `GET /api/risk/narrative`; +- deterministic rule-based model; +- `risk_score`, `risk_level`, `why`, `evidence`, `limitations`; +- Executive UI block `Риск-нарратив`; +- Markdown section `## Риск-нарратив`; +- OpenAPI and TypeScript contracts. + +Evidence: + +- `adk-rust/crates/detmir-portal/src/risk_narrative.rs`; +- `adk-rust/crates/detmir-portal/src/static/app.js`; +- `adk-rust/crates/detmir-portal/src/contracts/openapi.json`; +- `adk-rust/crates/detmir-portal/src/contracts/typescript.d.ts`. + +### Executive Action Center + +Подтверждено: + +- `GET /api/actions`; +- rule-based action model; +- owner role, priority, deadline, reason codes and evidence; +- no auto-remediation; +- Executive and Security UI blocks; +- Markdown section `## Рекомендуемые действия`; +- documentation in `docs/EXECUTIVE_ACTION_CENTER_RU.md`. + +Evidence: + +- `adk-rust/crates/detmir-portal/src/executive_actions.rs`; +- `scripts/awatch-production-hardening-smoke.mjs`. + +### Rust Agent Baseline + +Подтверждено: + +- crate `adk-rust/crates/awatch-agent/`; +- config loader; +- telemetry envelope; +- heartbeat; +- local spool; +- retry and dead-letter; +- `/healthz`; +- `/metrics`; +- structured JSON logging; +- unit tests. + +Также подтверждено различение: + +- `awatch-agent` - новый baseline core без мониторинга пользователя; +- `awatch-agent-rs` - текущий runtime для проверенных worktime/session задач. + +Не обнаружено в baseline: + +- keylogger; +- screenshot capture; +- clipboard capture; +- packet interception; +- kernel driver; +- EDR/DLP/ML/LLM behavior. + +Evidence: + +- `adk-rust/crates/awatch-agent/`; +- `adk-rust/crates/awatch-agent-rs/`; +- `docs/RUST_AGENT_BASELINE_RU.md`. + +### Demo Pack + +Подтверждено: + +- `docs/demo/DEMO_SCENARIO_EXECUTIVE_RU.md`; +- `docs/demo/DEMO_SCENARIO_SECURITY_RU.md`; +- `docs/demo/DEMO_SCENARIO_FORENSICS_RU.md`; +- `docs/demo/DEMO_PACK_ACCEPTANCE_CHECKLIST_RU.md`; +- `docs/DEMO_REPORT_EXAMPLE_RU.md`; +- `docs/PILOT_VALUE_PROPOSITION_RU.md`; +- `docs/fixtures/pilot-v1-demo/demo-seed-data.json`; +- screenshots in `docs/screenshots/`. + +Smoke подтвердил, что PNG не являются заглушками и ссылки валидны. + +### Registry Readiness + +Подтверждено: + +- `docs/REGISTRY_PRODUCT_PASSPORT_RU.md`; +- `docs/REGISTRY_ARCHITECTURE_RU.md`; +- `docs/REGISTRY_FUNCTIONAL_SCOPE_RU.md`; +- `docs/REGISTRY_DEPENDENCY_STATEMENT_RU.md`; +- `docs/REGISTRY_DEPLOYMENT_MODEL_RU.md`; +- `docs/REGISTRY_COMMERCIAL_POSITIONING_RU.md`; +- `docs/REGISTRY_READINESS_CHECKLIST_RU.md`. + +Core, optional and not claimed разделены. Есть explicit caveat, что документы +не являются юридической гарантией принятия в реестр. + +### Enterprise Deployment Guide + +Подтверждено: + +- `docs/ENTERPRISE_DEPLOYMENT_GUIDE_RU.md`; +- `docs/DEPLOYMENT_TOPOLOGIES_RU.md`; +- `docs/SIZING_GUIDE_RU.md`; +- `docs/BACKUP_AND_RECOVERY_RU.md`; +- `docs/OPERATIONS_RUNBOOK_RU.md`; +- `docs/SECURITY_HARDENING_RU.md`; +- `docs/ENTERPRISE_ACCEPTANCE_CHECKLIST_RU.md`; +- `scripts/deployment-readiness-smoke.mjs`. + +Sizing не заявлен как гарантия и требует проверки на инфраструктуре заказчика. + +## Partially Implemented Items + +- TASK_001 Pilot v1 Stabilization: результат фактически покрыт документами, + smoke и Pilot v1 artifacts, но сам roadmap-файл не имеет явного статуса + выполнения. +- TASK_002 Production Hardening: functionality and smoke confirmed, но + roadmap-файл не содержит секцию `Выполнение`. +- TASK_003 Explainable KPI: functionality confirmed, но roadmap-файл не содержит + секцию `Выполнение`. +- TASK_004 Risk Narrative: API/UI/report/contracts confirmed, но нет отдельного + `docs/RISK_NARRATIVE_RU.md`, а roadmap-файл не содержит секцию `Выполнение`. +- Portal visual conformance: UI markers and API-backed blocks confirmed, но + TASK_011 run не выполнял отдельный визуальный Playwright regression. + +## Documentation-Only Items + +- Registry readiness остается preparation package, not legal acceptance. +- Enterprise deployment docs задают target process, но production deployment + требует отдельной приемки на стенде. +- Platform and collector ecosystem documents корректно описывают planned, + future and contract-only направления, но не являются реализацией новых + collectors. +- pfSense readiness остается optional / `contract_only`. + +## Gaps + +1. Обновить roadmap metadata: + - добавить `## Выполнение` для TASK_001-TASK_004; + - указать текущий статус и evidence files. +2. Создать отдельный `docs/RISK_NARRATIVE_RU.md` или явно сослаться в roadmap + TASK_004 на документ, который заменяет dedicated Risk Narrative doc. +3. Добавить отдельный conformance smoke для roadmap/docs claims, чтобы TASK_011 + не оставался только ручным аудитом. +4. Выполнить live customer-stand validation: + - portal URL; + - TLS/reverse proxy; + - role access; + - `/api/reports`; + - backup/restore; + - data freshness. +5. Проверить public naming hygiene в старых исторических документах и, если они + остаются GitHub-facing, привести их к AWatch-rus naming policy. +6. Зафиксировать release tag, release-specific SBOM and signed/checksummed + artifacts перед registry/expert package. + +## False Claims Found + +Исправлено в рамках TASK_011: + +- Markdown report title, executive headline, status KPI label and CLI help used + stale internal product naming. Теперь человеко-читаемый вывод использует + публичное название `AWatch-rus`. + +Не обнаружено в README/Pilot v1 claims: + +- claim полноценной DLP; +- claim полноценной SIEM; +- claim EDR/XDR; +- claim ML/LLM scoring; +- claim обязательного pfSense; +- claim готового React/Tauri UI; +- claim auto-remediation. + +Оставшийся risk: + +- В старых исторических документах и некоторых filename paths есть legacy + naming. Это не product capability claim, но это снижает чистоту public GitHub + presentation и должно быть отдельной cleanup-задачей. + +## API Verification + +Проверенные endpoints: + +- `GET /healthz` - 200, JSON, response headers include `X-Request-Id` and + `X-Correlation-Id`. +- `GET /readyz` - controlled 200/503 with JSON checks. +- `GET /version` - 200, includes `app_version` and `schema_version=pilot-v1`. +- `GET /metrics` - Prometheus text format, includes + `awatch_http_requests_total` and `awatch_readyz_status`. +- `GET /api/reports` - covered by production smoke query limits and report + payload tests. +- `GET /api/workforce/kpi/explain` - 200, numeric KPI and deterministic + factors. +- `GET /api/risk/narrative` - 200, stable risk level and rule-based model. +- `GET /api/actions` - 200, actions array and no auto-remediation. + +Role gates: + +- manager -> `/api/security` returns 403 in smoke. +- Unit tests confirm executive/security/forensics report filtering. + +Query limits: + +- too large `page_size` rejected with `invalid_page_size`. +- too wide report date range rejected with `report_range_too_large`. + +## Portal Verification + +Confirmed by static UI code and tests: + +- Executive Dashboard; +- Workforce KPI; +- Explainable KPI block; +- Risk Narrative block; +- Recommended Actions block; +- Security view; +- Forensics view; +- reports view; +- architecture page. + +Evidence: + +- `adk-rust/crates/detmir-portal/src/static/index.html`; +- `adk-rust/crates/detmir-portal/src/static/app.js`; +- `adk-rust/crates/detmir-portal/src/static/architecture.html`; +- `adk-rust/crates/detmir-portal/src/main.rs` tests. + +Gap: + +- TASK_011 did not require and did not run a visual Playwright screenshot + regression. Use it before customer-facing UI freeze. + +## Agent Verification + +`awatch-agent` baseline conforms to TASK_005 scope: + +- no user monitoring collectors; +- no clipboard/screenshot/keylogger/packet interception; +- no kernel driver; +- no DLP/EDR/ML/LLM behavior; +- heartbeat-only telemetry envelope; +- local spool and dead-letter; +- bounded retry/backoff; +- health and metrics endpoints; +- structured JSON logs. + +`awatch-agent-rs` remains current runtime and has telemetry/session/worktime +tests. Documentation clearly separates baseline core from current runtime. + +## Demo Pack Verification + +Smoke results: + +- demo docs exist; +- screenshots exist and are valid PNG files; +- demo dataset exists; +- Markdown links valid; +- sensitive scan for validation/demo files passed. + +Screenshots verified: + +- `01-executive-overview.png`; +- `02-risk-heatmap.png`; +- `03-security-view.png`; +- `04-operations-view.png`; +- `05-investigation-pack.png`; +- `06-markdown-report.png`; +- `07-product-architecture.png`. + +## Registry Readiness Verification + +Confirmed: + +- core/optional/not claimed are separated; +- no legal guarantee of registry acceptance; +- remaining gaps are listed; +- SBOM is described as release-specific requirement; +- open-source dependencies are documented at package level. + +Gap: + +- release-specific SBOM and signed artifacts must be generated for final tag, + not inferred from roadmap docs. + +## Deployment Readiness Verification + +Confirmed: + +- deployment guide exists; +- topologies exist; +- sizing guide exists and includes caveats; +- backup/recovery exists; +- operations runbook exists; +- security hardening exists; +- enterprise acceptance checklist exists; +- deployment smoke passed. + +Gap: + +- restore test, sizing validation and live reverse proxy/TLS validation remain + stand-specific acceptance tasks. + +## Recommended Fixes + +1. Add `## Выполнение` sections to TASK_001-TASK_004. +2. Add dedicated `docs/RISK_NARRATIVE_RU.md` or update TASK_004 to point to the + accepted replacement document. +3. Add `scripts/roadmap-conformance-smoke.mjs` for future automated claim + checks. +4. Add visual/browser conformance smoke before the customer demo freeze. +5. Clean old public-facing naming paths where legacy internal naming appears in + GitHub-visible filenames or links. +6. Run live customer-stand validation and append evidence to pilot acceptance + docs. + +## Next Roadmap Corrections + +- TASK_012: Roadmap metadata cleanup for TASK_001-TASK_004. +- TASK_013: Risk Narrative documentation closure. +- TASK_014: Public naming hygiene cleanup for historical docs and README links. +- TASK_015: Browser/visual conformance smoke for Executive, Security, + Forensics and Reports views. +- TASK_016: Release tag, SBOM and signed artifact readiness. + +## Checks + +Commands executed from `adk-rust/` because the Rust workspace manifest is under +`adk-rust/Cargo.toml`: + +- `cargo fmt --all --check` - OK. +- `cargo clippy --all-targets --all-features -- -D warnings` - OK. +- `cargo test --all` - OK. +- `cargo build --release` - OK. + +Commands executed from repository root: + +- `node scripts/deployment-readiness-smoke.mjs` - OK. +- `node scripts/pilot-validation-smoke.mjs` - OK. +- `AWATCH_PORTAL_SMOKE_URL=http://127.0.0.1:8720 node scripts/awatch-production-hardening-smoke.mjs` - OK. +- `git diff --check` - OK. + +Smoke note: + +- The first live smoke attempt used a stale binary from `adk-rust/target/release` + and correctly failed `/healthz`. The validated production smoke was rerun on + the actual cargo release artifact from the configured cargo target cache. diff --git a/docs/roadmap/TASK_011_DETMIR_ROADMAP_CONFORMANCE_AUDIT.md b/docs/roadmap/TASK_011_DETMIR_ROADMAP_CONFORMANCE_AUDIT.md index f3795af..0a5f6ca 100644 --- a/docs/roadmap/TASK_011_DETMIR_ROADMAP_CONFORMANCE_AUDIT.md +++ b/docs/roadmap/TASK_011_DETMIR_ROADMAP_CONFORMANCE_AUDIT.md @@ -26,7 +26,8 @@ AWATCH_PORTAL_SMOKE_URL=http://127.0.0.1:8720 node scripts/awatch-production-har ## Цель -Проверить, что фактически работающий DetMir/AWatch-rus соответствует текущему roadmap, документации, заявленным контрактам и демо-сценариям. +Проверить, что фактически работающий AWatch-rus соответствует текущему roadmap, +документации, заявленным контрактам и демо-сценариям. Не добавлять новую функциональность. @@ -386,3 +387,53 @@ docs/ROADMAP_CONFORMANCE_AUDIT_RU.md 6. Исправленные claims/links, если были. 7. Результаты проверок. 8. Рекомендованные следующие задачи. + +--- + +## Выполнение + +Статус: выполнено. + +Создан итоговый аудит: + +- `docs/ROADMAP_CONFORMANCE_AUDIT_RU.md` + +Исправлен найденный claim: + +- человеко-читаемый runtime output приведен к публичному названию `AWatch-rus`: + заголовок Markdown-отчета, headline, KPI label и CLI help. + +Обновлен README: + +- добавлена ссылка на `docs/ROADMAP_CONFORMANCE_AUDIT_RU.md`. + +Подтвержденные блоки: + +- Production hardening; +- Explainable KPI; +- Risk Narrative; +- Executive Action Center; +- Rust Agent Baseline; +- Demo Pack; +- Registry Readiness; +- Enterprise Deployment Guide; +- Pilot Validation readiness. + +Выявленные gaps: + +- TASK_001-TASK_004 не имеют явной секции `Выполнение`; +- для Risk Narrative нет отдельного `docs/RISK_NARRATIVE_RU.md`; +- нужен отдельный visual/browser conformance smoke перед customer-facing freeze; +- live customer-stand validation остается отдельным acceptance шагом; +- старые GitHub-facing документы требуют отдельной naming hygiene cleanup. + +Проверки: + +- `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; +- `AWATCH_PORTAL_SMOKE_URL=http://127.0.0.1:8720 node scripts/awatch-production-hardening-smoke.mjs` - OK; +- `git diff --check` - OK.