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

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

Show a Risk

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:

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:

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

Seed from the Library

Bulk-instantiate library templates against a system + framework:

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:

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:

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.

# 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

Remove a Link

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:

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:

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.