# 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-режиме используются только обезличенные данные.