# Risk Management

The `risk` command group manages a system's risk register: list and create risks, attach artifact links (controls / evidence / findings / vendors), record a mitigation strategy, and refresh AI summaries. The risk library is org-level; everything else is **system-scoped** — resolve the active system before any risk operation.

## Workflow notes

- **Risks are system-scoped.** Every command except `risk library list` takes a system as its first argument.
- **Auto-link is opt-in.** `risk create` and `risk seed` only auto-link controls when `--framework` is supplied **and** the system has `ControlImplementation` rows for that framework. Without those, the risk is created with zero links — follow up with `risk link add`.
- **Mitigation is just `risk update`.** There is no separate `/mitigate` endpoint. Set `--treatment` (one of `mitigate` / `accept` / `transfer` / `avoid`) plus `--treatment-plan` and `--treatment-due-date` through the update command.
- **AI refresh is best-effort.** `risk refresh-summary` always re-scores. The AI summary regenerates only if the AI service is up and the org has quota; check whether `ai_summary_generated_at` advanced if you need to confirm AI ran.

## List Risks

```bash
pretorin risk list <system_id>
pretorin risk list <system_id> --category availability --risk-level high --status open
```

## Show a Risk

```bash
pretorin risk show <system_id> <risk_id>
```

Returns the full risk including eager-loaded `artifact_links`.

## Create a Risk

Custom risk with no auto-linking:

```bash
pretorin risk create <system_id> \
  --title "Phishing campaign against ops team" \
  --category confidentiality
```

Custom risk with mitigation recorded in one call and control auto-linking against a framework:

```bash
pretorin risk create <system_id> \
  --title "Stolen credential abuse" \
  --category confidentiality \
  --treatment mitigate \
  --treatment-plan "Roll out hardware MFA to all admin accounts" \
  --treatment-due-date 2026-06-30 \
  --framework nist-800-53-r5 \
  --suggested-control-family AC \
  --suggested-control-family IA
```

### Treatment values

| Value | Meaning |
|-------|---------|
| `mitigate` | Reduce likelihood/impact through controls |
| `accept` | Document and accept the residual risk |
| `transfer` | Shift the risk (insurance, vendor SLA, etc.) |
| `avoid` | Eliminate the activity that causes the risk |

## Seed from the Library

Bulk-instantiate library templates against a system + framework:

```bash
pretorin risk seed <system_id> \
  --framework nist-800-53-r5 \
  --template-id tpl-phishing \
  --template-id tpl-insider \
  --template-id tpl-data-loss
```

Each template is scored against the system, and controls are auto-linked per the template's `suggested_control_families` when matching `ControlImplementation` rows exist.

## Update / Mitigate a Risk

This is the **mitigation surface** — record how a risk will be addressed by updating the same fields:

```bash
pretorin risk update <system_id> <risk_id> \
  --treatment mitigate \
  --treatment-plan "Hardware MFA deployed Q2 2026" \
  --treatment-due-date 2026-06-30
```

Any other risk fields (title, description, category, likelihood, impact, owner_id, status, review_frequency_days) can be updated through the same command.

## Retiring a Risk

There is no public hard-delete endpoint for risks — risks are part of the audit chain. Retire a risk by setting its `status` to a terminal value:

```bash
pretorin risk update <system_id> <risk_id> --status closed
```

Conventional terminal values follow the platform's other status-bearing models (`FindingStatus`, `POAMItemStatus`, `RFIStatus`): `closed` for risks that have been remediated or are no longer relevant. The `risk list` `--status` filter can then exclude them from active views (`pretorin risk list <system_id> --status identified`).

This is a CLI-side convention; the platform's `status` field is currently an unconstrained string. A future platform-level lineage model is expected to formalize risk-retirement semantics across artifact types.

## Attach Artifact Links

Risks can link to controls, evidence, findings, vendors, or monitoring events. Pass exactly one artifact flag.

```bash
# A control that mitigates this risk
pretorin risk link add <system_id> <risk_id> \
  --link-type mitigates_risk \
  --control AC-2 \
  --framework nist-800-53-r5

# Evidence demonstrating the risk is real
pretorin risk link add <system_id> <risk_id> \
  --link-type evidence_of_risk \
  --evidence <evidence_id>

# A vendor whose service introduces the risk
pretorin risk link add <system_id> <risk_id> \
  --link-type contributes_to_risk \
  --vendor <vendor_id>
```

### Link types

| Value | Meaning |
|-------|---------|
| `contributes_to_risk` | Artifact increases the risk |
| `mitigates_risk` | Artifact reduces the risk |
| `evidence_of_risk` | Artifact demonstrates the risk has occurred or could |

## Remove a Link

```bash
pretorin risk link rm <system_id> <risk_id> <link_id>
```

## Refresh Score + AI Summary

Re-score the risk using the latest analytics and trigger a best-effort AI summary regeneration:

```bash
pretorin risk refresh-summary <system_id> <risk_id>
```

The endpoint always returns 200 with the updated entry. The score commits regardless of AI availability; the AI summary updates only if the AI service is reachable and the org has quota.

## Risk Library

Browse the org-level template library to see what can be seeded. Templates expose a `scenario` (the risk description), `category`, `cia_category`, and `suggested_control_families`:

```bash
pretorin risk library list
pretorin risk library list --category "Access control"
```

Use `--json` to capture the full template payload, including `suggested_control_families`, for scripting.

## Related: Risk Assessment Reports

Risk Assessment Report (RAR) generation is **not** exposed through the CLI or MCP — it remains a platform-only multi-section AI-assembled document. Drive RAR builds from the Pretorin platform UI when needed.
