Pretorin CLI Documentation
Description: Documentation for the Pretorin CLI - compliance tools for developers and AI agents.

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

# Pretorin CLI

> Beta — Pretorin is currently in closed beta. Framework and control browsing works for everyone. Platform write features (evidence, narratives, monitoring) require a beta code. Sign up for early access.

Pretorin CLI gives developers and AI agents direct access to compliance data, implementation context, and evidence workflows. It supports NIST 800-53, NIST 800-171, FedRAMP, and CMMC frameworks with over 700 controls across 8 framework profiles.

## Two Usage Modes

Pretorin works in two modes depending on your setup:

1. Pretorin-hosted model mode — Run `pretorin agent run` to route model calls through Pretorin’s `/v1` endpoints. Pretorin manages the AI runtime.

2. Bring-your-own-agent mode — Run `pretorin mcp-serve` and connect the MCP server to your existing AI tool (Claude Code, Codex CLI, Cursor, Windsurf, etc.). Your agent gets compliance tools without changing your workflow.

## What You Can Do

- Browse compliance frameworks — Query controls, families, and document requirements from authoritative sources
- Manage implementation context — Set an active system and framework, then track progress across controls
- Create and manage evidence — Generate local evidence files, push them to the platform, and link them to controls
- Write implementation narratives — Draft and push auditor-ready narratives for each control
- Run AI-powered compliance tasks — Use the built-in Codex agent for gap analysis, narrative generation, evidence collection, and security review
- Review code against controls — Analyze your codebase for control coverage
- Track monitoring events — Record security scans, access reviews, configuration changes, and compliance checks
- Generate compliance artifacts — Produce structured JSON artifacts documenting control implementations

## Architecture

    ┌─────────────────────────────────────────────┐
    │                 Developer                    │
    │                                             │
    │   ┌──────────┐        ┌──────────────────┐  │
    │   │ CLI      │        │ AI Agent         │  │
    │   │ pretorin │        │ (Claude, Codex,  │  │
    │   │ commands │        │  Cursor, etc.)   │  │
    │   └────┬─────┘        └────────┬─────────┘  │
    │        │                       │             │
    │        │              ┌────────┴─────────┐   │
    │        │              │  MCP Server      │   │
    │        │              │  pretorin        │   │
    │        │              │  mcp-serve       │   │
    │        │              └────────┬─────────┘   │
    │        │                       │             │
    │        └───────────┬───────────┘             │
    │                    │                         │
    │           ┌────────┴─────────┐               │
    │           │  Pretorin API    │               │
    │           │  Client          │               │
    │           └────────┬─────────┘               │
    └────────────────────┼─────────────────────────┘
                         │
                ┌────────┴─────────┐
                │  Pretorin        │
                │  Platform        │
                └──────────────────┘

## Links

- GitHub Repository
- Platform
- PyPI Package
- Issue Tracker
- API Documentation

# Installation

Pretorin CLI requires Python 3.10 or later.

## Recommended: uv

uv installs the CLI as an isolated tool with its own dependencies:

    uv tool install pretorin

## pip

    pip install pretorin

## pipx

pipx provides isolated installation similar to uv:

    pipx install pretorin

## Docker

A Dockerfile and Docker Compose configuration are included in the repository:

    git clone https://github.com/pretorin-ai/pretorin-cli.git
    cd pretorin-cli
    docker compose up

## Verify Installation

    pretorin version

Expected output:

    pretorin version 0.8.1

## Updating

Check for and install the latest version:

    pretorin update

The CLI also checks for updates automatically on startup and notifies you when a new version is available. To disable passive update notifications:

    export PRETORIN_DISABLE_UPDATE_CHECK=1
    # or
    pretorin config set disable_update_check true

## Development Installation

For contributing to Pretorin CLI:

    git clone https://github.com/pretorin-ai/pretorin-cli.git
    cd pretorin-cli
    uv pip install -e ".[dev]"

This installs the package in editable mode with development dependencies (pytest, ruff, mypy, etc.).

# Authentication

## Getting an API Key

Get your API key from platform.pretorin.com.

> Beta Note: Framework and control browsing works for all authenticated users. Platform write features (evidence, narratives, monitoring) require a beta code. Systems can only be created on the platform, not through the CLI or MCP. Sign up for early access.

## Login

    pretorin login

You’ll be prompted to enter your API key. Credentials are stored in `~/.pretorin/config.json`.

If you’re already authenticated, `pretorin login` validates your existing key against the API and skips the prompt.

## Verify Authentication

    $ pretorin whoami
    [°~°] Checking your session...
    ╭──────────────────────────────── Your Session ────────────────────────────────╮
    │ Status: Authenticated                                                        │
    │ API Key: 4MAS****...9v7o                                                     │
    │ API URL: https://platform.pretorin.com/api/v1                                │
    │ Frameworks Available: 8                                                      │
    ╰──────────────────────────────────────────────────────────────────────────────╯

## Logout

Clear stored credentials:

    pretorin logout

## API Key via Environment Variable

You can set your API key via environment variable instead of `pretorin login`. The environment variable takes precedence over stored config:

    export PRETORIN_API_KEY=pretorin_your_key_here

This is useful for CI/CD pipelines and containerized environments.

# Quick Start

After installing and authenticating, here are some common first steps.

## Browse Frameworks

List all available compliance frameworks:

    pretorin frameworks list

Get details on a specific control:

    pretorin frameworks control nist-800-53-r5 ac-02 --references

## Set Up Context

Set your active system and framework for platform operations:

    # Interactive selection
    pretorin context set

    # Or explicit
    pretorin context set --system "My Application" --framework fedramp-moderate

## Create Evidence

Create a local evidence file:

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

Push evidence to the platform:

    pretorin evidence push

## Run an Agent Task

Use the Codex agent for compliance analysis:

    pretorin agent run "Assess AC-02 implementation gaps for my system"

Or use a predefined skill:

    pretorin agent run --skill gap-analysis "Analyze my system compliance gaps"

## Connect Your AI Tool via MCP

If you use Claude Code, Codex CLI, Cursor, or another MCP-compatible AI tool:

    # Claude Code
    claude mcp add --transport stdio pretorin -- pretorin mcp-serve

    # Then ask your AI agent about compliance
    # "What controls are in the Access Control family for FedRAMP Moderate?"

See the MCP Setup Guides for other tools.

## Run the Demo Walkthrough

An interactive demo script is included in the repository:

    bash scripts/demo-walkthrough.sh

# Framework Browsing

The `frameworks` command group lets you browse compliance frameworks, control families, and individual controls. These commands are read-only and available to all authenticated users.

## List All Frameworks

    $ pretorin frameworks list
    [°~°] Consulting the compliance archives...
                            Available Compliance Frameworks
    ┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓
    ┃ ID          ┃ Title       ┃ Version     ┃ Tier         ┃ Families ┃ Controls ┃
    ┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩
    │ cmmc-l1     │ CMMC 2.0    │ 2.0         │ tier1_essen… │        6 │       17 │
    │             │ Level 1     │             │              │          │          │
    │ cmmc-l2     │ CMMC 2.0    │ 2.0         │ tier1_essen… │       14 │      110 │
    │             │ Level 2     │             │              │          │          │
    │ ...         │             │             │              │          │          │
    └─────────────┴─────────────┴─────────────┴──────────────┴──────────┴──────────┘

    Total: 8 framework(s)

The ID column is what you use in all other commands.

## Get Framework Details

    $ pretorin frameworks get fedramp-moderate
    [°~°] Gathering framework details...
    ╭───────────────── Framework: FedRAMP Rev 5 Moderate Baseline ─────────────────╮
    │ ID: fedramp-moderate                                                         │
    │ Title: FedRAMP Rev 5 Moderate Baseline                                       │
    │ Version: fedramp2.1.0-oscal1.0.4                                             │
    │ OSCAL Version: 1.0.4                                                         │
    │ Tier: tier1_essential                                                        │
    │ Category: government                                                         │
    │ Published: 2024-09-24T02:24:00Z                                              │
    ╰──────────────────────────────────────────────────────────────────────────────╯

## List Control Families

    $ pretorin frameworks families nist-800-53-r5
    [°~°] Gathering control families...
                           Control Families - nist-800-53-r5
    ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┓
    ┃ ID                          ┃ Title                       ┃ Class ┃ Controls ┃
    ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━┩
    │ access-control              │ Access Control              │ ac    │       25 │
    │ audit-and-accountability    │ Audit and Accountability    │ au    │       16 │
    │ awareness-and-training      │ Awareness and Training      │ at    │        6 │
    │ configuration-management    │ Configuration Management    │ cm    │       14 │
    │ ...                         │                             │       │          │
    └─────────────────────────────┴─────────────────────────────┴───────┴──────────┘

> Important: Family IDs are slugs like `access-control`, not short codes like `ac`. The short code is shown in the Class column for reference, but commands require the full slug ID.

### CMMC Family IDs

CMMC frameworks use level-specific family slugs:

    $ pretorin frameworks families cmmc-l2

CMMC family IDs include the level suffix, e.g., `access-control-level-2` instead of `access-control`.

## Get Family Details

    pretorin frameworks family nist-800-53-r5 access-control

## List Controls

    $ pretorin frameworks controls nist-800-53-r5 --family access-control --limit 10
    [°~°] Searching for controls...
       Controls - nist-800-53-r5 (Family: access-control)
    ┏━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
    ┃ ID    ┃ Title                        ┃ Family         ┃
    ┡━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
    │ ac-01 │ Policy and Procedures        │ ACCESS-CONTROL │
    │ ac-02 │ Account Management           │ ACCESS-CONTROL │
    │ ac-03 │ Access Enforcement           │ ACCESS-CONTROL │
    │ ...   │                              │                │
    └───────┴──────────────────────────────┴────────────────┘

    Showing 10 of 25 controls. Use --limit to see more.

Without `--family`, all controls for the framework are listed. Without `--limit`, all matching controls are shown.

> Important: Control IDs are zero-padded — use `ac-01`, not `ac-1`. See Control ID Formats for details.

## Get Control Details

    $ pretorin frameworks control nist-800-53-r5 ac-02
    [°~°] Looking up control details...
    ╭─────────────────────────────── Control: AC-02 ───────────────────────────────╮
    │ ID: ac-02                                                                    │
    │ Title: Account Management                                                    │
    │ Class: SP800-53                                                              │
    │ Type: organizational                                                         │
    │                                                                              │
    │ AI Guidance: Available                                                       │
    ╰──────────────────────────────────────────────────────────────────────────────╯

    Parameters:
      - ac-02_odp.01: prerequisites and criteria
      - ac-02_odp.02: attributes (as required)
      - ac-02_odp.03: personnel or roles
      - ac-02_odp.04: policy, procedures, prerequisites, and criteria
      - ac-02_odp.05: personnel or roles

### With References

Add `--references` to include the statement text, guidance, and related controls:

    $ pretorin frameworks control nist-800-53-r5 ac-02 --references

This adds:

- Statement — the formal control requirement text
- Guidance — implementation guidance from the framework
- Related Controls — other controls that relate to this one

### Common Mistakes

Using the wrong ID format produces an error:

    $ pretorin frameworks control nist-800-53-r5 ac-1
    [°~°] Looking up control details...
    [°︵°] Couldn't find control ac-1 in nist-800-53-r5
    Try pretorin frameworks controls nist-800-53-r5 to see available controls.

Use zero-padded IDs: `ac-01`, not `ac-1`.

## Document Requirements

    pretorin frameworks documents fedramp-moderate

Returns explicit and implicit document requirements for the framework.

## Framework Metadata

Get per-control metadata for a framework:

    pretorin frameworks metadata nist-800-53-r5

## Submit Artifacts

Submit a compliance artifact JSON file:

    pretorin frameworks submit-artifact artifact.json

See Artifact Generation for the artifact schema.

## JSON Output

All framework commands support JSON output for scripting and AI agents:

    pretorin --json frameworks list
    pretorin --json frameworks control nist-800-53-r5 ac-02

# Context Management

The `context` command group manages your active system and framework scope. Platform-backed compliance operations (evidence, narratives, notes, monitoring, control status) run inside exactly one `system + framework` pair at a time.

This works similarly to `kubectl config use-context` — set your scope once, then run commands within it.

## List Available Systems

    $ pretorin context list
    [°~°] Fetching your systems...
                                  Your Systems
    ┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━┓
    ┃ System           ┃ Framework ID       ┃ Progress % ┃ Status    ┃
    ┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━┩
    │ My Application   │ nist-800-53-r5     │        42% │ in_progress │
    │ My Application   │ fedramp-moderate   │        28% │ in_progress │
    │ Internal Tool    │ cmmc-l2            │        75% │ implemented │
    └──────────────────┴────────────────────┴────────────┴───────────┘

## Set Active Context

    # Interactive — prompts for system and framework selection
    pretorin context set

    # Explicit
    pretorin context set --system "My Application" --framework nist-800-53-r5

## Show Current Context

    $ pretorin context show
    ╭──────────────────────── Active Context ─────────────────────────╮
    │ System: My Application                                          │
    │ Framework: NIST SP 800-53 Rev 5                                │
    │ Progress: 42% (136/324 implemented, 45 in progress)            │
    ╰─────────────────────────────────────────────────────────────────╯

## Clear Context

    pretorin context clear

## Single-Scope Enforcement

All platform write operations must target exactly one system + framework pair. This includes:

- Evidence creation and push
- Narrative updates
- Control notes
- Monitoring events
- Control status updates

If you need to work across multiple frameworks (e.g., `fedramp-low` and `fedramp-moderate`), run them as separate operations:

    # Work on FedRAMP Moderate
    pretorin context set --system "My App" --framework fedramp-moderate
    pretorin evidence push

    # Switch to FedRAMP Low
    pretorin context set --system "My App" --framework fedramp-low
    pretorin evidence push

Some commands also accept explicit `--system` and `--framework` flags, which override the stored context for that invocation.

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

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

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

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

## Evidence Types

Valid evidence types:

Type | Description
--- | ---
`policy_document` | Policy or procedure document (default)
`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

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

# Narrative Commands

The `narrative` command group manages implementation narratives for controls. Narratives describe how a specific control is implemented within your system.

## Get Current Narrative

    pretorin narrative get ac-02 fedramp-moderate --system "My System"

Returns the current narrative text, status, and AI confidence metadata when present.

## Push a Narrative File

    pretorin narrative push ac-02 fedramp-moderate "My System" narrative-ac02.md

Reads a markdown or text file and submits it as the implementation narrative for the specified control.

## Markdown Quality Requirements

Narratives must be auditor-ready markdown:

- No markdown headings (`#`, `##`, etc.)
- At least two rich markdown elements (fenced code blocks, tables, lists, or links)
- At least one structural element (code block, table, or list)
- No markdown images (temporarily disabled pending platform image upload support)

These requirements are validated before push.

## Generating Narratives with AI

To generate narratives using the agent runtime:

    pretorin agent run --skill narrative-generation "Generate narrative for AC-02"

Or use the MCP server’s `pretorin_generate_control_artifacts` tool for read-only drafts through your AI agent.

See Skills for more on agent-powered narrative generation.

## No-Hallucination Requirements

Generated narratives must only document observable facts. For missing information, use TODO placeholder blocks:

    [[PRETORIN_TODO]]
    missing_item: <what is missing>
    reason: Not observable from current workspace and connected MCP systems
    required_manual_action: <what user must do on platform/integrations>
    suggested_evidence_type: <policy_document|configuration|...>
    [[/PRETORIN_TODO]]

# Notes Commands

The `notes` command group manages control implementation notes. Notes are used to track gaps, manual follow-up items, and implementation context for specific controls.

## List Notes

    pretorin notes list ac-02 fedramp-moderate --system "My System"

## Add a Note

    pretorin notes add ac-02 fedramp-moderate \
      --content "Gap: Missing SSO evidence. Manual next step: collect IdP configuration screenshots."

## Gap Note Format

When adding notes for unresolved gaps, use this structured format:

    Gap: <short title>
    Observed: <what was verifiably found>
    Missing: <what could not be verified>
    Why missing: <access/system limitation>
    Manual next step: <explicit user/platform action>

This format ensures consistency across CLI, MCP, and agent workflows when documenting compliance gaps.

# Monitoring Commands

The `monitoring` command group records security and compliance events against a system.

## Push a Monitoring Event

    pretorin monitoring push --system "My System" --title "Quarterly Access Review" \
      --event-type access_review --severity info

## Event Types

Type | Description
--- | ---
`security_scan` | Automated security scan result
`configuration_change` | Infrastructure or application configuration change
`access_review` | Periodic access review or audit
`compliance_check` | Compliance posture check or assessment

## Severity Levels

Severity | Description
--- | ---
`critical` | Requires immediate attention
`high` | Significant finding
`medium` | Moderate finding
`low` | Minor finding
`info` | Informational event

## Context Requirement

The `monitoring push` command requires an active system context. Set it with `pretorin context set` or pass `--system` explicitly.

# Review Commands

The `review` command group helps you review local code against framework controls.

## Run a Review

    # Uses active context for system/framework
    pretorin review run --control-id ac-02 --path ./src

    # Explicit system/framework override
    pretorin review run --control-id ac-02 --framework-id nist-800-53-r5 --path ./src

`pretorin review run` does not push narratives or evidence to the platform. In normal mode, it fetches control requirements and current implementation details for comparison. In `--local` mode, it writes a markdown review artifact under `.pretorin/reviews/` or the path specified with `--output-dir`.

## Check Implementation Status

    $ pretorin review status --control-id ac-02
    ╭─────────────────── Control AC-02 Status ───────────────────────╮
    │ Status: in_progress                                             │
    │ Evidence items: 3                                               │
    │ Narrative: This control is implemented through centralized     │
    │ account management using Azure AD...                           │
    ╰─────────────────────────────────────────────────────────────────╯

# Configuration

The `config` command group manages CLI configuration stored at `~/.pretorin/config.json`.

## List Configuration

    $ pretorin config list
              Pretorin Configuration
    ┏━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
    ┃ Key     ┃ Value           ┃ Source      ┃
    ┡━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
    │ api_key │ 4MAS****...9v7o │ config file │
    └─────────┴─────────────────┴─────────────┘

    Config file: /home/user/.pretorin/config.json

## Get a Config Value

    pretorin config get api_key

## Set a Config Value

    pretorin config set api_base_url https://custom-api.example.com/api/v1

## Show Config File Path

    $ pretorin config path
    /home/user/.pretorin/config.json

## Config File Format

The config file is JSON:

    {
      "api_key": "pretorin_...",
      "api_base_url": "https://platform.pretorin.com/api/v1/public",
      "model_api_base_url": "https://platform.pretorin.com/v1",
      "active_system": "My Application",
      "active_framework": "nist-800-53-r5",
      "disable_update_check": false
    }

## Configuration Keys

Key | Description
--- | ---
`api_key` | Pretorin API key
`api_base_url` | Platform REST API URL
`model_api_base_url` | Model API URL for agent runtime
`openai_api_key` | Optional model key for agent runtime
`active_system` | Currently active system name
`active_framework` | Currently active framework ID
`disable_update_check` | Disable passive update notifications

## Environment Variable Overrides

Environment variables take precedence over config file values. See Environment Variables for the full list.

# Complete Command Reference

## Global Options

Option | Description
--- | ---
`--json` | JSON output mode for scripting and AI agents
`--help` | Show command help

## Root Commands

Command | Description
--- | ---
`pretorin login` | Authenticate with the Pretorin API
`pretorin logout` | Clear stored credentials
`pretorin whoami` | Display authentication status
`pretorin version` | Show CLI version
`pretorin update` | Update to latest version
`pretorin mcp-serve` | Start the MCP server (stdio transport)

## Framework Commands

Command | Description
--- | ---
`pretorin frameworks list` | List all frameworks
`pretorin frameworks get <id>` | Get framework details
`pretorin frameworks families <id>` | List control families
`pretorin frameworks family <fw> <family>` | Get control family details
`pretorin frameworks controls <id>` | List controls (`--family`, `--limit`)
`pretorin frameworks control <fw> <ctrl>` | Get control details (`--references`)
`pretorin frameworks documents <id>` | Get document requirements
`pretorin frameworks metadata <id>` | Get per-control framework metadata
`pretorin frameworks submit-artifact <file>` | Submit a compliance artifact JSON file

## Context Commands

Command | Description
--- | ---
`pretorin context list` | List systems and frameworks with progress
`pretorin context set` | Set active system/framework context (`--system`, `--framework`)
`pretorin context show` | Display current active context
`pretorin context clear` | Clear active context

## Evidence Commands

Command | Description
--- | ---
`pretorin evidence create <ctrl> <fw>` | Create a local evidence file (`--name`, `--description`)
`pretorin evidence list` | List local evidence files (`--framework`)
`pretorin evidence push` | Push local evidence to the platform
`pretorin evidence search` | Search platform evidence (`--control-id`, `--framework-id`, `--system`, `--limit`)
`pretorin evidence upsert <ctrl> <fw>` | Find-or-create evidence and link it (`--name`, `--description`, `--type`)

## Narrative Commands

Command | Description
--- | ---
`pretorin narrative get <ctrl> <fw>` | Get current control narrative (`--system`)
`pretorin narrative push <ctrl> <fw> <sys> <file>` | Push a narrative file to the platform

## Notes Commands

Command | Description
--- | ---
`pretorin notes list <ctrl> <fw>` | List control notes (`--system`)
`pretorin notes add <ctrl> <fw>` | Add a control note (`--content`)

## Monitoring Commands

Command | Description
--- | ---
`pretorin monitoring push` | Push a monitoring event (`--system`, `--title`, `--event-type`, `--severity`)

## Agent Commands

Command | Description
--- | ---
`pretorin agent run "<task>"` | Run a compliance task (`--skill`, `--model`, `--base-url`, `--working-dir`, `--no-stream`, `--legacy`)
`pretorin agent doctor` | Validate Codex runtime setup
`pretorin agent install` | Download the pinned Codex binary
`pretorin agent version` | Show pinned Codex version and install status
`pretorin agent skills` | List available agent skills
`pretorin agent mcp-list` | List configured MCP servers for the agent
`pretorin agent mcp-add <name> stdio <cmd>` | Add an MCP server configuration (`--arg`)
`pretorin agent mcp-remove <name>` | Remove an MCP server configuration

## Review Commands

Command | Description
--- | ---
`pretorin review run` | Review code against a control (`--control-id`, `--framework-id`, `--path`, `--local`, `--output-dir`)
`pretorin review status` | Check implementation status for a control (`--control-id`)

## Config Commands

Command | Description
--- | ---
`pretorin config list` | List all configuration
`pretorin config get <key>` | Get a config value
`pretorin config set <key> <value>` | Set a config value
`pretorin config path` | Show config file path

## Deprecated Commands

Command | Description
--- | ---
`pretorin harness init` | Deprecated: initialize harness config
`pretorin harness doctor` | Deprecated: validate harness setup
`pretorin harness run "<task>"` | Deprecated: run task through harness backend

# MCP Integration Overview

The Pretorin CLI includes a built-in Model Context Protocol (MCP) server that enables AI assistants to access compliance framework data directly during conversations.

## Why MCP?

The Model Context Protocol allows AI assistants to:

- Access real-time data — Query the latest compliance frameworks, controls, and requirements
- Understand context — Get detailed control guidance and related controls for better recommendations
- Reduce hallucination — Work with authoritative compliance data instead of training knowledge
- Streamline workflows — No need to copy-paste control requirements or switch between tools

## How It Works

The MCP server communicates via stdio (standard input/output) using JSON-RPC messages. When you start it with `pretorin mcp-serve`, your AI tool connects and gains access to 23 compliance tools.

    ┌──────────────┐     stdio      ┌──────────────┐     HTTPS     ┌──────────────┐
    │   AI Agent   │◄──────────────►│   Pretorin   │◄─────────────►│   Pretorin   │
    │ (Claude,     │   JSON-RPC    │   MCP Server  │              │   Platform   │
    │  Cursor,     │               │               │              │              │
    │  Codex)      │               │               │              │              │
    └──────────────┘               └──────────────┘              └──────────────┘

## Scope

Scoped compliance execution tools on the MCP server run inside exactly one `system + framework` pair at a time. Set the active scope with `pretorin context set`, or pass both values explicitly. If a request spans multiple frameworks or systems, split it into separate runs.

## Tool Categories

The 23 MCP tools are organized into categories:

Category | Tools | Access
--- | --- | ---
Framework & Control Reference | 7 | Read-only, all users
Systems | 3 | Read-only
Evidence Management | 4 | Read/Write, requires beta
Implementation Context | 6 | Read/Write, requires beta
Compliance Updates | 3 | Write, requires beta

See Tool Reference for the complete list.

## Quick Setup

    # 1. Install
    uv tool install pretorin

    # 2. Authenticate
    pretorin login

    # 3. Add to your AI tool (example: Claude Code)
    claude mcp add --transport stdio pretorin -- pretorin mcp-serve

See Setup Guides for other AI tools.

## Example Conversations

### Getting Started with a Framework

> You: What compliance frameworks are available for government systems?

> Claude: Uses pretorin_list_frameworks — I can see several frameworks available including NIST 800-53 Rev 5, NIST 800-171, and FedRAMP at various impact levels…

### Understanding a Control

> You: I need to implement Account Management for our FedRAMP Moderate system. What does it require?

> Claude: Uses pretorin_get_control and pretorin_get_control_references — Account Management requires organizations to manage system accounts including identifying account types, establishing conditions for membership, and specifying authorized users…

### Control Family Overview

> You: Give me an overview of the Audit controls in NIST 800-53

> Claude: Uses pretorin_list_controls with family filter — The Audit and Accountability family contains controls for audit events, content, storage, review, and reporting…

# MCP Setup Guides

## Prerequisites

Install and authenticate the Pretorin CLI:

    uv tool install pretorin
    pretorin login

## Claude Code

Quick setup — run a single command:

    claude mcp add --transport stdio pretorin -- pretorin mcp-serve

This registers the server for your current project. To make it available across all your projects, add `--scope user`.

Team setup — add a `.mcp.json` file to your project root so every team member gets the server automatically:

    {
      "mcpServers": {
        "pretorin": {
          "type": "stdio",
          "command": "pretorin",
          "args": ["mcp-serve"]
        }
      }
    }

Claude Code detects the file automatically.

## Claude Desktop

Add to your Claude Desktop configuration file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

    {
      "mcpServers": {
        "pretorin": {
          "command": "pretorin",
          "args": ["mcp-serve"]
        }
      }
    }

Restart Claude Desktop after saving.

## Cursor

Add to `~/.cursor/mcp.json`:

    {
      "mcpServers": {
        "pretorin": {
          "command": "pretorin",
          "args": ["mcp-serve"]
        }
      }
    }

Restart Cursor after saving.

## OpenAI Codex CLI

Add to `~/.codex/config.toml`:

    [mcp_servers.pretorin]
    command = "pretorin"
    args = ["mcp-serve"]

If you installed Pretorin with `uv tool install` or `pipx`, prefer pinning the absolute path from `command -v pretorin` to avoid PATH drift between shells and GUI apps.

## Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

    {
      "mcpServers": {
        "pretorin": {
          "command": "pretorin",
          "args": ["mcp-serve"]
        }
      }
    }

Restart Windsurf after saving.

## Other MCP Clients

The Pretorin MCP server follows the standard Model Context Protocol and works with any MCP-compatible client. The server communicates via stdio.

To test the server manually:

    pretorin mcp-serve

The server accepts JSON-RPC messages on stdin and responds on stdout.

## PATH Considerations

If your AI tool can’t find the `pretorin` command, use the full path:

    # Find the full path
    command -v pretorin

Then use that path in your configuration:

    {
      "mcpServers": {
        "pretorin": {
          "command": "/home/user/.local/bin/pretorin",
          "args": ["mcp-serve"]
        }
      }
    }

This is especially important for `uv tool` and `pipx` installations where the binary may not be on the PATH available to GUI applications.

# MCP Tool Reference

The MCP server provides 23 tools organized by category.

## Framework & Control Reference

These tools are read-only and available to all authenticated users.

### pretorin_list_frameworks

List all available compliance frameworks.

Parameters: None

Returns: List of frameworks with ID, title, version, tier, and control counts.

### pretorin_get_framework

Get detailed metadata about a specific framework including AI context (purpose, target audience, regulatory context).

Parameters:

- `framework_id` (required) — e.g., `nist-800-53-r5`, `fedramp-moderate`

Returns: Framework details including description, version, OSCAL version, and dates.

### pretorin_list_control_families

List control families for a framework with AI context (domain summary, risk context, implementation priority).

Parameters:

- `framework_id` (required)

Returns: List of control families with ID, title, class, and control count.

### pretorin_list_controls

List controls for a framework, optionally filtered by family.

Parameters:

- `framework_id` (required)
- `family_id` (optional) — Family IDs are slugs like `access-control`, not short codes. CMMC families include a level suffix (e.g., `access-control-level-2`).

Returns: List of controls with ID, title, and family.

### pretorin_get_control

Get detailed control information including AI guidance (summary, control intent, evidence expectations, implementation considerations, common failures, complexity).

Parameters:

- `framework_id` (required)
- `control_id` (required) — NIST/FedRAMP: zero-padded (`ac-01`). CMMC: dotted (`AC.L2-3.1.1`).

Returns: Control details including parameters, parts, and enhancement count.

### pretorin_get_control_references

Get reference information including statement, guidance, objectives, and related controls.

Parameters:

- `framework_id` (required)
- `control_id` (required)

Returns: Statement, guidance, objectives, parameters, and related controls.

### pretorin_get_document_requirements

Get document requirements for a framework.

Parameters:

- `framework_id` (required)

Returns: List of explicit and implicit document requirements with control references.

## Systems

### pretorin_list_systems

List systems in the current organization.

Parameters: None

Returns: System IDs, names, and summary metadata.

### pretorin_get_system

Get system metadata including attached frameworks and security impact level.

Parameters:

- `system_id` (required) — System ID or name

Returns: System metadata.

### pretorin_get_compliance_status

Get framework progress and implementation posture for a system.

Parameters:

- `system_id` (required)

Returns: Framework status summaries and progress metrics.

## Evidence Management

### pretorin_search_evidence

Search current evidence items.

Parameters:

- `system_id` (optional) — System context
- `control_id` (optional) — Filter by control
- `framework_id` (optional) — Filter by framework

Returns: Matching evidence items.

### pretorin_create_evidence

Upsert evidence on the platform (find-or-create by default). If `dedupe` is true, exact matching evidence in the active system/framework scope is reused; otherwise a new record is created.

Parameters:

- `system_id` (required)
- `name` (required)
- `description` (required) — Must be auditor-ready markdown (no headings, at least one rich element, no images)
- `evidence_type` (optional) — Default: `policy_document`
- `control_id` (optional)
- `framework_id` (optional)
- `dedupe` (optional) — Default: `true`

Returns:

- `evidence_id`
- `created` — true if new, false if reused
- `linked` — whether control/system link succeeded
- `match_basis` — `exact_name_desc_type_control_framework` or `none`

### pretorin_link_evidence

Link an existing evidence item to a control.

Parameters:

- `system_id` (required)
- `evidence_id` (required)
- `control_id` (required)
- `framework_id` (optional)

Returns: Link confirmation.

### pretorin_get_narrative

Get the current narrative record for a control.

Parameters:

- `system_id` (required)
- `control_id` (required)
- `framework_id` (required)

Returns: Narrative text, status, and AI confidence metadata.

## Implementation Context

### pretorin_get_control_context

Get rich context for a control including AI guidance, statement, objectives, scope status, and current implementation details.

Parameters:

- `system_id` (required)
- `control_id` (required)
- `framework_id` (required)

Returns: Combined control metadata and implementation details.

### pretorin_get_scope

Get system scope and policy information including excluded controls and Q&A responses.

Parameters:

- `system_id` (required)

Returns: Scope narrative, excluded controls, Q&A responses, and scope status.

### pretorin_get_control_implementation

Get implementation details for a control in a system.

Parameters:

- `system_id` (required)
- `control_id` (required)
- `framework_id` (required)

Returns: Current status, narrative, evidence count, and notes metadata.

### pretorin_get_control_notes

Get notes for a control implementation.

Parameters:

- `system_id` (required)
- `control_id` (required)
- `framework_id` (optional)

Returns: Note list with `total` count.

### pretorin_update_narrative

Push a narrative text update for a control implementation.

Parameters:

- `system_id` (required)
- `control_id` (required)
- `framework_id` (required)
- `narrative` (required) — Must be auditor-ready markdown (no headings, 2+ rich elements, 1+ structural element, no images)
- `is_ai_generated` (optional) — Default: `false`

Returns: Update confirmation.

### pretorin_add_control_note

Add a note for unresolved gaps or manual follow-up actions.

Parameters:

- `system_id` (required)
- `control_id` (required)
- `framework_id` (required)
- `content` (required)

Returns: The created note record.

## Compliance Updates

### pretorin_update_control_status

Update the implementation status for a control.

Parameters:

- `system_id` (required)
- `control_id` (required)
- `status` (required)
- `framework_id` (optional)

Returns: Status update confirmation.

### pretorin_push_monitoring_event

Create a monitoring event for a system.

Parameters:

- `system_id` (required)
- `title` (required)
- `severity` (optional) — `critical`, `high`, `medium`, `low`, `info`
- `event_type` (optional) — `security_scan`, `configuration_change`, `access_review`, `compliance_check`
- `control_id` (optional)
- `description` (optional)

Returns: The created monitoring event.

### pretorin_generate_control_artifacts

Generate read-only AI drafts for a control narrative and evidence-gap assessment.

Parameters:

- `system_id` (required)
- `control_id` (required)
- `framework_id` (required)
- `working_directory` (optional) — Local workspace path for code-aware drafting
- `model` (optional) — Model override

Returns: Draft narrative text plus evidence-gap analysis. Does not write to the platform.

Use `pretorin_update_narrative`, `pretorin_create_evidence`, and `pretorin_add_control_note` to persist approved changes.

# MCP Resources

The MCP server exposes read-only resources for analysis guidance.

## Available Resources

Resource URI | Description
--- | ---
`analysis://schema` | JSON schema for compliance artifacts
`analysis://guide/{framework_id}` | Analysis guide for a specific framework
`analysis://control/{framework_id}/{control_id}` | Analysis guidance for a specific control within one framework scope

## Usage

Access these resources via `ReadMcpResourceTool` with `server: "pretorin"` in your MCP client.

### Analysis Schema

`analysis://schema`

Returns the JSON schema for structured compliance artifacts. Use this when generating artifact JSON to ensure correct structure. See Artifact Schema for documentation.

### Framework Analysis Guide

`analysis://guide/{framework_id}`

Available framework guides:

- `analysis://guide/fedramp-moderate`
- `analysis://guide/nist-800-53-r5`
- `analysis://guide/nist-800-171-r3`

Returns framework-specific analysis guidance including purpose, target audience, scope, and assessment methodology.

### Control Analysis Guidance

`analysis://control/{framework_id}/{control_id}`

Example: `analysis://control/fedramp-moderate/ac-02`

Returns control-specific analysis guidance including search patterns, evidence examples, and assessment criteria for one framework scope.

# MCP Troubleshooting

## “Not authenticated” Error

Ensure you’ve logged in:

    pretorin login
    pretorin whoami  # Verify authentication

## MCP Server Not Found

1. Verify pretorin is installed and in your PATH:

       which pretorin
       pretorin --version

2. Try using the full path in your configuration:

       {
         "mcpServers": {
           "pretorin": {
             "command": "/path/to/pretorin",
             "args": ["mcp-serve"]
           }
         }
       }

3. For `uv tool` or `pipx` installations, find the path:

       command -v pretorin

## Server Crashes or Hangs

Check the MCP server logs:

    pretorin mcp-serve 2>&1 | tee mcp-debug.log

Ensure your API key is valid:

    pretorin whoami

## Framework or Control Not Found

- Verify the framework ID exists: `pretorin frameworks list`
- Verify the control ID exists: `pretorin frameworks controls <framework_id>`
- Check Control ID Formats for correct formatting

## Common ID Mistakes

Error | Fix
--- | ---
`ac-1` not found | Use zero-padded: `ac-01`
`ac` family not found | Use slug: `access-control`
`AC.l2-3.1.1` not found | CMMC is case-sensitive: `AC.L2-3.1.1`
`3.1.1` control not found | 800-171 needs leading zeros: `03.01.01`

## No Systems Found

If `pretorin_list_systems` returns no systems, you need a beta code to create one on the Pretorin platform. Systems cannot be created through the CLI or MCP. Sign up for early access.

## Rate Limiting

The API uses rate limiting. If you receive `429 Too Many Requests` errors, the client automatically retries with exponential backoff. For persistent issues, reduce request frequency.

## Support

- Documentation: platform.pretorin.com/api/docs
- Issues: github.com/pretorin-ai/pretorin-cli/issues
- Platform: platform.pretorin.com

# Agent Overview

The `agent` command group runs autonomous compliance tasks using the Codex agent runtime. This is the Pretorin-hosted model mode — Pretorin manages the AI runtime and routes model calls through its `/v1` endpoints.

If you already use another AI agent (Claude Code, Cursor, etc.), use the MCP mode instead (`pretorin mcp-serve`) and connect Pretorin tools to your existing agent.

## Running a Compliance Task

    # Free-form task
    pretorin agent run "Assess AC-02 implementation gaps for my system"

    # Use a predefined skill
    pretorin agent run --skill gap-analysis "Analyze my system compliance gaps"

## Options

Option | Description
--- | ---
`--skill <name>` | Use a predefined skill template
`--model <model>` | Model override
`--base-url <url>` | Custom model API endpoint
`--working-dir <path>` | Working directory for code analysis
`--no-stream` | Disable streaming output
`--legacy` | Use legacy OpenAI Agents SDK (deprecated)

## Hosted Model Setup

Use this setup when you want `pretorin agent run` to call Pretorin-hosted model endpoints.

    # 1. Login with your Pretorin API key
    pretorin login

    # 2. Optional: custom/self-hosted Pretorin model endpoint
    pretorin config set model_api_base_url https://platform.pretorin.com/v1

    # 3. Validate runtime
    pretorin agent doctor
    pretorin agent install

    # 4. Run a task
    pretorin agent run "Assess AC-02 implementation gaps for my system"

## Model Key Precedence

The agent runtime resolves model keys in this order:

1. `OPENAI_API_KEY` environment variable
2. `config.api_key` (from `pretorin login`)
3. `config.openai_api_key`

If `OPENAI_API_KEY` is set in your shell, it overrides the stored Pretorin login key.

## Custom Model Endpoints

The agent supports any OpenAI-spec LLM endpoint, including:

- Azure OpenAI
- vLLM
- LiteLLM
- Ollama

Configure via `--base-url` flag or the `model_api_base_url` config key.

## How It Works

The agent runtime uses the Codex SDK with an isolated binary managed under `~/.pretorin/codex`. The agent:

1. Downloads and pins a specific Codex binary version
2. Runs in an isolated `CODEX_HOME` environment
3. Automatically injects the Pretorin MCP server for compliance tool access
4. Streams events and output in real-time (unless `--no-stream` is passed)

# Agent Skills

Skills are predefined task templates that guide the agent through specific compliance workflows.

## Available Skills

Skill | Description
--- | ---
`gap-analysis` | Assess codebase against framework controls, identify gaps, and prioritize remediation
`narrative-generation` | Generate auditor-ready implementation narratives for controls
`evidence-collection` | Collect and map evidence from codebase to controls
`security-review` | Review codebase for security controls and compliance posture

## Using Skills

    # Gap analysis
    pretorin agent run --skill gap-analysis "Analyze my system compliance gaps"

    # Narrative generation
    pretorin agent run --skill narrative-generation "Generate narratives for all AC controls"

    # Evidence collection
    pretorin agent run --skill evidence-collection "Collect evidence for AC-02 in this repo"

    # Security review
    pretorin agent run --skill security-review "Review this codebase for AC-02 coverage"

## List Skills

    pretorin agent skills

## Skill Details

### Gap Analysis

Systematically assesses a codebase against a framework’s controls. The agent:

1. Scopes the assessment to relevant control families
2. Prioritizes families with code evidence (Access Control, Audit, IA, SC, CM)
3. Searches the codebase for evidence matching AI guidance expectations
4. Assigns implementation status per control
5. Produces a report with findings and priority remediation items

See Gap Analysis Workflow for the detailed methodology.

### Narrative Generation

Generates control implementation narratives that meet auditor-readiness requirements:

- No markdown headings
- At least two rich markdown elements (code blocks, tables, lists, links)
- At least one structural element (code block, table, or list)
- TODO placeholders for missing information
- Only documents observable facts (no hallucination)

### Evidence Collection

Searches the codebase for evidence that maps to specific controls:

- Identifies relevant files and code patterns
- Creates evidence items with auditor-ready descriptions
- Links evidence to controls via the platform
- Flags gaps where evidence is missing

### Security Review

Reviews the codebase against specific controls:

- Analyzes code for control coverage
- Identifies implementation strengths and weaknesses
- Documents findings with file paths and line numbers
- Produces remediation recommendations

# Agent Runtime Management

The agent runtime uses a managed Codex binary with isolated configuration.

## Check Runtime Health

    pretorin agent doctor

Validates that the Codex runtime is properly installed and configured.

## Install Codex Binary

    pretorin agent install

Downloads the pinned Codex binary to `~/.pretorin/bin/`. The version is pinned by the CLI to ensure compatibility.

## Check Version

    pretorin agent version

Shows the pinned Codex version and whether it’s currently installed.

## Manage MCP Servers

The agent can connect to additional MCP servers beyond Pretorin. This lets the agent access other tools (filesystem, databases, etc.) during compliance tasks.

### List Configured Servers

    pretorin agent mcp-list

### Add a Server

    pretorin agent mcp-add <name> stdio <command> --arg <arg1> --arg <arg2>

Example:

    pretorin agent mcp-add filesystem stdio node --arg /path/to/fs-server

### Remove a Server

    pretorin agent mcp-remove <name>

## Runtime Architecture

The Codex runtime is fully isolated:

- Binary location: `~/.pretorin/bin/`
- Configuration: `~/.pretorin/codex/` (`CODEX_HOME`)
- Version pinning: The CLI pins a specific Codex version for compatibility
- MCP injection: Pretorin MCP server is automatically available to the agent

This isolation ensures the agent runtime never interferes with any user-installed Codex instances.

# Supported Frameworks

Pretorin provides access to 8 compliance framework profiles spanning federal, contractor, and defense industrial base requirements.

## Framework Overview

ID | Title | Version | Families | Controls
--- | --- | --- | --- | ---
`nist-800-53-r5` | NIST SP 800-53 Rev 5 | 5.2.0 | 20 | 324
`nist-800-171-r3` | NIST SP 800-171 Revision 3 | 1.0.0 | 17 | 130
`fedramp-low` | FedRAMP Rev 5 Low Baseline | fedramp2.1.0 | 18 | 135
`fedramp-moderate` | FedRAMP Rev 5 Moderate Baseline | fedramp2.1.0 | 18 | 181
`fedramp-high` | FedRAMP Rev 5 High Baseline | fedramp2.1.0 | 18 | 191
`cmmc-l1` | CMMC 2.0 Level 1 (Foundational) | 2.0 | 6 | 17
`cmmc-l2` | CMMC 2.0 Level 2 (Advanced) | 2.0 | 14 | 110
`cmmc-l3` | CMMC 2.0 Level 3 (Expert) | 2.0 | 10 | 24

Always call `pretorin frameworks list` to get the current list from the API.

## Framework Relationships

Understanding how frameworks relate helps with cross-compliance:

    NIST 800-53 Rev 5 (full catalog, 324 controls)
    ├── FedRAMP Low/Moderate/High (800-53 subset + cloud requirements)
    ├── NIST 800-171 Rev 3 (800-53 subset for CUI in non-federal systems)
    │   └── CMMC Level 2 (maps to 800-171 requirements)
    └── CMMC Level 3 (advanced controls beyond 800-171)

If an organization is already compliant with a parent framework, many child framework controls are already satisfied.

## NIST SP 800-53 Rev 5

The foundational catalog for federal information systems. Contains 324 controls across 20 families covering all aspects of information security. All other US government frameworks derive from it.

Target audience: Federal agencies

## NIST SP 800-171 Rev 3

Protects Controlled Unclassified Information (CUI) in non-federal systems. A focused subset of 800-53 with 130 requirements.

Target audience: Federal contractors, universities, and other non-federal entities handling CUI under DFARS 252.204-7012 or similar requirements.

## FedRAMP

Based on NIST 800-53 with additional cloud-specific requirements. Required for cloud services used by federal agencies.

Impact levels:

Level | ID | Controls | Use When
--- | --- | --- | ---
Low | `fedramp-low` | 135 | Public, non-sensitive data. Limited adverse effect from loss.
Moderate | `fedramp-moderate` | 181 | CUI, PII, sensitive data. Serious adverse effect from loss. Most common level.
High | `fedramp-high` | 191 | Life-safety, financial, law enforcement data. Severe/catastrophic effect from loss.

Target audience: Cloud service providers to government

## CMMC 2.0

Cybersecurity Maturity Model Certification for defense contractors. Required by DoD contracts.

Level | ID | Controls | Use When
--- | --- | --- | ---
Level 1 | `cmmc-l1` | 17 | Handles only Federal Contract Information (FCI). Basic cyber hygiene.
Level 2 | `cmmc-l2` | 110 | Handles CUI. Aligns with NIST 800-171. Most defense contractors need this.
Level 3 | `cmmc-l3` | 24 | Highest sensitivity CUI. Advanced practices on top of Level 2.

Target audience: Defense industrial base organizations

> Note: CMMC Level 3 controls are in addition to Level 2. An organization at Level 3 must also satisfy all Level 2 controls.

See Framework Selection Guide for help choosing the right framework.

# Control ID Formats

Correct ID formatting is critical. The Pretorin API returns errors on malformed IDs. When unsure, discover IDs first with `pretorin frameworks families <id>` or `pretorin frameworks controls <id>`.

## NIST 800-53 Rev 5 / FedRAMP

Framework IDs: `nist-800-53-r5`, `fedramp-low`, `fedramp-moderate`, `fedramp-high`

### Family IDs

Family IDs are lowercase slugs, not short codes:

Correct | Incorrect
--- | ---
`access-control` | `ac`
`audit-and-accountability` | `au`
`identification-and-authentication` | `ia`
`system-and-communications-protection` | `sc`
`configuration-management` | `cm`
`incident-response` | `ir`
`risk-assessment` | `ra`

### Control IDs

Control IDs are zero-padded with a hyphen:

Correct | Incorrect
--- | ---
`ac-01` | `ac-1`, `AC-1`, `ac1`
`ac-02` | `ac-2`, `AC-2`, `ac2`
`au-02` | `au-2`, `AU-2`
`sc-07` | `sc-7`, `SC-7`

## CMMC 2.0

Framework IDs: `cmmc-l1`, `cmmc-l2`, `cmmc-l3`

### Family IDs

CMMC family IDs include a level suffix:

Correct | Incorrect
--- | ---
`access-control-level-1` | `access-control`, `ac`
`access-control-level-2` | `access-control`, `ac-l2`
`incident-response-level-2` | `incident-response`, `ir`
`system-and-communications-protection-level-3` | `sc`, `sc-l3`

### Control IDs

CMMC control IDs use dotted notation with a level prefix and are case-sensitive:

Correct | Incorrect
--- | ---
`AC.L2-3.1.1` | `ac-01`, `3.1.1`
`SC.L3-3.13.2` | `sc-07`, `3.13.2`
`AC.L1-3.1.22` | `ac.l1-3.1.22`

Use uppercase for the family prefix (e.g., `AC`, not `ac`).

## NIST 800-171 Rev 3

Framework ID: `nist-800-171-r3`

### Family IDs

Family IDs use the same lowercase slug convention as NIST 800-53:

Correct | Incorrect
--- | ---
`access-control` | `ac`, `3.1`
`incident-response` | `ir`, `3.6`
`identification-and-authentication` | `ia`, `3.5`

### Control IDs

Control IDs use dotted notation with leading zeros:

Correct | Incorrect
--- | ---
`03.01.01` | `3.1.1`, `ac-01`
`03.01.02` | `3.1.2`, `ac-02`
`03.13.01` | `3.13.1`, `sc-01`

## Discovery Workflow

When a user provides an informal control reference (e.g., “AC-2” or “access control”):

1. Call `pretorin frameworks families <framework_id>` to find the correct family slug
2. Call `pretorin frameworks controls <framework_id> --family <family_slug>` to find the correct control ID
3. Use the discovered ID in subsequent calls

## Quick Reference

Framework | Family Format | Control Format | Example
--- | --- | --- | ---
NIST 800-53 | `access-control` | `ac-01` | `pretorin frameworks control nist-800-53-r5 ac-02`
FedRAMP | `access-control` | `ac-01` | `pretorin frameworks control fedramp-moderate ac-02`
CMMC | `access-control-level-2` | `AC.L2-3.1.1` | `pretorin frameworks control cmmc-l2 AC.L2-3.1.1`
800-171 | `access-control` | `03.01.01` | `pretorin frameworks control nist-800-171-r3 03.01.01`

# Framework Selection Guide

Use this decision tree to identify the right compliance framework for your situation.

## Decision Tree

### 1. Federal Agency (US Government)

Use: NIST 800-53 Rev 5 (`nist-800-53-r5`)

The foundational catalog for federal information systems. All other US government frameworks derive from it. Contains 324 controls across 20 families. Use this when the organization IS a federal agency and needs the full control catalog.

### 2. Federal Contractor Handling CUI

Use: NIST 800-171 Rev 3 (`nist-800-171-r3`)

Protects Controlled Unclassified Information (CUI) in non-federal systems. A focused subset of 800-53 with 130 requirements. Use this when the organization is a contractor, university, or other non-federal entity that handles CUI under DFARS 252.204-7012 or similar requirements.

### 3. Cloud Service Provider to Government

Use: FedRAMP (`fedramp-low`, `fedramp-moderate`, `fedramp-high`)

Based on NIST 800-53 with additional cloud-specific requirements. Required for cloud services used by federal agencies.

Level | ID | Controls | Use When
--- | --- | --- | ---
Low | `fedramp-low` | 135 | Public, non-sensitive data. Loss would have limited adverse effect.
Moderate | `fedramp-moderate` | 181 | CUI, PII, sensitive but not critical data. Loss would have serious adverse effect. Most common level.
High | `fedramp-high` | 191 | Life-safety, financial, law enforcement, or emergency services data. Loss would have severe or catastrophic effect.

When unsure, FedRAMP Moderate is the most common starting point for cloud services handling government data.

### 4. Defense Industrial Base (DIB)

Use: CMMC (`cmmc-l1`, `cmmc-l2`, `cmmc-l3`)

Cybersecurity Maturity Model Certification for defense contractors. Required by DoD contracts.

Level | ID | Controls | Use When
--- | --- | --- | ---
Level 1 | `cmmc-l1` | 17 | Handles only Federal Contract Information (FCI). Basic cyber hygiene.
Level 2 | `cmmc-l2` | 110 | Handles CUI. Aligns with NIST 800-171. Most defense contractors need this.
Level 3 | `cmmc-l3` | 24 | Highest sensitivity CUI. Advanced/progressive practices on top of Level 2.

Note: CMMC Level 3 controls are in addition to Level 2.

## Quick Reference

Situation | Framework | ID
--- | --- | ---
We’re a federal agency | NIST 800-53 | `nist-800-53-r5`
We handle CUI as a contractor | NIST 800-171 | `nist-800-171-r3`
We’re a cloud service for government | FedRAMP | `fedramp-moderate`
We have a DoD contract | CMMC | `cmmc-l2`
We need to handle both CUI and cloud | FedRAMP + 800-171 | Start with `fedramp-moderate`
We’re not sure yet | Start with NIST 800-53 | `nist-800-53-r5`

## Using AI Context for Selection

Call `pretorin_get_framework` (MCP) or `pretorin frameworks get <id>` (CLI) to get AI context including purpose, target audience, regulatory context, scope, and key concepts. This helps confirm whether a framework is the right fit.

# Narrative & Evidence Workflow

This is the core workflow for updating control implementations on the platform. Follow this sequence for any control update.

## Workflow Steps

### 1. Resolve the Target

Identify the `system_id`, `control_id`, and `framework_id` for your update. Set the active context:

    pretorin context set --system "My Application" --framework fedramp-moderate

### 2. Read Current State

Before making changes, understand what’s already there:

    # Get full control context (requirements + current implementation)
    # Via MCP: pretorin_get_control_context

    # Get current narrative
    pretorin narrative get ac-02 fedramp-moderate

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

    # List existing notes
    pretorin notes list ac-02 fedramp-moderate

### 3. Collect Observable Facts

Search your codebase and connected systems for evidence. Only document what is directly observable — never assume or fabricate implementation details.

### 4. Draft Updates

Prepare three types of updates:

Narrative — How the control is implemented. Include TODO placeholders for unknowns:

    [[PRETORIN_TODO]]
    missing_item: SSO configuration details
    reason: Not observable from current workspace and connected MCP systems
    required_manual_action: Export IdP SAML configuration
    suggested_evidence_type: configuration
    [[/PRETORIN_TODO]]

Evidence — Specific artifacts demonstrating implementation (config files, code, policies).

Gap Notes — Unresolved items requiring manual follow-up:

    Gap: Missing MFA enforcement evidence
    Observed: TOTP library imported in auth module
    Missing: MFA policy enforcement configuration
    Why missing: IdP admin console not accessible via codebase
    Manual next step: Screenshot MFA policy from Azure AD admin portal

### 5. Push Updates

    # Push narrative
    pretorin narrative push ac-02 fedramp-moderate "My Application" narrative-ac02.md

    # Upsert evidence (finds or creates, then links)
    pretorin evidence upsert ac-02 fedramp-moderate \
      --name "RBAC Configuration" \
      --description "Role mapping in IdP" \
      --type configuration

    # Add gap notes
    pretorin notes add ac-02 fedramp-moderate \
      --content "Gap: Missing MFA evidence..."

## Read-Only Draft Workflow

When you want AI drafts before any platform writes:

1. Resolve scope (system, control, framework)
2. Read current state (context, narrative, evidence, notes)
3. Generate drafts via `pretorin agent run --skill narrative-generation` or the MCP `pretorin_generate_control_artifacts` tool
4. Review the draft — clearly separate candidate narrative, evidence gaps, and manual follow-up actions
5. Only push to the platform after explicit approval

## Markdown Quality Rules

All narratives and evidence must pass markdown quality validation:

### Narratives

- No markdown headings (`#`, `##`, etc.)
- At least 2 rich markdown elements (code blocks, tables, lists, links)
- At least 1 structural element (code block, table, or list)
- No markdown images

### Evidence

- No markdown headings
- At least 1 rich markdown element
- No markdown images

## Evidence Deduplication

`pretorin evidence upsert` and the MCP `pretorin_create_evidence` tool use find-or-create logic by default (`dedupe: true`):

1. Search for an exact match on (name + description + type + control + framework) within the active system scope
2. If found, reuse the existing evidence item
3. If not found, create a new one
4. Ensure the evidence is linked to the specified control

The response indicates whether the evidence was `created` (new) or reused, along with the `match_basis`.

# Gap Analysis Workflow

A systematic approach to assessing a codebase against a compliance framework’s controls.

## Step 1: Scope the Assessment

Determine which framework and control families to assess.

    # List frameworks if not specified
    pretorin frameworks list

    # List control families for the chosen framework
    pretorin frameworks families fedramp-moderate

Not all families will have code evidence. Prioritize based on evidence likelihood.

## Step 2: Prioritize Control Families

### High Priority (Direct Code Evidence)

These families typically have strong evidence in source code:

Family | What to Search For
--- | ---
Access Control (AC) | Authentication systems, RBAC/ABAC, session management, user provisioning
Audit & Accountability (AU) | Logging frameworks, audit trails, log retention, structured logging
Identification & Authentication (IA) | Login flows, MFA, password hashing, credential storage, OAuth/SAML
System & Communications Protection (SC) | TLS config, encryption, network boundaries, CORS, API security
Configuration Management (CM) | Config files, env handling, version pinning, baseline settings, IaC

### Medium Priority (Mixed Code/Policy)

Family | What to Search For
--- | ---
System Acquisition (SA) | Secure development practices, dependency management, SAST/DAST configs
System Integrity (SI) | Input validation, error handling, malware protection configs
Assessment (CA) | Security testing configs, vulnerability scanning, CI/CD security gates

### Lower Priority (Mostly Policy)

Primarily documentation-based, unlikely to have code evidence:

- Awareness & Training (AT)
- Planning (PL)
- Personnel Security (PS)
- Physical Protection (PE)
- Program Management (PM)

## Step 3: Collect Evidence

For each high-priority family:

1. List controls filtered by family:

       pretorin frameworks controls fedramp-moderate --family access-control

2. For each relevant control, get AI guidance:

       pretorin frameworks control fedramp-moderate ac-02 --references

   The `ai_guidance` field provides evidence expectations, implementation considerations, and common failures.

3. Search the codebase using guidance-informed patterns:

File patterns:

    **/auth/**          **/users/**         **/accounts/**
    **/logging/**       **/audit/**         **/security/**
    **/config/**        **/settings/**      **/crypto/**
    **/identity/**      **/iam/**           **/rbac/**
    **/middleware/**     **/terraform/**     **/k8s/**

Keyword patterns:

    authenticate, authorize, permission, role, session
    log, audit, event, trace, record
    encrypt, tls, ssl, https, certificate
    config, setting, baseline, default
    password, credential, hash, mfa, token

4. For each piece of evidence, note the file path, line numbers, and what it demonstrates.

## Step 4: Assess Implementation Status

For each control, assign a status:

Status | Criteria
--- | ---
Implemented | Full requirements met with clear code evidence
Partial | Some requirements met, others missing or incomplete
Planned | Architecture supports it but feature not built yet
Not Applicable | Control doesn’t apply to this component
Gap | Control requirements not addressed at all

Use `ai_guidance.common_failures` to calibrate your assessment — if the codebase exhibits a known failure pattern, it’s likely a gap or partial implementation.

## Step 5: Produce the Report

Structure the gap analysis output as:

### Summary

- Framework assessed and total controls in scope
- Counts by status (implemented, partial, planned, not applicable, gap)
- Overall compliance posture assessment

### Family-by-Family Findings

For each assessed family:

- Family name and total controls
- Status breakdown
- Key findings with evidence references
- Gaps with remediation recommendations

### Priority Remediation Items

Rank gaps by:

1. Controls with the highest security impact
2. Controls that are prerequisites for other controls (check related controls)
3. Controls that are easiest to implement (quick wins)

### Evidence Summary

For each assessed control:

- Control ID and title
- Implementation status
- Evidence file paths and descriptions
- Recommendations if partial or gap

## Example Output

See the example gap analysis for a complete sample report.

## Tips

- Start broad (family level) and drill into specific controls where evidence exists
- Use `pretorin frameworks control <fw> <ctrl>` for AI guidance — it provides the richest context
- Use `--references` for formal statement, objectives, and related controls
- Check related controls to identify dependencies
- For infrastructure evidence, look at Terraform, CloudFormation, Dockerfiles, Helm charts, and CI/CD configs
- For application evidence, focus on auth, logging, crypto, and configuration code

# Example: Gap Analysis Report

This example shows a gap analysis for a hypothetical web application assessed against FedRAMP Moderate.

## Gap Analysis: Acme Web Platform — FedRAMP Moderate

### Summary

Metric | Value
--- | ---
Framework | FedRAMP Rev 5 Moderate (`fedramp-moderate`)
Component | Acme Web Platform
Families Assessed | 5 of 18 (high-priority code-evidenced families)
Controls in Scope | 47
Implemented | 18 (38%)
Partial | 14 (30%)
Planned | 3 (6%)
Not Applicable | 4 (9%)
Gap | 8 (17%)

Overall Posture: Partial compliance. Strong authentication and logging foundations, but gaps in account lifecycle management, boundary protection, and baseline configuration documentation.

### Access Control (AC) — 12 controls assessed

Status: 5 implemented, 4 partial, 1 planned, 2 gap

Key Findings:

- AC-02 (Account Management) — Partial. User creation with role assignment exists in `src/auth/users.py:45-72`, but no account expiration, dormant account handling, or manager approval workflow.
- AC-03 (Access Enforcement) — Implemented. RBAC middleware in `src/middleware/auth.py:12-38` enforces role-based access on all API routes.
- AC-07 (Unsuccessful Logon Attempts) — Implemented. Account lockout after 5 failed attempts in `src/auth/login.py:89-105`.
- AC-17 (Remote Access) — Gap. No VPN or remote access controls documented.

Recommendations:

1. Add account expiration and dormant account cleanup (addresses AC-02 gaps)
2. Implement remote access policy and controls for administrative access (addresses AC-17)

### Audit & Accountability (AU) — 8 controls assessed

Status: 5 implemented, 2 partial, 1 gap

Key Findings:

- AU-02 (Audit Events) — Implemented. Structured JSON logging for auth events, data access, and admin actions.
- AU-03 (Content of Audit Records) — Implemented. Logs include timestamp, user ID, action, outcome, and source IP.
- AU-06 (Audit Record Review) — Gap. No automated log review or alerting configured.

Recommendations:

1. Configure CloudWatch alarms for security events (addresses AU-06)
2. Add log review procedures and alerting rules

### System & Communications Protection (SC) — 10 controls assessed

Status: 2 implemented, 4 partial, 2 planned, 2 not applicable

Key Findings:

- SC-07 (Boundary Protection) — Partial. TLS 1.3 and CORS configured, but security groups allow broad ingress.
- SC-08 (Transmission Confidentiality) — Implemented. All traffic encrypted via TLS 1.3 with HSTS.
- SC-28 (Protection of Information at Rest) — Planned. Database encryption not yet enabled.

### Priority Remediation

Priority | Control | Gap | Effort
--- | --- | --- | ---
1 | SC-28 | Enable RDS encryption at rest | Low — Terraform change
2 | AU-06 | Add CloudWatch alerting for security events | Medium — alerting rules
3 | AC-02 | Account lifecycle management | Medium — new feature
4 | CM-02/CM-06 | Baseline configuration documentation | Medium — documentation
5 | AC-17 | Remote access controls for admin access | High — new infrastructure

# Artifact Generation

Compliance artifacts are structured JSON documents that describe how a specific control is implemented within a component.

## Generating Artifacts

### Via Agent

    pretorin agent run --skill evidence-collection "Generate artifact for AC-02 in my system"

### Via MCP

Use the `pretorin_generate_control_artifacts` tool for read-only AI drafts.

### Submit to Platform

    pretorin frameworks submit-artifact artifact.json

## Artifact Schema

    {
      "framework_id": "fedramp-moderate",
      "control_id": "ac-02",
      "component": {
        "component_id": "my-application",
        "title": "My Application",
        "description": "A web application that handles user data",
        "type": "software",
        "control_implementations": [
          {
            "control_id": "ac-02",
            "description": "2-3 sentence narrative explaining HOW the control is implemented",
            "implementation_status": "implemented",
            "responsible_roles": ["System Administrator", "Security Team"],
            "evidence": [
              {
                "description": "What this evidence demonstrates",
                "file_path": "src/auth/users.py",
                "line_numbers": "45-72",
                "code_snippet": "def create_user(username, role):\n    ..."
              }
            ],
            "remarks": "Optional additional context"
          }
        ]
      },
      "confidence": "high"
    }

See Artifact Schema Reference for the full field documentation.

## Implementation Status Values

Status | Criteria
--- | ---
`implemented` | Fully implemented and operational. Clear, direct code evidence.
`partial` | Some aspects implemented, others pending.
`planned` | Not yet implemented but scheduled. Architecture supports it.
`not-applicable` | Control doesn’t apply to this component.

## Confidence Levels

Level | Criteria
--- | ---
`high` | Clear, direct evidence in code. Specific file paths and line numbers.
`medium` | Reasonable evidence with some inference required.
`low` | Limited evidence. Significant assumptions made.

## Evidence Quality

Good evidence shows HOW a control is implemented with specifics. Weak evidence merely shows that relevant code exists.

Good:

> User creation requires role assignment and manager approval via the `create_user()` function which validates roles against an allowlist and triggers an approval workflow.

Weak:

> Has a User class in the models file.

### Guidelines

- Call `pretorin frameworks control <fw> <ctrl>` first — the AI guidance describes exactly what evidence assessors expect
- Include specific file paths and line numbers
- Keep code snippets brief (under 10 lines)
- Focus on the most relevant evidence, not exhaustive listing
- Describe what the evidence demonstrates in relation to the control requirement

## Example: Good Artifact

    {
      "framework_id": "fedramp-moderate",
      "control_id": "ac-02",
      "component": {
        "component_id": "acme-web-platform",
        "title": "Acme Web Platform",
        "description": "A web application with multi-tenant user management",
        "type": "software",
        "control_implementations": [
          {
            "control_id": "ac-02",
            "description": "The application implements account management through a provisioning system that requires role assignment during user creation, enforces manager approval for elevated roles, and automatically disables accounts after 90 days of inactivity.",
            "implementation_status": "implemented",
            "responsible_roles": ["System Administrator", "Security Team", "Team Managers"],
            "evidence": [
              {
                "description": "User creation requires role assignment and manager approval for admin roles",
                "file_path": "src/users/provisioning.py",
                "line_numbers": "45-72",
                "code_snippet": "def create_user(username, role, manager_id):\n    validate_role(role)\n    if role in ELEVATED_ROLES:\n        require_approval(manager_id)\n    user = User.create(username=username, role=role)"
              },
              {
                "description": "Automated dormant account detection and deactivation after 90 days",
                "file_path": "src/users/lifecycle.py",
                "line_numbers": "120-145",
                "code_snippet": "def check_dormant_accounts():\n    threshold = datetime.utcnow() - timedelta(days=90)\n    dormant = User.query.filter(User.last_login < threshold)"
              }
            ],
            "remarks": "Account removal via soft delete to maintain audit trail."
          }
        ]
      },
      "confidence": "high"
    }

## Example: Partial Implementation

    {
      "framework_id": "fedramp-moderate",
      "control_id": "sc-07",
      "component": {
        "component_id": "acme-web-platform",
        "title": "Acme Web Platform",
        "description": "A web application with multi-tenant user management",
        "type": "software",
        "control_implementations": [
          {
            "control_id": "sc-07",
            "description": "TLS 1.3 enforced and CORS restricted to specific origins. However, security group ingress allows broad access from 0.0.0.0/0 on port 443, and no WAF is configured.",
            "implementation_status": "partial",
            "responsible_roles": ["System Administrator", "DevOps Team"],
            "evidence": [
              {
                "description": "CORS restricted to application origins only",
                "file_path": "src/api/middleware.py",
                "line_numbers": "8-15",
                "code_snippet": "app.add_middleware(\n    CORSMiddleware,\n    allow_origins=['https://app.acme.com'])"
              },
              {
                "description": "Security group allows unrestricted ingress — overly permissive",
                "file_path": "terraform/security.tf",
                "line_numbers": "12-25",
                "code_snippet": "ingress {\n    from_port = 443\n    cidr_blocks = [\"0.0.0.0/0\"]\n}"
              }
            ],
            "remarks": "Recommend restricting security group ingress and adding WAF."
          }
        ]
      },
      "confidence": "medium"
    }

# Cross-Framework Mapping

Map controls across related frameworks to identify overlaps, reduce duplicate work, and understand framework relationships.

## When to Use Cross-Framework Mapping

- Dual compliance — Organization needs FedRAMP + CMMC. Map overlapping controls to avoid duplicate work.
- Framework migration — Moving from 800-171 to FedRAMP. Identify which controls already satisfy FedRAMP requirements.
- Gap identification — Already compliant with 800-53 and need CMMC. Find the delta.
- Audit preparation — Show auditors how controls in one framework map to another.

## Workflow

### Step 1: Start with the Source Control

Query the control with references to discover relationships:

    pretorin frameworks control nist-800-53-r5 ac-02 --references

The Related Controls field reveals connections to other controls and frameworks.

### Step 2: Build the Mapping

Look up the equivalent control in each target framework:

Framework | Control ID | Title
--- | --- | ---
NIST 800-53 Rev 5 | `ac-02` | Account Management
FedRAMP Moderate | `ac-02` | Account Management
NIST 800-171 Rev 3 | `03.01.01` | Account Management
CMMC Level 2 | `AC.L2-3.1.1` | Authorized Access Control

### Step 3: Compare Requirements

Get details for each framework’s version of the control:

    pretorin frameworks control nist-800-53-r5 ac-02 --references
    pretorin frameworks control fedramp-moderate ac-02 --references
    pretorin frameworks control nist-800-171-r3 03.01.01 --references
    pretorin frameworks control cmmc-l2 AC.L2-3.1.1 --references

Compare what each framework emphasizes. For Account Management:

- NIST 800-53 — Full control with 13 enhancements. Covers account types, conditions, authorized users, managers, CRUD, monitoring, and atypical usage.
- FedRAMP Moderate — Same base control with FedRAMP-specific parameter values (e.g., specific timeframes for disabling inactive accounts).
- NIST 800-171 — Streamlined from 800-53. Core requirements: defining types, assigning managers, establishing conditions, authorizing access, monitoring.
- CMMC Level 2 — Maps directly to 800-171 03.01.01. Same core requirements framed as maturity practices.

### Step 4: Identify Gaps and Overlaps

    NIST 800-53 AC-02 (most comprehensive)
      ├── Includes all FedRAMP Moderate AC-02 requirements ✓
      ├── Includes all NIST 800-171 03.01.01 requirements ✓
      └── Includes all CMMC L2 AC.L2-3.1.1 requirements ✓

    FedRAMP Moderate AC-02
      ├── Satisfies NIST 800-171 03.01.01 ✓
      └── Satisfies CMMC L2 AC.L2-3.1.1 ✓

    NIST 800-171 03.01.01
      └── Satisfies CMMC L2 AC.L2-3.1.1 ✓

Key insight: Compliance with a parent framework generally satisfies the child framework’s corresponding control. Always verify with `pretorin frameworks control <fw> <ctrl> --references` to check for framework-specific parameters or additional requirements.

## Using MCP for Cross-Framework Mapping

With an MCP-connected AI agent, ask questions like:

> “Map Account Management controls across NIST 800-53, FedRAMP Moderate, and CMMC Level 2. Show me the overlaps and any unique requirements.”

The agent will use `pretorin_get_control` and `pretorin_get_control_references` to discover and compare related controls across frameworks.

# Environment Variables

Environment variables override stored configuration values.

## Authentication & API

Variable | Description | Default
--- | --- | ---
`PRETORIN_API_KEY` | API key for platform access. Overrides `api_key` in config file. | —
`PRETORIN_PLATFORM_API_BASE_URL` | Platform REST API base URL | `https://platform.pretorin.com/api/v1/public`
`PRETORIN_API_BASE_URL` | Backward-compatible alias for `PRETORIN_PLATFORM_API_BASE_URL` | —
`PRETORIN_MODEL_API_BASE_URL` | Model API URL for agent runtime | `https://platform.pretorin.com/v1`

## Agent Runtime

Variable | Description | Default
--- | --- | ---
`OPENAI_API_KEY` | Model key override for agent runtime. Takes precedence over stored Pretorin login key. | —

## Behavior

Variable | Description | Default
--- | --- | ---
`PRETORIN_DISABLE_UPDATE_CHECK` | Set to `1` to disable passive update notifications | —
`PRETORIN_LOG_LEVEL` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `WARNING`

## Precedence

For the API key:

1. `PRETORIN_API_KEY` environment variable (highest)
2. `api_key` in `~/.pretorin/config.json`

For the model key (agent runtime):

1. `OPENAI_API_KEY` environment variable (highest)
2. `config.api_key` (from `pretorin login`)
3. `config.openai_api_key`

## CI/CD Example

    export PRETORIN_API_KEY=pretorin_your_key_here
    export PRETORIN_DISABLE_UPDATE_CHECK=1

    pretorin frameworks list
    pretorin evidence push

# Artifact Schema Reference

Complete field reference for compliance artifact JSON documents.

## Top-Level Fields

Field | Type | Required | Description
--- | --- | --- | ---
`framework_id` | string | Yes | The compliance framework (e.g., `fedramp-moderate`, `nist-800-53-r5`)
`control_id` | string | Yes | The control being addressed (e.g., `ac-02`, `au-02`)
`component` | object | Yes | The system component being assessed
`confidence` | string | Yes | Confidence in the analysis: `high`, `medium`, or `low`

## Component Fields

Field | Type | Required | Description
--- | --- | --- | ---
`component_id` | string | Yes | Source identifier (repository name, package name)
`title` | string | Yes | Human-readable component name
`description` | string | Yes | Brief description of what the component does
`type` | string | Yes | One of: `software`, `hardware`, `service`, `policy`, `process`
`control_implementations` | array | Yes | How the control is implemented

## Control Implementation Fields

Field | Type | Required | Description
--- | --- | --- | ---
`control_id` | string | Yes | Must match parent `control_id`
`description` | string | Yes | 2-3 sentence narrative of HOW the control is implemented
`implementation_status` | string | Yes | `implemented`, `partial`, `planned`, or `not-applicable`
`responsible_roles` | array | No | Roles responsible (default: `["System Administrator"]`)
`evidence` | array | No | Supporting evidence items
`remarks` | string | No | Additional notes or caveats

## Evidence Fields

Field | Type | Required | Description
--- | --- | --- | ---
`description` | string | Yes | Narrative of what this evidence shows
`file_path` | string | No | Path to the source file
`line_numbers` | string | No | Line range (e.g., `"10-25"`)
`code_snippet` | string | No | Relevant code excerpt (keep under 10 lines)

## Implementation Status Definitions

Status | Definition
--- | ---
`implemented` | Control is fully implemented and operational. Clear, direct evidence exists in the codebase.
`partial` | Some aspects are implemented, others are pending. Example: user CRUD exists but no account expiration or manager approval.
`planned` | Not yet implemented but scheduled. The architecture supports it but the feature isn’t built.
`not-applicable` | Control doesn’t apply to this component. Example: a pure API service with no user accounts doesn’t need account management controls.

## Confidence Levels

Level | Definition
--- | ---
`high` | Clear, direct evidence in code. Well-documented implementations with specific file paths and line numbers.
`medium` | Reasonable evidence but some inference required. The implementation likely satisfies the control but some aspects aren’t explicitly documented.
`low` | Limited evidence. Significant assumptions made. The codebase has relevant code but the connection to the control requirement is indirect.

# Contributing

Thank you for your interest in contributing to the Pretorin CLI!

## Getting Started

1. Fork the repository
2. Clone your fork:

       git clone https://github.com/YOUR_USERNAME/pretorin-cli.git
       cd pretorin-cli

3. Install development dependencies:

       uv pip install -e ".[dev]"

## Development Workflow

### Running Tests

    pytest

Integration tests require an API key and are marked with `@pytest.mark.integration`:

    pytest -m integration

### Type Checking

    mypy src/pretorin

### Linting

    ruff check src/pretorin
    ruff format src/pretorin

### Full CI Check

Run the same checks as the CI pipeline:

    ruff check src/pretorin && ruff format --check src/pretorin && mypy src/pretorin && pytest

## Submitting Changes

1. Create a feature branch from `master`
2. Make your changes
3. Ensure tests pass and code is properly formatted
4. Submit a pull request

## Code Style

- Follow PEP 8 guidelines
- Use type hints for all function signatures
- Write docstrings for public functions and classes
- Keep functions focused and small

## CI Pipeline

The CI pipeline runs on Python 3.10, 3.11, and 3.12:

- Lint — Ruff check + format
- Audit — pip-audit (dependency vulnerability scan)
- Type check — mypy strict mode
- Test — pytest

## Reporting Issues

Use GitHub Issues to report bugs or request features. Include:

- Clear description of the issue
- Steps to reproduce (for bugs)
- Expected vs actual behavior
- CLI version (`pretorin version`)

## Questions?

- API documentation: platform.pretorin.com/api/docs
- Platform: platform.pretorin.com

# Changelog

All notable changes to the Pretorin CLI are documented here. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

## 0.8.0 - 2026-03-07

### Added

- MCP `pretorin_generate_control_artifacts` for read-only AI drafting of control narratives and evidence-gap assessments
- Shared AI drafting workflow helper for structured MCP/CLI parity

### Changed

- MCP system-scoped tools now resolve friendly system names the same way the CLI does
- Codex Desktop MCP configuration can be pinned to the UV-managed Pretorin wrapper

## 0.7.0 - 2026-03-07

### Fixed

- Control implementation parsing tolerant of `notes: null` deployments
- Compatibility fallback for control note reads when `/notes` endpoint returns `405`
- Compatibility fallback for evidence search on system-scoped evidence routes
- Agent `--no-stream` crash on literal `[[PRETORIN_TODO]]` blocks

### Changed

- MCP and legacy agent evidence search tools accept optional `system_id` context

## 0.6.1 - 2026-03-05

### Fixed

- Added required MCP registry ownership marker for PyPI validation

## 0.6.0 - 2026-03-05

### Added

- Shared markdown quality validator for auditor-readable artifacts
- Dedicated tests for markdown quality guardrails
- CLI/MCP/agent parity for reading notes via dedicated endpoint

### Changed

- Narrative and evidence update flows enforce markdown quality checks before push/upsert
- Agent prompts require auditor-ready markdown (lists/tables/code/links)
- Source tagging normalized to `cli` across write paths

### Removed

- Markdown image usage from narrative/evidence authoring contract (temporarily)

## 0.5.4 - 2026-03-05

### Added

- `pretorin narrative get` to read current control narratives
- `pretorin notes list` and `pretorin notes add` for control-note management
- `pretorin evidence search` for platform evidence visibility
- `pretorin evidence upsert` for find-or-create evidence with control linking
- Shared compliance workflow helpers (system resolution, evidence dedupe/upsert, TODO blocks, gap notes)
- MCP `pretorin_get_control_notes` tool

### Changed

- `pretorin_create_evidence` now upserts by default (`dedupe: true`)
- `pretorin evidence push` uses find-or-create upsert logic
- Agent skill prompts include no-hallucination guidance and gap note format

### Removed

- Automatic control status updates from CLI evidence push workflow

## 0.5.3 - 2026-03-02

### Fixed

- CI lint failure formatting
- CLI model key precedence: `OPENAI_API_KEY` → `config.api_key` → `config.openai_api_key`

## 0.5.2 - 2026-02-27

### Fixed

- Rich markup `MarkupError` crash in login flow
- Evidence type mismatch (`documentation` → `policy_document`)
- CMMC control ID casing preserved (no longer incorrectly lowercased)
- `monitoring push` checks active context before requiring `--system`
- `pretorin login` skips prompt when already authenticated
- Demo script `--json` flag position and stdin handling

### Changed

- Default evidence type changed to `policy_document`
- Valid evidence types aligned with API
- Added `.pretorin/` and `evidence/` to `.gitignore`

## 0.5.0 - 2026-02-27

### Added

- Context management (`context list/set/show/clear`)
- Evidence commands (`evidence create/list/push/search/upsert`)
- Narrative push (`narrative push`)
- Monitoring events (`monitoring push`)
- Codex agent runtime (`agent run` with skills, `agent doctor/install/version/skills`)
- Agent MCP management (`agent mcp-list/mcp-add/mcp-remove`)
- Code review (`review run/status`)
- 14 new MCP tools for system, evidence, narrative, monitoring, notes, and control operations
- Control ID normalization (zero-padding)
- Interactive demo walkthrough script
- Beta messaging across CLI, MCP, and README

### Changed

- Platform API base URL changed to `/api/v1/public`
- Evidence and linking scoped to system
- `update_control_status()` changed from PATCH to POST

### Removed

- `pretorin narrative generate` — use `pretorin agent run --skill narrative-generation`
- `pretorin_generate_narrative` MCP tool

### Security

- MCP mutation handler parameter validation
- Client-side enum validation
- Path traversal protection in evidence writer
- TOML injection prevention in Codex config writer
- Connection error URL display

## 0.2.0 - 2026-02-06

### Added

- `--json` flag for machine-readable output
- `pretorin frameworks family/metadata/submit-artifact` commands
- Full AI Guidance rendering on control detail view
- `.mcp.json` for Claude Code auto-discovery
- Usage examples in command docstrings

### Changed

- Control references shown by default (replaced `--references` with `--brief`)
- Default controls limit changed to 0 (show all)

## 0.1.0 - 2025-02-03

### Added

- Initial public release
- CLI commands for browsing compliance frameworks
- Authentication commands (login, logout, whoami)
- Configuration management
- MCP server with 7 tools and analysis resources
- Self-update functionality
- Rich terminal output with Rome-bot mascot
- Docker support
- GitHub Actions CI/CD
- Integration test suite

### Supported Frameworks

- NIST SP 800-53 Rev 5
- NIST SP 800-171 Rev 2/3
- FedRAMP (Low, Moderate, High)
- CMMC Level 1, 2, and 3