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

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" \
      --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:

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.

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

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