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" \
  --artifact-content "**Evidence**\n\n- RBAC roles are configured in Azure AD." \
  --type configuration

Creates a markdown file under evidence/<framework>/<control>/ with YAML frontmatter containing metadata (control ID, framework, name, type, status, short description). The Markdown body is the evidence artifact that will be sent as artifact_content when pushed.

The CLI does not default --type to policy_document; you get a hard error listing canonical types if you omit it or pass an unknown value. Evidence artifacts should describe only the artifact and what it supports. Gaps, missing evidence, ambiguity, and remediation work belong in pretorin issues, not in evidence or narratives. Markdown headings (#, ##, etc.) are automatically converted to bold section labels with spacing because headings can break report rendering.

Format Evidence Markdown

Use this when you already have Markdown with headings and want the report-safe evidence style:

# Print reformatted Markdown to stdout
pretorin evidence format-markdown artifact.md

# Rewrite in place
pretorin evidence format-markdown artifact.md --write

# CI check
pretorin evidence format-markdown artifact.md --check

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" \
  --artifact-content "**Evidence**\n\n- Role mapping is enforced in the IdP export." \
  --type configuration

--description is the short human summary. --artifact-content is the Markdown evidence body that the platform materializes as the stored artifact. 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. Prefer evidence validate (below) so the CLI compares the fresh source-material hash before re-verifying.

Source Provenance Options

Audit-grade provenance metadata, captured into audit_metadata and used by evidence validate to detect drift against the original source material:

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.

Validate Evidence Source

Validate file-backed evidence against its recorded audit_metadata.content_hash:

pretorin evidence validate ev-abc123 --system "My System"

# Resolve relative source_uri values against a specific repo checkout
pretorin evidence validate ev-abc123 --source-root /path/to/repo

# Provide the replacement artifact body and reviewer note up front when drift is expected
pretorin evidence validate ev-abc123 \
  --artifact-content "**Evidence**\n\n- Updated RBAC mapping after Q2 IdP migration." \
  --description "RBAC mapping (post Q2 IdP migration)" \
  --drift-note "Source file rotated during Q2 IdP migration; review updated artifact."

If the fresh source-material hash is unchanged, the CLI calls mark-current and Pretorin records a re_verified lineage event. If the source changed, the CLI calls the artifact update endpoint with a new Markdown artifact and a drift_note so reviewers see the drift instead of silently marking stale evidence current.

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 Attestations (DSSE)

The platform may sign each evidence record with a DSSE in-toto attestation envelope (ADR 0003) so auditors and downstream tooling can independently verify integrity and provenance. Two commands surface that envelope from the CLI:

# Fetch the latest signed envelope as a pretty summary
pretorin evidence attestation get ev-abc123

# Emit raw DSSE JSON (pipe to cosign or any DSSE verifier)
pretorin evidence attestation get ev-abc123 --json | cosign verify-blob-attestation --key <pub> --signature -

# List all attestations for one evidence record (newest first)
pretorin evidence attestation get ev-abc123 --lineage

# Verify the signature locally against the platform's key registry
pretorin evidence attestation verify ev-abc123        # exit 0 on success, 1 on failure
pretorin evidence attestation verify ev-abc123 --env staging
pretorin evidence attestation verify ev-abc123 --key-fingerprint <sha256-of-DER-SPKI>

The verifier ports the platform’s own implementation (apps/api/app/services/attestation/verifier.py). It checks the ECDSA P-256 + SHA-256 signature over the DSSE PAE bytes (not the canonical JSON Statement bytes — a subtle but load-bearing distinction), resolves the signing key through GET /api/v1/public/keys rather than trusting any embedded PEM, and honors key validity windows, revocation timestamps, and environment labels.

See Evidence Attestation for the full verification model, CI integration, and a worked example.

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 the canonical types and can self-correct.

Markdown Artifact Requirements

Evidence descriptions are short summaries. The actual evidence belongs in artifact_content / --artifact-content as Markdown:

• Markdown headings are allowed in the artifact body.
• Markdown images are not accepted on JSON evidence writes; upload files with evidence upload.
• Source path, line, timestamp, and capture details belong in structured audit_metadata, not appended to the description.

These requirements are validated before push/upsert operations.