Evidence Commands

The evidence command group manages local evidence files and syncs them to the Pretorin platform.

Create Local Evidence

pretorin evidence create ac-02 fedramp-moderate \
  --name "RBAC Configuration" \
  --description "Role-based access control in Azure AD" \
  --type configuration

Creates a markdown file under evidence/<framework>/<control>/ with YAML frontmatter containing metadata (control ID, framework, name, type, status).

--type / -t is required — the CLI no longer defaults to policy_document. See Evidence Types below for the 13 canonical values.

List Local Evidence

# List all local evidence
pretorin evidence list

# Filter by framework
pretorin evidence list --framework fedramp-moderate

Push Evidence to Platform

pretorin evidence push

Pushes local evidence files to the platform using find-or-create upsert logic. Exact matches are reused and reported separately.

Requires an active single scope from pretorin context set, unless both --system and --framework are provided explicitly.

Search Platform Evidence

# Search by control
pretorin evidence search --control-id ac-02 --framework-id fedramp-moderate

# Search by system
pretorin evidence search --system "My Application" --framework-id fedramp-moderate --limit 100

Upload Evidence File

Upload a file directly as evidence:

pretorin evidence upload screenshot.png ac-02 fedramp-moderate \
  --name "MFA Screenshot" --type screenshot

pretorin evidence upload config.yaml ac-06 fedramp-moderate \
  --name "Auth Config" --type configuration --description "IdP auth config"

Creates an evidence record with the uploaded file and links it to the specified control. The file’s SHA-256 checksum is computed locally and verified server-side for integrity.

Upsert Evidence

Find-or-create evidence and link it to a control:

pretorin evidence upsert ac-02 fedramp-moderate \
  --name "RBAC Configuration" \
  --description "Role mapping in IdP" \
  --type configuration

This searches for an exact match on (name + description + type + control + framework) within the active system scope. If found, it reuses the existing item; otherwise, it creates a new one. It then ensures the evidence is linked to the specified control.

Code Context Options

When upserting evidence, you can attach source code context:

If --code-repo or --code-commit are not provided, the CLI auto-populates them from the attested source verification snapshot when available.

Audit Sufficiency Options

For evidence whose auditor sufficiency depends on the period it covers or the query/filter that produced it (typical for log extracts, scan exports, and continuous-compliance feeds):

Cadenced evidence transitions to expired automatically when expires_at lapses; refresh it with evidence mark-current (below).

Link Evidence to a Control

Link an existing platform evidence item to a control:

pretorin evidence link ev-abc123 ac-02
pretorin evidence link ev-abc123 ac-02 --framework-id fedramp-moderate --system "My System"

Options:

• --framework-id / -f — Framework ID (uses active context if omitted)
• --system / -s — System name or ID (uses active context if omitted)

Link Evidence to a CCI Implementation

Attach evidence to a per-system CCI implementation row:

pretorin evidence link-cci ev-abc123 <cci_implementation_id>
pretorin evidence link-cci ev-abc123 <cci_implementation_id> --system "My System"

Options:

• --system / -s — System name or ID (uses active context if omitted)
• --override-system-mismatch — Permit cross-system attachment (must be paired with --override-reason)
• --override-reason TEXT — Justification recorded with the override

The CCI implementation UUID can be obtained from pretorin cci impl or from the CCI status rollup.

Link Evidence to a STIG Rule Workflow

Attach remediation proof, mitigating-control documentation, or waiver-justification artifacts to a STIG rule:

pretorin evidence link-stig ev-abc123 <stig_rule_id>
pretorin evidence link-stig ev-abc123 <stig_rule_id> --system "My System"

The first link to a given (system, stig_rule) pair lazy-creates the workflow row on the platform.

Options match link-cci: --system, --override-system-mismatch, --override-reason.

Mark Evidence Current

Re-affirm that an evidence item is still current — bumps expires_at by the evidence’s refresh_cadence_days, transitions status from expired back to valid if needed, and auto-resolves any open evidence.expiring / evidence.expired monitoring events:

pretorin evidence mark-current ev-abc123
pretorin evidence mark-current ev-abc123 --system "My System"

Options:

• --system / -s — System name or ID (uses active context if omitted)

Fails with HTTP 400 if the evidence has no refresh_cadence_days set — only cadenced evidence (set via evidence upsert --cadence-days N) can be marked current. This is the entry-point for the continuous-compliance refresh loop: cron jobs, recipes, and operators all call mark-current to confirm evidence is still representative without rewriting its body.

Delete Evidence

# Delete with confirmation prompt
pretorin evidence delete ev-abc123

# Skip confirmation (for automation)
pretorin evidence delete ev-abc123 --yes

# Explicit system scope
pretorin evidence delete ev-abc123 --system "My Application" --framework-id fedramp-moderate --yes

Permanently deletes an evidence item from the platform. This is system-scoped and requires WRITE access. Associated evidence embeddings are removed as part of the delete lifecycle.

Evidence Types

Valid evidence types:

AI-Drift Normalization

Non-CLI write paths (MCP handlers, agent tools, upsert_evidence workflow, campaign apply) run a client-side normalizer before submitting evidence to the platform. It maps known AI-drift aliases to canonical types (e.g. audit_log → log_file, plural test_results → test_result, screenshoot → screenshot) and uses difflib fuzzy matching for novel typos before falling back to other. The CLI itself does not run the normalizer; users get a hard error listing all 13 canonical types and can self-correct.

Markdown Quality Requirements

Evidence descriptions must be auditor-ready markdown:

• No markdown headings (#, ##, etc.)
• At least one rich markdown element (fenced code block, table, list, or link)
• No markdown images (temporarily disabled pending platform image upload support)

These requirements are validated before push/upsert operations.