docs: enter demo freeze housekeeping

2026-06-07 21:17:12 +03:00
parent 037d47b592
commit 1b817866a4
29 changed files with 495 additions and 58 deletions
@@ -0,0 +1,179 @@
+# Risk Narrative
+
+Risk Narrative в AWatch-rus - это управленческое объяснение текущего риска на
+основе уже существующих сигналов продукта. Слой отвечает на четыре вопроса:
+
+- что происходит;
+- насколько это рискованно;
+- почему система так считает;
+- что делать дальше.
+
+Risk Narrative не является ML-прогнозом, LLM-выводом, SIEM, DLP или
+автоматическим подтверждением нарушения. Это rule-based decision-support слой
+для Pilot v1.
+
+## API
+
+Endpoint:
+
+```http
+GET /api/risk/narrative
+```
+
+Поддерживаемые параметры зависят от текущего контракта портала:
+
+- `date`;
+- `department`;
+- `role`;
+- `module`.
+
+Employee-level детализация не добавляется, пока нет отдельной безопасной модели
+доступа и приемочного контракта.
+
+## Модель ответа
+
+Ответ содержит:
+
+- `risk_level` - уровень риска: `low`, `guarded`, `medium`, `high`,
+  `critical`;
+- `risk_score` - числовая оценка 0-100;
+- `title` - короткий управленческий заголовок;
+- `summary` - объяснение ситуации простым языком;
+- `why` - причины расчета;
+- `evidence` - подтверждающие сигналы;
+- `recommended_actions` - ручные действия для ответственных ролей;
+- `limitations` - ограничения интерпретации.
+
+Пример:
+
+```json
+{
+  "risk_level": "medium",
+  "risk_score": 62,
+  "title": "Умеренный рост операционного риска",
+  "summary": "Активность подразделения снизилась при росте удаленных сессий и частичных пробелах покрытия.",
+  "why": [
+    "Индекс активности ниже среднего по подразделениям",
+    "UEBA score повышен",
+    "Покрытие агентов ниже целевого уровня"
+  ],
+  "evidence": [
+    {
+      "source": "workforce_kpi",
+      "label": "Индекс активности",
+      "value": "74%",
+      "severity": "medium"
+    }
+  ],
+  "recommended_actions": [
+    "Проверить подразделения с низким покрытием данных",
+    "Передать security-события в контур ИБ для анализа"
+  ],
+  "limitations": [
+    "pfSense находится в contract_only режиме",
+    "Risk Narrative не является ML-прогнозом"
+  ]
+}
+```
+
+## Rule-Based Scoring
+
+Модель детерминированная. Она использует только текущие агрегированные сигналы
+и не обучается на данных заказчика.
+
+Уровни:
+
+| Диапазон | Уровень | Интерпретация |
+| --- | --- | --- |
+| `0-24` | `low` | Существенных отклонений нет |
+| `25-49` | `guarded` | Есть ранние признаки риска |
+| `50-74` | `medium` | Нужна ручная проверка причин |
+| `75-89` | `high` | Требуется приоритетная проверка |
+| `90-100` | `critical` | Нужна срочная ручная проверка |
+
+Сигналы:
+
+- сниженный Workforce KPI;
+- низкое доверие к KPI;
+- низкое покрытие агентами;
+- повышенный UEBA severity;
+- наличие кандидатов на проверку;
+- высокая связь security-событий и активности;
+- пропуски данных;
+- активность вне рабочего времени;
+- рост удаленных сессий;
+- `contract_only` ограничение pfSense.
+
+## Evidence
+
+`evidence` нужен, чтобы руководитель, ИБ и эксплуатация видели не только итоговый
+уровень риска, но и источники вывода.
+
+Типовые источники:
+
+- `workforce_kpi`;
+- `kpi_explainability`;
+- `ueba`;
+- `coverage`;
+- `risk_heatmap`;
+- `security_correlation`;
+- `incident_candidates`;
+- `pfsense_contract`.
+
+Evidence не должен содержать реальные ФИО, логины, IP-адреса, hostname или
+сырые события безопасности в demo-режиме.
+
+## Роли
+
+| Роль | Видимость |
+| --- | --- |
+| `executive` | Управленческий риск, причины, действия без технической детализации |
+| `manager` | Workforce-риск и действия по подразделению |
+| `security` | ИБ-релевантные причины, кандидаты и correlation indicators |
+| `forensics` | Контекст расследования и evidence package |
+| `admin` | Состояние источников, покрытие и технические ограничения |
+
+Серверные role gates остаются обязательными. Скрытие блоков в HTML не считается
+достаточной защитой.
+
+## UI и Markdown
+
+В Executive view портал показывает блок:
+
+```text
+Риск-нарратив
+```
+
+В Markdown-отчете используется раздел:
+
+```markdown
+## Риск-нарратив
+```
+
+Раздел должен быть понятен руководителю без знаний ИБ: сначала вывод, затем
+причины, затем действия и ограничения.
+
+## Как показывать заказчику
+
+Рекомендуемый порядок для demo:
+
+1. Открыть Executive view.
+2. Показать `Риск-нарратив`: уровень, score и краткое summary.
+3. Показать `Почему`: какие факторы подняли риск.
+4. Показать `Evidence`: какие сигналы подтверждают вывод.
+5. Показать `Рекомендуемые действия`.
+6. Перейти в Security или Forensics только после управленческого вывода.
+
+Важно: не заявлять, что Risk Narrative сам подтверждает нарушение. Он
+приоритизирует ручную проверку.
+
+## Ограничения Pilot v1
+
+- Нет ML, LLM и predictive analytics.
+- Нет auto-remediation.
+- Нет полноценного SIEM/DLP claim.
+- pfSense readiness является `contract_only`, если ingestion отдельно не
+  включен и не прошел приемку.
+- Качество вывода зависит от свежести источников, покрытия агентов и полноты
+  данных.
+- В demo-режиме используются только обезличенные данные.