## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# 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.

`--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.

Option | Description
--- | ---
`--name` / `-n` | Evidence name (required)
`--type` / `-t` | Evidence type (default: `other`)
`--description` / `-d` | Evidence description
`--system` / `-s` | System name or ID (uses active context if omitted)

## 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:

Option | Description
--- | ---
`--code-file` | Path to source file
`--code-lines` | Line range (e.g., `10-25`)
`--code-repo` | Git repository URL
`--code-commit` | Git commit hash

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):

Option | Description
--- | ---
`--coverage-start` | ISO 8601 start of the period the evidence content describes
`--coverage-end` | ISO 8601 end of the period; omit for point-in-time evidence
`--capture-query` | Query / filter / command that produced the artifact (IPE reproducibility)
`--cadence-days` | Refresh cadence in days (1–365); evidence requires re-verification after this window. Server computes `expires_at` from this value.

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:

Option | Description
--- | ---
`--source-uri` | Stable source path, URL, object id, report id, or export id used for provenance
`--source-label` | Human-readable source title or section label for auditors
`--source-locator` | Precise source locator, e.g. section id or `lines 84-88`
`--source-excerpt` | Short quoted excerpt or source material used to produce the evidence claim
`--capture-method` | Source capture method, e.g. `repository_file_read`, `api_export`, `scanner_output`

## 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.

Option | Description
--- | ---
`--system` / `-s` | System name or ID (uses active context if omitted)
`--source-root` | Root directory for relative file-backed `source_uri` values (defaults to current directory)
`--artifact-content` / `--artifact` | Updated Markdown artifact body to use if drift is detected; otherwise an excerpt artifact is generated
`--description` / `-d` | Updated short summary to use if drift is detected
`--drift-note` | Reviewer-facing note created when drift is detected (defaults to a generic review-needed prompt)

## 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.

Option | Description
--- | ---
`--system` / `-s` | System name or ID (uses active context if omitted)
`--framework-id` / `-f` | Framework ID (uses active context if omitted)
`--yes` / `-y` | Skip confirmation prompt

## Evidence Types

Valid evidence types:

Type | Description
--- | ---
`policy_document` | Policy or procedure document
`screenshot` | Screenshot evidence
`screen_recording` | Screen recording
`log_file` | Log file extract
`configuration` | Configuration file or setting
`test_result` | Test output or report
`certificate` | Certificate or attestation document
`attestation` | Signed attestation
`code_snippet` | Code excerpt
`repository_link` | Link to source repository
`scan_result` | Security scan output
`interview_notes` | Interview or assessment notes
`other` | Other evidence type

### 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 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.