360 lines
9.8 KiB
Markdown
360 lines
9.8 KiB
Markdown
|
||
docs/roadmap/TASK_004_RISK_NARRATIVE.md
|
||
|
||
Рекомендуемые параметры
|
||
|
||
Mode: xhigh
|
||
Reasoning: maximum
|
||
Task type: product feature / executive risk UX / reporting
|
||
Quality bar: production-ready
|
||
Breaking changes: forbidden
|
||
Architecture changes: minimal
|
||
Simplifications: forbidden
|
||
Security posture: no sensitive data exposure
|
||
|
||
Required checks:
|
||
|
||
cargo fmt --all --check
|
||
cargo clippy --all-targets --all-features -- -D warnings
|
||
cargo test --all
|
||
cargo build --release
|
||
AWATCH_PORTAL_SMOKE_URL=http://127.0.0.1:8720 node scripts/awatch-production-hardening-smoke.mjs
|
||
|
||
Задача
|
||
|
||
Добавить Risk Narrative слой для AWatch-rus.
|
||
|
||
Цель
|
||
|
||
Связать уже существующие данные:
|
||
|
||
- Workforce KPI;
|
||
- Explainable KPI;
|
||
- UEBA Score;
|
||
- Coverage;
|
||
- Risk Heatmap;
|
||
- Security Correlation;
|
||
- Incident Candidates;
|
||
- pfSense contract status;
|
||
|
||
в понятный управленческий вывод:
|
||
|
||
Что происходит?
|
||
Насколько это рискованно?
|
||
Почему система так считает?
|
||
Что делать дальше?
|
||
|
||
Контекст
|
||
|
||
AWatch-rus позиционируется как Workforce-first система с отдельными контурами:
|
||
|
||
- Executive;
|
||
- Workforce;
|
||
- Security;
|
||
- Forensics;
|
||
- Admin.
|
||
|
||
Нужно не добавлять новую SIEM/DLP/ML-систему, а собрать уже имеющиеся сигналы в объяснимый risk narrative.
|
||
|
||
Что реализовать
|
||
|
||
1. Risk Narrative model
|
||
|
||
Добавить модель:
|
||
|
||
{
|
||
"risk_level": "medium",
|
||
"risk_score": 62,
|
||
"title": "Умеренный рост операционного риска",
|
||
"summary": "Активность подразделения снизилась при росте удаленных сессий и частичных пробелах покрытия.",
|
||
"why": [
|
||
"Индекс активности ниже среднего по подразделениям",
|
||
"UEBA score повышен до high",
|
||
"Покрытие агентов ниже целевого уровня",
|
||
"Есть кандидаты на инциденты"
|
||
],
|
||
"evidence": [
|
||
{
|
||
"source": "workforce_kpi",
|
||
"label": "Индекс активности",
|
||
"value": "74%",
|
||
"severity": "medium"
|
||
},
|
||
{
|
||
"source": "ueba",
|
||
"label": "UEBA score",
|
||
"value": "high",
|
||
"severity": "high"
|
||
}
|
||
],
|
||
"recommended_actions": [
|
||
"Проверить подразделения с низким покрытием данных",
|
||
"Проверить рост удаленных сессий",
|
||
"Передать security-события в контур ИБ для анализа"
|
||
],
|
||
"limitations": [
|
||
"pfSense находится в contract_only режиме",
|
||
"Risk Narrative не является ML-прогнозом"
|
||
]
|
||
}
|
||
|
||
2. API endpoint
|
||
|
||
Добавить endpoint:
|
||
|
||
GET /api/risk/narrative
|
||
|
||
Поддержать параметры, если они уже есть в текущей архитектуре:
|
||
|
||
- date;
|
||
- department;
|
||
- role;
|
||
- module.
|
||
|
||
Не добавлять employee-level детализацию, если нет готового безопасного контракта.
|
||
|
||
3. Rule-based risk scoring
|
||
|
||
Реализовать детерминированный rule-based scoring.
|
||
|
||
Пример уровней:
|
||
|
||
0-24 low
|
||
25-49 guarded
|
||
50-74 medium
|
||
75-89 high
|
||
90-100 critical
|
||
|
||
Сигналы для расчета:
|
||
|
||
- low Workforce KPI;
|
||
- low KPI confidence;
|
||
- low agent coverage;
|
||
- increased UEBA severity;
|
||
- incident candidates count;
|
||
- high security correlation;
|
||
- missing data;
|
||
- afterhours/remote activity;
|
||
- pfsense contract_only limitation.
|
||
|
||
Важно:
|
||
|
||
- не использовать ML;
|
||
- не использовать LLM;
|
||
- не использовать predictive scoring;
|
||
- все причины должны быть объяснимыми.
|
||
|
||
4. UI в Executive Portal
|
||
|
||
Добавить блок:
|
||
|
||
Риск-нарратив
|
||
|
||
Показать:
|
||
|
||
- уровень риска;
|
||
- risk score;
|
||
- краткое резюме;
|
||
- почему система так считает;
|
||
- evidence;
|
||
- recommended actions;
|
||
- limitations.
|
||
|
||
Интерфейс должен быть управленческим, не техническим.
|
||
|
||
5. UI в Security Portal
|
||
|
||
Добавить security-oriented view:
|
||
|
||
ИБ-интерпретация риска
|
||
|
||
Показать:
|
||
|
||
- security evidence;
|
||
- UEBA-related reasons;
|
||
- incident candidates;
|
||
- correlation indicators;
|
||
- что нужно проверить ИБ.
|
||
|
||
Не смешивать это с HR-оценкой сотрудников.
|
||
|
||
6. Markdown report
|
||
|
||
Обновить markdown report.
|
||
|
||
Добавить раздел:
|
||
|
||
## Риск-нарратив
|
||
|
||
Включить:
|
||
|
||
- risk level;
|
||
- risk score;
|
||
- summary;
|
||
- why;
|
||
- evidence;
|
||
- recommended actions;
|
||
- limitations.
|
||
|
||
7. OpenAPI / TypeScript contracts
|
||
|
||
Обновить:
|
||
|
||
- OpenAPI spec;
|
||
- TypeScript contracts;
|
||
|
||
если в проекте они уже поддерживаются.
|
||
|
||
8. Tests
|
||
|
||
Добавить тесты:
|
||
|
||
- "/api/risk/narrative" returns valid JSON;
|
||
- low-risk scenario;
|
||
- medium-risk scenario;
|
||
- high-risk scenario;
|
||
- limitations include contract_only where relevant;
|
||
- no ML/LLM claims;
|
||
- role visibility не раскрывает лишнее;
|
||
- markdown report contains risk narrative section;
|
||
- existing role gates not broken.
|
||
|
||
9. Documentation
|
||
|
||
Добавить:
|
||
|
||
docs/RISK_NARRATIVE_RU.md
|
||
|
||
Описать:
|
||
|
||
- что такое Risk Narrative;
|
||
- какие сигналы используются;
|
||
- как считается risk level;
|
||
- что означает evidence;
|
||
- что означает limitations;
|
||
- почему это не ML/LLM;
|
||
- почему это не SIEM и не DLP;
|
||
- как это показывать заказчику.
|
||
|
||
Запрещено
|
||
|
||
Не делать:
|
||
|
||
- ML;
|
||
- LLM;
|
||
- predictive analytics;
|
||
- полноценную SIEM;
|
||
- полноценную DLP;
|
||
- employee punishment scoring;
|
||
- новую БД;
|
||
- React;
|
||
- Tauri;
|
||
- Dioxus;
|
||
- SaaS-зависимости;
|
||
- ложные claims о pfSense ingestion.
|
||
|
||
Критерии приемки
|
||
|
||
Задача выполнена, если:
|
||
|
||
- добавлен "/api/risk/narrative";
|
||
- добавлена rule-based модель risk narrative;
|
||
- Executive UI показывает управленческий риск-нарратив;
|
||
- Security UI показывает ИБ-интерпретацию;
|
||
- markdown report обновлен;
|
||
- OpenAPI/TypeScript обновлены при необходимости;
|
||
- документация добавлена;
|
||
- тесты проходят;
|
||
- smoke проходит;
|
||
- существующие контракты не сломаны.
|
||
|
||
Финальный отчет Codex должен содержать
|
||
|
||
1. Краткое описание изменений.
|
||
2. Список измененных файлов.
|
||
3. Новый endpoint.
|
||
4. Risk scoring rules.
|
||
5. UI-блоки.
|
||
6. Обновления report/OpenAPI/TypeScript.
|
||
7. Добавленные тесты.
|
||
8. Результаты fmt/clippy/test/build/smoke.
|
||
9. Известные ограничения.
|
||
|
||
---
|
||
|
||
## Выполнение
|
||
|
||
Статус: выполнено для Pilot v1.
|
||
|
||
Краткое описание:
|
||
|
||
- добавлен rule-based Risk Narrative layer;
|
||
- добавлен endpoint `GET /api/risk/narrative`;
|
||
- risk score связывает Workforce KPI, Explainable KPI, UEBA, coverage,
|
||
security correlation, incident candidates и pfSense `contract_only`
|
||
limitation;
|
||
- Executive UI показывает блок `Риск-нарратив`;
|
||
- Security UI проверяет ИБ-релевантную связь рисков и активности;
|
||
- Markdown-отчет содержит раздел `## Риск-нарратив`;
|
||
- OpenAPI и TypeScript contracts обновлены;
|
||
- создана отдельная документация `docs/RISK_NARRATIVE_RU.md`.
|
||
|
||
Ключевые файлы:
|
||
|
||
- `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`;
|
||
- `docs/RISK_NARRATIVE_RU.md`;
|
||
- `scripts/browser-conformance-smoke.mjs`;
|
||
- `scripts/detmir-portal-tabs-smoke.mjs`.
|
||
|
||
Risk scoring rules:
|
||
|
||
- `0-24` - `low`;
|
||
- `25-49` - `guarded`;
|
||
- `50-74` - `medium`;
|
||
- `75-89` - `high`;
|
||
- `90-100` - `critical`.
|
||
|
||
Сигналы:
|
||
|
||
- low Workforce KPI;
|
||
- low KPI confidence;
|
||
- low agent coverage;
|
||
- increased UEBA severity;
|
||
- incident candidates count;
|
||
- high security correlation;
|
||
- missing data;
|
||
- afterhours/remote activity;
|
||
- pfSense `contract_only` limitation.
|
||
|
||
UI-блоки:
|
||
|
||
- Executive: `Риск-нарратив`, `Почему`, `Подтверждения`, `Дальше`,
|
||
`Ограничения`;
|
||
- Security: `Связь рисков и активности`, `Требует проверки`,
|
||
`Рекомендуемые действия ИБ`;
|
||
- Forensics: расследования, timeline, материалы расследования и аудит.
|
||
|
||
Проверки:
|
||
|
||
- unit tests для risk narrative scenarios;
|
||
- OpenAPI/TypeScript contract smoke;
|
||
- `node scripts/browser-conformance-smoke.mjs`;
|
||
- `node scripts/detmir-portal-tabs-smoke.mjs`;
|
||
- `cargo fmt --all --check`;
|
||
- `cargo clippy --all-targets --all-features -- -D warnings`;
|
||
- `cargo test --all`;
|
||
- `cargo build --release`;
|
||
- `git diff --check`.
|
||
|
||
Известные ограничения:
|
||
|
||
- Risk Narrative не является ML/LLM/predictive analytics;
|
||
- Risk Narrative не подтверждает нарушение без ручной проверки;
|
||
- нет auto-remediation;
|
||
- pfSense не заявляется как ingestion/SIEM, пока это не пройдет отдельную
|
||
приемку;
|
||
- live customer-stand validation остается отдельным шагом Demo Freeze v1.
|