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, refresh AI summaries, and produce DSSE-signed risk attestations. 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.
Attestations are DSSE in-toto envelopes. risk attest produces a signed statement over the current risk state (inherent/residual scores, treatment, due date). The signing key, statement, and rationale are immutable once recorded — produce a fresh attestation if the risk changes.

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

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:

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

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

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 Posture

System-scoped summary covering inherent vs. residual score distributions, overdue attestations, the last full-assessment timestamp, and the top 5 risks by residual score:

pretorin risk posture <system_id>
pretorin risk posture <system_id> --json   # machine-readable for dashboards

Use posture as the entry-point when an auditor asks “where is this system on risk?” — it surfaces what’s overdue for attestation and where the worst residual exposure sits without listing every risk.

Attest a Risk

Produce a DSSE-signed attestation envelope over the current risk state. The platform records the signing key, algorithm (ECDSA P-256 + SHA-256 today), a signed statement covering risk scores and treatment, and your free-text rationale.

pretorin risk attest <system_id> <risk_id> \
  --type residual_accepted \
  --statement "Residual score 0.42 accepted by CISO after MFA rollout completed 2026-05-30."

The CLI prints the attestation ID, signing algorithm, public key fingerprint, and attestation status on success.

Attestation types

Value	Meaning
`residual_accepted`	Authorizing official formally accepts the residual risk
`mitigation_approved`	Mitigation plan and due date are approved as written
`inherent_validated`	Inherent risk scoring is validated as accurate baseline

List Attestations

pretorin risk attestations <system_id> <risk_id>
pretorin risk attestations <system_id> <risk_id> --json

Lists every signed envelope produced for the risk, newest first, including the attesting user, signing algorithm, and a truncated public-key fingerprint. Use --json to pipe full envelopes to a DSSE verifier such as cosign verify-blob-attestation.

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.

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.

Keyboard shortcuts

Pretorin Developer & Agent Docs