Pretorin Developer & Agent Docs

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

Pretorin gives developers and AI agents direct access to compliance data, implementation context, and evidence workflows. The primary surfaces are the CLI, the MCP server, and skill-driven agent workflows. It supports 30+ compliance frameworks and profiles, including NIST 800-53, NIST 800-171, FedRAMP, and CMMC.

The CLI and MCP tooling in this repository are open source under Apache-2.0. Access to Pretorin-hosted platform services, APIs, and account-scoped data is authenticated and governed separately by the applicable platform terms.

Start Here

Choose the path that matches how you work:

• CLI-first — Use the Pretorin CLI directly for framework browsing, evidence workflows, reviews, scans, and agent execution.
• AI-agent-first — Connect pretorin mcp-serve to Claude Code, Codex CLI, Cursor, or another MCP-compatible tool.
• Hosted agent runtime — Use pretorin agent run when you want Pretorin-managed model execution with built-in skills.

Start with Installation, Authentication, and Quick Start if this is your first time here.

Core Paths

Pretorin is usually used in one of these modes:

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.

3. Direct CLI mode — Use pretorin subcommands directly for browsing frameworks, managing context, authoring evidence, updating narratives, and running scans.

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
• Browse STIGs and CCIs — Look up STIG benchmarks, rules, and trace CCIs through the full control hierarchy
• Manage vendors — Track third-party vendors, link evidence to vendor assessments, and upload vendor documents
• Complete policy and scope questionnaires — Answer org-policy and scope questions through a guided workflow with AI-assisted generation and review

Recommended Sections

• Quick Start for first commands and setup
• MCP Integration for Claude, Codex, Cursor, and other agent tools
• Agent Overview for Pretorin-hosted runtime usage
• CLI Reference for command-level detail
• Workflows for end-to-end compliance tasks

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

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

All hosted API access is account-scoped and authenticated. Access to Pretorin-hosted services and any returned account-scoped data is governed by the applicable platform terms in addition to the open-source license for this repository.

Login

pretorin login

Options:

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. To re-authenticate with a different key, pass it explicitly:

pretorin login --api-key <new-key>

If you log into a different API endpoint or switch API keys, Pretorin clears the stored active system + framework context so stale scope does not bleed into the new environment.

Verify Authentication

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

For machine-readable output, use the global --json flag:

pretorin --json whoami

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

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 \
  --description "Role-based access control in Azure AD" \
  --type configuration \
  --name "RBAC Configuration"

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

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

# Install the skill (teaches your agent how to use Pretorin tools)
pretorin skill install

# Add the MCP server (Claude Code example)
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?"

Check install status with pretorin skill status. See the MCP Setup Guides for other tools.

Browse STIGs and CCIs

Look up STIG benchmarks, rules, and CCI traceability:

# List available STIG benchmarks
pretorin stig list

# View STIG benchmark details
pretorin stig show <stig_id>

# Trace a CCI to its parent controls
pretorin cci chain <cci-id>

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: 30+ framework(s)

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

The exact total and available framework set can vary as the platform catalog expands. Use pretorin frameworks list to see the live catalog available to your account.

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

Brief Mode

By default, the full control is shown including statement, guidance, and references. Use --brief to show only the basic info panel:

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

The default (no flag) includes:

• 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

# Skip automatic source verification after setting context
pretorin context set --system "My Application" --framework nist-800-53-r5 --no-verify

Pretorin stores the canonical system ID for stability and also caches the last known system name for display. After setting context, source verification runs automatically unless --no-verify is passed. If you change API keys or platform endpoints with pretorin login, the stored active context is cleared automatically so old scope does not leak into the new environment.

Show Current Context

$ pretorin context show
╭──────────────────────── Active Context ─────────────────────────╮
│ System: My Application (sys-1234...)                           │
│ Framework: nist-800-53-r5                                      │
│ Progress: 42%                                                  │
│ Status: in_progress                                            │
╰─────────────────────────────────────────────────────────────────╯

# Compact summary for shell use
pretorin context show --quiet

# Fail fast if the stored context is missing, stale, or cannot be verified
pretorin context show --quiet --check

context show validates the stored system and framework against the platform when credentials are available. If the system has been deleted or the framework is no longer attached, the command reports that state explicitly instead of silently showing a stale context.

Verify Context

Verify the active context against source attestation:

# Full output
pretorin context verify

# Compact output with custom TTL
pretorin context verify --ttl 7200 --quiet

Source Manifest

Show the resolved source manifest and evaluate it against detected sources:

pretorin context manifest
pretorin context manifest --quiet

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" \
  --type configuration

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

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

List Local Evidence

# List all local evidence
pretorin evidence list

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

Push Evidence to Platform

pretorin evidence push

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

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

Search Platform Evidence

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

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

Upload Evidence File

Upload a file directly as evidence:

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

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

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

Upsert Evidence

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

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

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

Code Context Options

When upserting evidence, you can attach source code context:

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

Link Evidence to a Control

Link an existing platform evidence item to a control:

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

Options:

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

Delete Evidence

# Delete with confirmation prompt
pretorin evidence delete ev-abc123

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

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

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

Evidence Types

Valid evidence types:

AI-Drift Normalization

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

Markdown Quality Requirements

Evidence descriptions must be auditor-ready markdown:

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

These requirements are validated before push/upsert operations.

Narrative Commands

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

Create Local Narrative

pretorin narrative create ac-02 fedramp-moderate \
  -c "- RBAC enforced via IdP\n\n\`\`\`yaml\nroles:\n  admin: ...\n\`\`\`"

Creates a local markdown file at narratives/<framework>/<control>/<slug>.md with YAML frontmatter. Markdown is validated at create time (same rules as push).

Options:

• --content / -c — Narrative content (required)
• --name / -n — Custom name (defaults to <control>-<framework>)
• --ai-generated — Mark the narrative as AI-generated

List Local Narratives

pretorin narrative list
pretorin narrative list --framework fedramp-moderate

Displays a table of local narrative files: Control, Framework, Name, AI Generated, Synced.

Push Narratives

pretorin narrative push --dry-run
pretorin narrative push

Batch-pushes all unsynced local narratives to the platform. After a successful push, the local file’s platform_synced frontmatter is set to true.

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 Single File (Legacy)

pretorin narrative push-file 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 at create time and 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:

• Treat existing Pretorin narratives, notes, and status fields as a starting point, not proof that a control gap exists.
• Before writing a narrative update or gap note, inspect the relevant implementation in the workspace and connected systems.
• If observed implementation is stronger than the current platform record, update the narrative to match the observed implementation and record any remaining evidence gap separately.

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

Create Local Note

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

Creates a local markdown file at notes/<framework>/<control>/<slug>.md with YAML frontmatter. No markdown validation is applied to notes.

Options:

• --content / -c — Note content (required)
• --name / -n — Custom name (defaults to content summary)

Push Notes

pretorin notes push --dry-run
pretorin notes push

Batch-pushes all unsynced local notes to the platform. Notes are append-only on the platform. After a successful push, the local file’s platform_synced frontmatter is set to true.

List Local Notes

pretorin notes list --local
pretorin notes list --local --framework fedramp-moderate

Use the --local flag to list local note files instead of platform notes.

List Platform Notes

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

Add a Note (Direct to Platform)

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

pretorin notes add ac-02 fedramp-moderate \
  --content "MFA verified" --system "My System"

Options:

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

Resolve or Reopen a Note

# Resolve a note
pretorin notes resolve ac-02 fedramp-moderate <note_id>

# Resolve with updated content
pretorin notes resolve ac-02 fedramp-moderate <note_id> --content "Resolved: SSO config verified."

# Reopen a resolved note
pretorin notes resolve ac-02 fedramp-moderate <note_id> --reopen

Options:

• --system / -s — System name or ID
• --reopen — Reopen a resolved note instead of resolving it
• --content / -c — Optional updated note content
• --pinned — Optional pinned state

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

Severity Levels

Options

Context Requirement

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

Campaign Workflows

The campaign command group runs bulk compliance operations across multiple controls, policies, or scope questions in a single coordinated run. Campaigns support an external-agent-first pattern with checkpoint persistence and lease-based concurrency for safe fan-out to multiple agents.

Campaign Domains and Modes

Control Campaigns

Draft New Narratives for a Family

pretorin campaign controls --mode initial --family AC \
  --system "My System" --framework-id fedramp-moderate

Fix Controls with Platform Notes

pretorin campaign controls --mode notes-fix --family AC

Fix Controls after Family Review

pretorin campaign controls --mode review-fix --family AC --review-job <job-id>

Options

Policy Campaigns

Answer All Incomplete Policy Questions

pretorin campaign policy --mode answer --all-incomplete

Fix Policy Review Findings

pretorin campaign policy --mode review-fix --policies <policy-id>

Options

Scope Campaigns

Answer Scope Questions

pretorin campaign scope --mode answer \
  --system "My System" --framework-id fedramp-moderate

Options

Checking Campaign Status

pretorin campaign status --checkpoint .pretorin/campaign-checkpoint.json

Campaign Lifecycle

1. Prepare — The campaign snapshots platform state and creates a local checkpoint file
2. Claim — Items are claimed with TTL-based leases (safe for multiple agents)
3. Draft — Each item gets full context and drafting instructions
4. Propose — Proposals are submitted without writing to the platform
5. Apply — All accepted proposals are pushed to the platform in one operation

Use --apply to automatically apply after completion, or run campaign status to review before applying.

Vendor Management

The vendor command group manages vendor entities and their evidence documents. Vendors represent external providers (CSPs, SaaS, managed services) or internal teams whose controls your system inherits.

List Vendors

pretorin vendor list

Create a Vendor

pretorin vendor create "AWS" --type csp --description "Primary cloud provider" \
  --authorization-level "FedRAMP High P-ATO"

Vendor Types

Get Vendor Details

pretorin vendor get <vendor_id>

Update a Vendor

pretorin vendor update <vendor_id> --name "AWS GovCloud" --authorization-level "FedRAMP High"

Delete a Vendor

pretorin vendor delete <vendor_id>
pretorin vendor delete <vendor_id> --force  # skip confirmation

Upload Vendor Documents

Upload SOC 2 reports, Customer Responsibility Matrices (CRMs), FedRAMP packages, or other vendor evidence:

pretorin vendor upload-doc <vendor_id> ./aws-soc2-report.pdf \
  --name "AWS SOC 2 Type II" \
  --description "Annual SOC 2 report covering 2025" \
  --attestation-type third_party_attestation

Attestation Types

List Vendor Documents

pretorin vendor list-docs <vendor_id>

Related: Control Inheritance

Once vendors are created and documents uploaded, use the MCP tools or platform to set control responsibility edges:

• pretorin_set_control_responsibility — Mark controls as inherited/shared
• pretorin_generate_inheritance_narrative — AI-draft inheritance narratives from vendor docs
• pretorin_get_stale_edges / pretorin_sync_stale_edges — Monitor and sync inheritance

STIG & CCI Browsing

The stig and cci command groups let you browse STIG benchmarks, rules, and CCIs with full traceability from NIST 800-53 controls down to individual STIG check rules.

STIG Commands

List STIG Benchmarks

pretorin stig list
pretorin stig list --technology-area "Network"
pretorin stig list --product "Windows" --limit 10

Show STIG Details

pretorin stig show <stig_id>

Shows benchmark metadata including title, version, release info, and severity breakdown of rules.

List Rules for a STIG

pretorin stig rules <stig_id>
pretorin stig rules <stig_id> --severity cat_i
pretorin stig rules <stig_id> --cci CCI-000015 --limit 20

Show Applicable STIGs

# Uses active system context
pretorin stig applicable

# Explicit system
pretorin stig applicable --system "My System"

AI-Infer Applicable STIGs

pretorin stig infer
pretorin stig infer --system "My System"

Uses the system’s profile to recommend which STIG benchmarks should apply.

CCI Commands

CCIs (Control Correlation Identifiers) bridge NIST 800-53 controls to specific STIG rules via SRGs (Security Requirements Guides).

List CCIs

pretorin cci list
pretorin cci list --control ac-2
pretorin cci list --status draft --limit 50

Show CCI Details

pretorin cci show CCI-000015

Shows the CCI definition, linked SRGs, and linked STIG rules.

Full Traceability Chain

pretorin cci chain ac-2
pretorin cci chain ac-2 --system "My System"

Shows the complete chain: NIST 800-53 Control -> CCIs -> SRGs -> STIG rules (and test results when --system is provided).

This is useful for understanding exactly which technical checks validate a given control requirement.

STIG Scanning

The scan command group runs STIG compliance scans using available scanner tools and manages test results.

Check Scanner Availability

pretorin scan doctor

Lists which scanner tools are installed and available on your system:

View Test Manifest

# Uses active system context
pretorin scan manifest

# Filter by STIG
pretorin scan manifest --system "My System" --stig <stig_id>

Shows which STIGs and rules are applicable to the system and which scanners can test them.

Run Scans

# Run all applicable scans
pretorin scan run

# Target a specific STIG
pretorin scan run --stig <stig_id>

# Use a specific scanner
pretorin scan run --tool openscap

# Dry run (show what would execute)
pretorin scan run --dry-run

The scan orchestrator automatically detects available scanners, assigns rules to capable tools, and collects results.

Options

View Results

# All results for active system
pretorin scan results

# Filter by control
pretorin scan results --system "My System" --control ac-2

Shows CCI-level test results including pass/fail status, scanner used, and timestamp.

Workflow

1. pretorin scan doctor — Verify scanner tools are installed
2. pretorin scan manifest — Review what will be tested
3. pretorin scan run --dry-run — Preview the test plan
4. pretorin scan run — Execute scans
5. pretorin scan results — Review results

Results are automatically submitted to the platform when a system context is active.

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 --system "My System" --path ./src

# Local-only mode — saves control context as markdown, no system required
pretorin review run --control-id ac-02 --framework-id fedramp-moderate --local

# Custom output directory for local artifacts
pretorin review run --control-id ac-02 --framework-id fedramp-moderate --local --output-dir ./compliance-notes

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.

Options

Check Implementation Status

pretorin review status --control-id ac-02
pretorin review status --control-id sc-07 --framework-id fedramp-moderate --system my-system

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",
  "platform_api_base_url": "https://platform.pretorin.com/api/v1/public",
  "model_api_base_url": "https://platform.pretorin.com/api/v1/public/model",
  "active_system_id": "sys-abc123",
  "active_system_name": "My Application",
  "active_framework_id": "nist-800-53-r5",
  "disable_update_check": false
}

Configuration Keys

Environment Variable Overrides

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

Complete Command Reference

Global Options

Root Commands

Framework Commands

Context Commands

Control Commands

Evidence Commands

Narrative Commands

Notes Commands

Monitoring Commands

Policy Commands

Scope Commands

Agent Commands

Skill Commands

Review Commands

Config Commands

Campaign Commands

Campaign Modes

Vendor Commands

Vendor Types

csp, saas, managed_service, internal

STIG Commands

CCI Commands

Scan Commands

Supported Scanners

OpenSCAP, InSpec, AWS Cloud Scanner, Azure Cloud Scanner, Manual

Deprecated Commands

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

Before running write-heavy MCP workflows from a shell or GUI wrapper, prefer validating the stored scope with:

pretorin context show --quiet --check

Tool Categories

The 87 MCP tools are organized into categories:

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

Install the Pretorin Skill

The skill teaches your AI agent how to use MCP tools for compliance workflows — control ID formats, narrative authoring rules, gap analysis methodology, and more. Install it before setting up MCP:

pretorin skill install                # both Claude Code and Codex CLI
pretorin skill install --agent claude # Claude Code only
pretorin skill install --agent codex  # Codex CLI only
pretorin skill status                 # check what's installed

The skill is copied to ~/.claude/skills/pretorin/ and/or ~/.codex/skills/pretorin/ and auto-discovered by each agent.

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.

Before debugging scoped MCP write failures, validate the active CLI scope:

pretorin context show --quiet --check

MCP Tool Reference

The MCP server provides 87 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_controls_batch

Get detailed control data for many controls in one framework-scoped request.

Parameters:

• framework_id (required)
• control_ids (optional) — List of canonical control IDs; omit to retrieve all controls in the framework

Returns: Full control detail records for the requested controls.

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_cli_status

Return the local Pretorin CLI version status, including update availability and upgrade guidance for MCP hosts and agents.

Parameters:

• force (optional) — Bypass local cache and re-check PyPI for the latest version. Default: false

Returns: Current version, latest version, update available flag, and upgrade instructions.

pretorin_get_source_manifest

Get the resolved source manifest for a system and evaluate it against currently detected sources. Shows which external sources (git, cloud, HRIS, etc.) are required, recommended, or optional, and whether each is currently satisfied.

Parameters:

• system_id (optional) — System ID or name

Returns: Source manifest with per-source satisfaction status. Returns null manifest if none is configured.

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) — System ID or friendly system name

Returns: Framework status summaries and progress metrics.

Evidence Management

pretorin_search_evidence

Search current evidence items.

Parameters:

• system_id (optional) — System ID or friendly system name. When omitted, the active CLI scope is used if available.
• control_id (optional) — Filter by control
• framework_id (optional) — Filter by framework
• limit (optional) — Maximum number of results. Default: 20

Returns: Matching evidence items. The server uses the same compatibility search path as the CLI for deployments that only expose system-scoped evidence routes.

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:

• name (required)
• description (required) — Must be auditor-ready markdown (no headings, at least one rich element, no images)
• evidence_type (required) — Must be one of the canonical evidence types
• system_id (optional) — Defaults to active scope
• 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_create_evidence_batch

Create and link multiple evidence items within one system/framework scope in a single request.

Parameters:

• items (required) — Array of evidence payloads with name, description, and control_id; may also include evidence_type and relevance_notes
• system_id (optional) — Defaults to active scope
• framework_id (optional) — Defaults to active scope

Returns: Batch creation summary with per-item results and created evidence IDs.

pretorin_link_evidence

Link an existing evidence item to a control.

Parameters:

• evidence_id (required)
• control_id (required)
• system_id (optional) — Defaults to active scope
• framework_id (optional)

Returns: Link confirmation.

pretorin_upload_evidence

Upload a file as evidence to the platform (system-scoped, requires WRITE access).

Parameters:

• file_path (required) — Absolute path to the file to upload
• name (required) — Evidence name
• system_id (optional) — Defaults to active scope
• evidence_type (optional) — Default: other
• description (optional) — Evidence description
• control_id (optional)
• framework_id (optional)

Returns: Uploaded evidence record.

pretorin_delete_evidence

Delete an evidence item from the platform (system-scoped, requires WRITE access).

Parameters:

• evidence_id (required) — The evidence item ID to delete
• system_id (optional) — Defaults to active scope
• framework_id (optional) — Defaults to active scope

Returns: Deletion confirmation.

pretorin_get_narrative

Get the current narrative record for a control.

Parameters:

• control_id (required)
• system_id (optional) — Defaults to active scope
• framework_id (optional) — Defaults to active scope

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:

• control_id (required)
• system_id (optional) — Defaults to active scope
• framework_id (optional) — Defaults to active scope

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)
• framework_id (required)

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

pretorin_patch_scope_qa

Apply partial scope questionnaire updates for a system/framework.

Parameters:

• system_id (required)
• framework_id (required)
• updates (required) — Non-empty list of {question_id, answer} objects

Returns: Updated scope questionnaire state, including the saved responses.

pretorin_list_org_policies

List organization policies available for questionnaire work.

Parameters: None

Returns: Policy summaries including id, name, template linkage, and questionnaire status.

pretorin_get_org_policy_questionnaire

Get the canonical questionnaire state for one organization policy.

Parameters:

• policy_id (required)

Returns: Policy metadata, saved answers, and the merged template/question set when available.

pretorin_patch_org_policy_qa

Apply partial questionnaire updates for one organization policy.

Parameters:

• policy_id (required)
• updates (required) — Non-empty list of {question_id, answer} objects

Returns: Updated organization policy questionnaire state.

pretorin_get_control_implementation

Get implementation details for a control in a system.

Parameters:

• control_id (required)
• system_id (optional) — Defaults to active scope
• framework_id (optional) — Defaults to active scope

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

pretorin_get_control_notes

Get notes for a control implementation.

Parameters:

• control_id (required)
• system_id (optional) — Defaults to active scope
• framework_id (optional)

Returns: Note list with total count.

pretorin_update_narrative

Push a narrative text update for a control implementation.

Parameters:

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

Returns: Update confirmation.

pretorin_add_control_note

Add a note for unresolved gaps or manual follow-up actions. Content is plain text (no markdown validation required).

Parameters:

• control_id (required)
• content (required)
• system_id (optional) — Defaults to active scope
• framework_id (optional) — Defaults to active scope

Returns: The created note record.

pretorin_resolve_control_note

Resolve, unresolve, or update an existing control note. Use this to clear blocking notes so control status can advance.

Parameters:

• control_id (required)
• note_id (required)
• system_id (optional) — Defaults to active scope
• framework_id (optional) — Defaults to active scope
• is_resolved (optional) — Default: true
• content (optional) — Updated note content
• is_pinned (optional)

Returns: The updated note record.

Compliance Updates

pretorin_update_control_status

Update the implementation status for a control.

Parameters:

• control_id (required)
• status (required) — implemented, in_progress, inherited, not_applicable, not_started, partially_implemented, planned, ready_to_approve
• system_id (optional) — Defaults to active scope
• framework_id (optional)

Returns: Status update confirmation.

pretorin_push_monitoring_event

Create a monitoring event for a system.

Parameters:

• title (required)
• system_id (optional) — Defaults to active scope
• framework_id (optional) — Defaults to active scope
• severity (optional) — critical, high, medium, low, info. Default: medium
• event_type (optional) — security_scan, configuration_change, access_review, compliance_check. Default: security_scan
• 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.

Workflow State & Analytics

pretorin_get_workflow_state

Get the lifecycle state for a system+framework, showing which stage needs work next (scope, policies, controls, evidence).

Parameters:

• system_id (required)
• framework_id (required)

Returns: Current workflow stage, completion percentages, and next recommended action.

pretorin_get_analytics_summary

Get a lightweight system progress snapshot.

Parameters:

• system_id (required)
• framework_id (required)

Returns: Scope completion, policy completion, control coverage, and evidence gaps.

pretorin_get_family_analytics

Get per-family breakdown with narrative coverage, evidence coverage, and status distribution.

Parameters:

• system_id (required)
• framework_id (required)

Returns: Per-family metrics.

pretorin_get_policy_analytics

Get per-policy breakdown with answer completion and review status.

Parameters:

• policy_id (required)

Returns: Per-policy completion metrics.

Family Operations

pretorin_get_pending_families

Identify which control families need work.

Parameters:

• system_id (required)
• framework_id (required)

Returns: Families with counts of pending vs total controls.

pretorin_get_family_bundle

Get all controls in one family with status, narrative presence, evidence presence, and note counts.

Parameters:

• system_id (required)
• family_id (required)
• framework_id (required)

Returns: Complete family bundle with per-control details.

pretorin_trigger_family_review

Trigger AI review of all controls in a family. Takes 2-4 minutes for large families.

Parameters:

• system_id (required)
• family_id (required)
• framework_id (required)

Returns: Review job ID for polling.

pretorin_get_family_review_results

Poll family review results.

Parameters:

• system_id (required)
• job_id (required)

Returns: Aggregated findings with severity, affected control IDs, and recommended fixes.

Scope Workflow

pretorin_get_pending_scope_questions

Get only unanswered scope questions (lightweight).

Parameters:

• system_id (required)
• framework_id (required)

Returns: List of unanswered questions with IDs.

pretorin_get_scope_question_detail

Get guidance, tips, and example responses for a specific scope question.

Parameters:

• system_id (required)
• question_id (required)
• framework_id (required)

Returns: Question text, guidance, tips, and example answers.

pretorin_answer_scope_question

Answer one scope question.

Parameters:

• system_id (required)
• question_id (required)
• answer (required)
• framework_id (required)

Returns: Updated question state.

pretorin_trigger_scope_generation

Trigger AI generation of scope document from answered questions.

Parameters:

• system_id (required)
• framework_id (required)

Returns: Generation job ID for polling.

pretorin_trigger_scope_review

Trigger AI review of scope answers.

Parameters:

• system_id (required)
• framework_id (required)

Returns: Review job ID for polling.

pretorin_get_scope_review_results

Poll for structured scope review findings.

Parameters:

• system_id (required)
• job_id (required)

Returns: Findings with severity levels and recommended fixes.

Policy Workflow

pretorin_get_pending_policy_questions

Get only unanswered policy questions.

Parameters:

• policy_id (required)

Returns: List of unanswered questions.

pretorin_get_policy_question_detail

Get guidance, tips, and examples for a specific policy question.

Parameters:

• policy_id (required)
• question_id (required)

Returns: Question text, guidance, and example answers.

pretorin_answer_policy_question

Answer one policy question.

Parameters:

• policy_id (required)
• question_id (required)
• answer (required)

Returns: Updated question state.

pretorin_get_policy_workflow_state

Get per-policy workflow state including completion, generation, and review status.

Parameters:

• policy_id (required)

Returns: Policy workflow state.

pretorin_trigger_policy_generation

Trigger AI generation of policy document from answered questions.

Parameters:

• policy_id (required)
• system_id (optional) — System ID for scope context

Returns: Generation job status.

pretorin_trigger_policy_review

Trigger AI review of policy answers/document.

Parameters:

• policy_id (required)

Returns: Review job ID for polling.

pretorin_get_policy_review_results

Poll for structured policy review findings.

Parameters:

• policy_id (required)
• job_id (required)

Returns: Findings with severity levels and recommended fixes.

Campaign Operations

Campaigns enable bulk compliance operations with checkpoint persistence and lease-based concurrency.

pretorin_prepare_campaign

Prepare a workflow-aligned campaign run with a platform state snapshot.

Parameters:

• domain (required) — controls, policy, or scope
• mode (required) — Campaign mode for the selected domain
• system_id (optional) — Defaults to active scope
• framework_id (optional) — Defaults to active scope
• family_id (optional) — Target family for control campaigns
• control_ids (optional) — Explicit control IDs to include
• all_controls (optional) — Include all controls. Default: false
• artifacts (optional) — Artifact type: narratives, evidence, or both. Default: both
• review_job (optional) — Family review job ID for review-fix mode
• policy_ids (optional) — Explicit policy IDs to include
• all_incomplete (optional) — Include all incomplete items. Default: false
• apply (optional) — Apply proposals immediately. Default: false
• output (optional) — Output format: auto, live, compact, json. Default: json
• checkpoint_path (optional) — Local checkpoint file path
• working_directory (optional) — Working directory for executors
• concurrency (optional) — Parallel execution limit. Default: 4
• max_retries (optional) — Retry limit per item. Default: 2

Returns: Campaign checkpoint with item list and metadata.

pretorin_claim_campaign_items

Claim items for drafting with TTL-based leases. Safe for fan-out to multiple agents.

Parameters:

• checkpoint_path (required) — Local campaign checkpoint path
• lease_owner (optional) — Stable identifier for the claiming agent
• max_items (optional) — Number of items to claim. Default: 1
• lease_ttl_seconds (optional) — Lease time-to-live. Default: 300

Returns: Claimed items with lease metadata.

pretorin_get_campaign_item_context

Get full item context plus drafting instructions for a claimed item.

Parameters:

• checkpoint_path (required)
• item_id (required)

Returns: Control/policy/scope context, current state, and drafting guidance.

pretorin_submit_campaign_proposal

Submit an external agent’s proposal without applying it to the platform.

Parameters:

• checkpoint_path (required)
• item_id (required)
• proposal (required) — Campaign proposal payload object

Returns: Proposal acceptance confirmation.

pretorin_apply_campaign

Push stored proposals to the platform.

Parameters:

• checkpoint_path (required)
• item_ids (optional) — Subset of item IDs to apply; omit to apply all

Returns: Apply results with per-item status.

pretorin_get_campaign_status

Get structured campaign status with a stable transcript snapshot.

Parameters:

• checkpoint_path (required)

Returns: Campaign progress, item states, and transcript.

Vendor Management

pretorin_list_vendors

List all vendor entities in the organization.

Parameters: None

Returns: Vendor list with IDs, names, types, and authorization levels.

pretorin_create_vendor

Create a new vendor entity.

Parameters:

• name (required)
• provider_type (required) — csp, saas, managed_service, internal
• description (optional)
• authorization_level (optional)

Returns: Created vendor record.

pretorin_get_vendor

Get vendor details.

Parameters:

• vendor_id (required)

Returns: Vendor metadata and linked documents.

pretorin_update_vendor

Update vendor fields.

Parameters:

• vendor_id (required)
• name (optional)
• description (optional)
• provider_type (optional) — csp, saas, managed_service, internal
• authorization_level (optional)

Returns: Updated vendor record.

pretorin_delete_vendor

Delete a vendor entity.

Parameters:

• vendor_id (required)

Returns: Deletion confirmation.

pretorin_upload_vendor_document

Upload vendor evidence documents (SOC 2 reports, CRMs, FedRAMP packages).

Parameters:

• vendor_id (required)
• file_path (required)
• name (optional)
• description (optional)
• attestation_type (optional) — self_attested, third_party_attestation, vendor_provided. Default: vendor_provided

Returns: Uploaded document record.

pretorin_list_vendor_documents

List documents linked to a vendor.

Parameters:

• vendor_id (required)

Returns: Document list with metadata.

pretorin_link_evidence_to_vendor

Link an evidence item to a vendor with attestation type. Set vendor_id to null to unlink.

Parameters:

• evidence_id (required)
• vendor_id (optional) — Vendor ID; null to unlink
• attestation_type (optional) — self_attested, third_party_attestation, vendor_provided

Returns: Link confirmation.

Inheritance & Responsibility

pretorin_set_control_responsibility

Create or update an inheritance edge for a control.

Parameters:

• system_id (required)
• control_id (required)
• framework_id (required)
• responsibility_mode (required) — inherited or shared
• source_type (optional) — provider, internal, or hybrid
• vendor_id (optional) — Vendor providing the inherited control

Returns: Created responsibility edge.

pretorin_get_control_responsibility

Check if a control is inherited and from where.

Parameters:

• system_id (required)
• control_id (required)
• framework_id (required)

Returns: Responsibility edge details or null.

pretorin_remove_control_responsibility

Convert an inherited control back to system-specific.

Parameters:

• system_id (required)
• control_id (required)
• framework_id (required)

Returns: Removal confirmation.

pretorin_generate_inheritance_narrative

AI-generate an inheritance narrative grounded in vendor documentation.

Parameters:

• system_id (required)
• control_id (required)
• framework_id (required)

Returns: Draft inheritance narrative text.

pretorin_get_stale_edges

Identify controls where the source narrative changed but the inherited control hasn’t been updated.

Parameters:

• system_id (required)

Returns: List of stale inheritance edges with source change timestamps.

pretorin_sync_stale_edges

Bulk update inherited controls by regenerating narratives from latest source.

Parameters:

• system_id (required)

Returns: Sync results with per-control status.

STIG & CCI

pretorin_list_stigs

List STIG benchmarks with optional filters.

Parameters:

• technology_area (optional) — Filter by technology area
• product (optional) — Filter by product name
• limit (optional) — Default: 100
• offset (optional) — Pagination offset. Default: 0

Returns: STIG benchmark list with IDs, titles, and rule counts.

pretorin_get_stig

Get STIG benchmark detail.

Parameters:

• stig_id (required)

Returns: Benchmark metadata including title, version, release info, and severity breakdown.

pretorin_list_stig_rules

List rules for a STIG benchmark.

Parameters:

• stig_id (required)
• severity (optional) — Filter by severity (high, medium, low)
• cci_id (optional) — Filter by CCI identifier
• limit (optional) — Default: 100
• offset (optional) — Pagination offset. Default: 0

Returns: Rule list with IDs, titles, severities, and linked CCIs.

pretorin_get_stig_rule

Get full STIG rule detail.

Parameters:

• stig_id (required)
• rule_id (required)

Returns: Check text, fix text, discussion, and linked CCIs.

pretorin_list_ccis

List CCIs with optional filters.

Parameters:

• nist_control_id (optional) — Filter by NIST 800-53 control ID (e.g., AC-2)
• status (optional)
• limit (optional) — Default: 100
• offset (optional) — Pagination offset. Default: 0

Returns: CCI list with definitions and linked controls.

pretorin_get_cci

Get CCI detail with linked SRGs and STIG rules.

Parameters:

• cci_id (required) — e.g., CCI-000015

Returns: CCI definition, linked SRGs, and linked STIG rules.

pretorin_get_cci_chain

Get the full traceability chain: Control -> CCIs -> SRGs -> STIG rules.

Parameters:

• nist_control_id (required) — NIST 800-53 control ID (e.g., AC-2)

Returns: Complete traceability from control requirements to technical checks.

pretorin_get_cci_status

Get CCI-level compliance rollup for a system.

Parameters:

• system_id (required)
• nist_control_id (optional) — Filter by NIST control ID (e.g., AC-2)

Returns: Per-CCI pass/fail status.

pretorin_get_stig_applicability

Get which STIGs apply to a system based on its profile.

Parameters:

• system_id (required)

Returns: List of applicable STIG benchmarks.

pretorin_infer_stigs

AI-infer applicable STIGs from the system’s profile.

Parameters:

• system_id (required)

Returns: Recommended STIG benchmarks with reasoning.

pretorin_get_test_manifest

Fetch the test manifest (applicable STIGs + rules) for a system.

Parameters:

• system_id (required)
• stig_id (optional) — Scope manifest to a specific STIG benchmark

Returns: Test manifest with applicable rules and scanner assignments.

pretorin_submit_test_results

Upload STIG scan results to the platform.

Parameters:

• system_id (required)
• cli_run_id (required) — CLI scan run identifier
• results (required) — Array of test result objects
• cli_version (optional) — CLI version string

Returns: Submission confirmation with per-result status.

MCP Resources

The MCP server exposes read-only resources across three URI schemes: analysis://, status://, and workflow://.

Available Resources

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.

CLI Status

status://cli

Returns the current CLI version, latest available version, whether an update is available, passive notification status, check state (verified/unverified), and the upgrade command. MCP hosts can inspect this resource to surface update guidance.

Workflow Recipes

workflow://recipe/{recipe_id}

Returns a step-by-step workflow recipe for common compliance tasks. Available recipes are listed dynamically via the MCP list_resources method.

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
   

4. If the MCP client can talk to Pretorin but scoped write tools behave strangely, validate the stored CLI context:

   pretorin context show --quiet --check
   

   This catches deleted systems, detached frameworks, and other stale local scope before you debug the MCP client itself.

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

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

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/api/v1/public/model

# 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 Codex agent resolves API keys in this order:

1. config.api_key (from pretorin login) — used as bearer key for the platform model proxy
2. OPENAI_API_KEY environment variable
3. config.openai_api_key

When --base-url is explicitly provided (non-platform endpoint), the order changes to prefer OPENAI_API_KEY first, then falls back to config keys.

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

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"

# STIG scan
pretorin agent run --skill stig-scan "Check STIG applicability for my system"

# CCI assessment
pretorin agent run --skill cci-assessment "Assess CCI compliance for AC-02"

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
• Pushes monitoring events for critical or high-severity findings
• Produces remediation recommendations

STIG Scan

Runs STIG compliance scans against a system:

• Checks which STIGs apply to the system (applicability)
• Gets the test manifest (rules to evaluate)
• Reports available scanners and rule coverage
• Summarizes the scan plan and gaps in automated coverage

CCI Assessment

Assesses CCI-level compliance for a specific control:

• Gets control context and implementation status
• Lists CCIs for the target control
• Checks CCI-level test results (pass/fail/not tested)
• Identifies CCIs with no test coverage
• Presents results as a traceability chain: Control -> CCIs -> SRGs -> STIG rules

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

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

# http transport
pretorin agent mcp-add <name> http <url>

Options:

Examples:

pretorin agent mcp-add github stdio uvx --arg mcp-server-github
pretorin agent mcp-add aws http https://mcp.example.com/aws
pretorin agent mcp-add tools stdio node --arg /path/to/server --scope global

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 30+ compliance frameworks and profiles spanning federal, contractor, defense industrial base, and related compliance requirements.

Representative Frameworks

The table below highlights a representative subset of commonly used frameworks in Pretorin. Always call pretorin frameworks list to get the current catalog from the API for your environment.

Framework Tiers

Each framework has a tier classification displayed in the pretorin frameworks list output:

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:

Target audience: Cloud service providers to government

CMMC 2.0

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

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:

Control IDs

Control IDs are zero-padded with a hyphen:

Enhancement IDs append a dot-suffix or parenthetical suffix:

CMMC 2.0

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

Family IDs

CMMC family IDs include a level suffix:

Control IDs

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

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:

Control IDs

Control IDs use dotted notation with leading zeros:

Auto-Normalization

The CLI and MCP tools automatically normalize NIST 800-53 and FedRAMP control IDs: uppercase is lowered and single-digit numbers are zero-padded. For example, AC-2 becomes ac-02 and SC-7.1 becomes sc-07.1. CMMC and NIST 800-171 IDs are passed through unchanged — use the exact format shown above.

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

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.

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

Quick Reference

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.

Treat existing Pretorin narratives, notes, and status fields as a starting point, not proof that a control gap exists. Before writing a narrative update or gap note, inspect the relevant implementation in the workspace and connected systems. If those sources show stronger implementation than the current platform record, update the narrative to reflect the observed implementation and record any remaining evidence gap separately.

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 a single narrative file
pretorin narrative push-file 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.

Campaign Workflows

Campaigns are the recommended way to run bulk compliance operations across multiple controls, policies, or scope questions. They replace manual one-at-a-time updates with a coordinated prepare-claim-propose-apply lifecycle.

When to Use Campaigns

• Initial control implementation — Draft narratives and evidence for an entire control family
• Fixing review findings — Address issues flagged by family or policy reviews
• Answering questionnaires — Bulk-answer policy or scope questions
• Notes remediation — Fix controls flagged by platform notes

Campaign Lifecycle

Prepare → Claim → Draft → Propose → Apply

1. Prepare — Snapshot platform state and create a checkpoint file. This captures the current state of all target items so the campaign works from a consistent baseline.

2. Claim — Lease items for drafting. TTL-based leases prevent concurrent editing when multiple agents are working in parallel.

3. Draft — For each claimed item, get full context (control requirements, current state, guidance) and produce a draft.

4. Propose — Submit drafts as proposals without writing to the platform. This provides a review opportunity before any changes are persisted.

5. Apply — Push all accepted proposals to the platform as a single operation.

External Agent Pattern

Campaigns are designed for external agents (Claude Code, Codex, Cursor, etc.) operating through MCP:

Agent A: prepare_campaign → claim_campaign_items → get_campaign_item_context → submit_campaign_proposal
Agent B: claim_campaign_items → get_campaign_item_context → submit_campaign_proposal
...
Coordinator: get_campaign_status → apply_campaign

The checkpoint file enables independent agent execution. Agents can claim non-overlapping items and work in parallel.

CLI Usage

Control Campaign

# Draft narratives for the Access Control family
pretorin campaign controls --mode initial --family AC \
  --system "My System" --framework-id fedramp-moderate

# Fix controls flagged by notes
pretorin campaign controls --mode notes-fix --family AC \
  --system "My System" --framework-id fedramp-moderate

# Fix controls flagged by review
pretorin campaign controls --mode review-fix --family AC --review-job <job-id> \
  --system "My System" --framework-id fedramp-moderate

# Auto-apply after completion
pretorin campaign controls --mode initial --family AC --apply \
  --system "My System" --framework-id fedramp-moderate

Policy Campaign

# Answer all incomplete policy questions
pretorin campaign policy --mode answer --all-incomplete

# Fix review findings for a specific policy
pretorin campaign policy --mode review-fix --policies <policy-id>

Scope Campaign

pretorin campaign scope --mode answer \
  --system "My System" --framework-id fedramp-moderate

Check Status

pretorin campaign status --checkpoint .pretorin/campaign-checkpoint.json

MCP Tool Sequence

For AI agents working through MCP:

1. pretorin_get_workflow_state — Understand what needs work
2. pretorin_get_pending_families — Identify target families
3. pretorin_prepare_campaign — Create the campaign
4. pretorin_claim_campaign_items — Claim items
5. pretorin_get_campaign_item_context — Get context per item
6. pretorin_submit_campaign_proposal — Submit drafts
7. pretorin_get_campaign_status — Review progress
8. pretorin_apply_campaign — Push to platform

Policy & Scope Questionnaires

Pretorin uses questionnaire workflows to capture organizational policy information and system scope details. Both follow a similar lifecycle: answer questions, generate documents, review, and iterate.

Policy Questionnaire Workflow

Organization policies (e.g., Access Control Policy, Incident Response Policy) are defined at the org level and apply across systems.

1. List Available Policies

pretorin policy list

Or via MCP: pretorin_list_org_policies

2. View Current State

# Show questionnaire state and saved review findings
pretorin policy show --policy <policy-id-or-name>

Or via MCP:

pretorin_get_pending_policy_questions  # lightweight — only unanswered
pretorin_get_policy_question_detail    # guidance and examples per question

3. Answer Questions

Via CLI — Draft answers from your workspace:

# Preview proposed answers
pretorin policy populate --policy <policy-id>

# Apply answers to the platform
pretorin policy populate --policy <policy-id> --apply

Via MCP — Answer individually for precise control:

pretorin_answer_policy_question(policy_id, question_id, answer)

Or batch-update multiple answers:

pretorin_patch_org_policy_qa(policy_id, updates=[{question_id, answer}, ...])

4. Generate Policy Document

Once questions are answered, trigger AI document generation:

pretorin_trigger_policy_generation(policy_id)

5. Review

Trigger an AI review of the policy:

pretorin_trigger_policy_review(policy_id)
pretorin_get_policy_review_results(policy_id)  # poll for results

Review results include findings with severity levels, affected sections, and recommended fixes.

6. Track Status

pretorin_get_policy_workflow_state(policy_id)
pretorin_get_policy_analytics()

Scope Questionnaire Workflow

Scope questionnaires are system+framework specific. They define what’s in scope, what’s excluded, and system boundary details.

1. View Current State

# Show scope questionnaire state and review findings
pretorin scope show --system "My System" --framework-id fedramp-moderate

Or via MCP:

pretorin_get_pending_scope_questions(system_id, framework_id)
pretorin_get_scope_question_detail(system_id, framework_id, question_id)

2. Answer Questions

Via CLI — Draft answers from your workspace:

# Preview proposed answers
pretorin scope populate --system "My System" --framework-id fedramp-moderate

# Apply answers to the platform
pretorin scope populate --system "My System" --framework-id fedramp-moderate --apply

Via MCP — Answer individually:

pretorin_answer_scope_question(system_id, framework_id, question_id, answer)

Or batch-update:

pretorin_patch_scope_qa(system_id, framework_id, updates=[{question_id, answer}, ...])

3. Generate Scope Document

pretorin_trigger_scope_generation(system_id, framework_id)

4. Review

pretorin_trigger_scope_review(system_id, framework_id)
pretorin_get_scope_review_results(system_id, framework_id)

5. View Full Scope

pretorin_get_scope(system_id, framework_id)

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

Bulk Questionnaire Campaigns

For answering many questions at once, use campaigns:

# Answer all incomplete policy questions
pretorin campaign policy --mode answer --all-incomplete

# Answer scope questions
pretorin campaign scope --mode answer --system "My System" --framework-id fedramp-moderate

# Fix review findings
pretorin campaign policy --mode review-fix --policies <policy-id>

See Campaign Workflows for details on the campaign lifecycle.

Vendor Inheritance

Many compliance controls are partially or fully satisfied by external providers (cloud platforms, SaaS tools, managed services). Pretorin tracks these inheritance relationships and keeps inherited narratives in sync with vendor documentation.

Concepts

• Vendor — An external provider or internal shared service (CSP, SaaS, managed service, internal)
• Responsibility edge — A link between a control and a vendor indicating the control is inherited or shared
• Stale edge — A responsibility edge where the source narrative has changed but the inherited control hasn’t been updated

Workflow

1. Create Vendor Entities

pretorin vendor create "AWS GovCloud" --type csp \
  --description "Primary cloud infrastructure" \
  --authorization-level "FedRAMP High P-ATO"

pretorin vendor create "Okta" --type saas \
  --description "Identity and access management"

2. Upload Vendor Documentation

pretorin vendor upload-doc <vendor_id> ./aws-crm.pdf \
  --name "AWS Customer Responsibility Matrix" \
  --attestation-type vendor_provided

pretorin vendor upload-doc <vendor_id> ./okta-soc2.pdf \
  --name "Okta SOC 2 Type II Report" \
  --attestation-type third_party_attestation

3. Set Control Responsibility

Via MCP tools:

pretorin_set_control_responsibility(system_id, control_id, framework_id, vendor_id, responsibility_type)

Responsibility types:

• inherited — Fully satisfied by the vendor
• shared — Partially satisfied; your system handles the remainder

4. Generate Inheritance Narratives

pretorin_generate_inheritance_narrative(system_id, control_id, framework_id, vendor_id)

AI generates a narrative grounded in the vendor’s uploaded documentation, explaining how the vendor satisfies the control requirements.

5. Monitor Staleness

Over time, vendor documentation or source narratives may be updated. Check for stale inheritance:

pretorin_get_stale_edges(system_id, framework_id)

Returns controls where the source has changed but the inherited narrative hasn’t been refreshed.

6. Sync Stale Edges

pretorin_sync_stale_edges(system_id, framework_id)

Bulk updates inherited controls by regenerating narratives from the latest source.

Linking Evidence to Vendors

pretorin_link_evidence_to_vendor(evidence_id, vendor_id, attestation_type)

Attestation types: self_attested, third_party_attestation, vendor_provided

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:

Medium Priority (Mixed Code/Policy)

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 and AI guidance are shown by default. The ai_guidance field provides evidence expectations, implementation considerations, and common failures. Use --brief to show only the basic info panel.

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:

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 (references are included by default; use --brief to skip them)
• 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

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

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

Confidence Levels

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 are shown by default. 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:

Step 3: Compare Requirements

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

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

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> to check for framework-specific parameters or additional requirements (references are included by default).

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.

STIG Compliance Scanning

Pretorin integrates STIG (Security Technical Implementation Guide) scanning to verify technical control implementations. The scanning workflow connects NIST 800-53 controls to specific technical checks via the CCI (Control Correlation Identifier) chain.

Traceability Chain

NIST 800-53 Control → CCIs → SRGs → STIG Rules → Scanner Results

• CCI — Control Correlation Identifier: bridges a control requirement to testable items
• SRG — Security Requirements Guide: technology-neutral security requirements
• STIG Rule — Technology-specific check with detailed test and fix procedures

Browse the Chain

Find Applicable STIGs

# Show STIGs applicable to your system
pretorin stig applicable --system "My System"

# AI-infer STIGs from system profile
pretorin stig infer --system "My System"

Explore the Traceability

# Full chain from a NIST control to STIG rules
pretorin cci chain ac-2 --system "My System"

# Browse CCIs for a control
pretorin cci list --control ac-2

# See what a specific CCI requires
pretorin cci show CCI-000015

# Browse STIG rules
pretorin stig rules <stig_id> --severity cat_i

Scanning Workflow

1. Check Scanner Availability

pretorin scan doctor

Supported scanners: OpenSCAP, InSpec, AWS Cloud Scanner, Azure Cloud Scanner, Manual.

2. Review Test Manifest

pretorin scan manifest --system "My System"

Shows which STIGs, rules, and scanners apply to the system.

3. Run Scans

# Run all applicable scans
pretorin scan run --system "My System"

# Dry run first
pretorin scan run --system "My System" --dry-run

# Target specific STIG or tool
pretorin scan run --stig <stig_id> --tool openscap

4. Review Results

# All results
pretorin scan results --system "My System"

# Filter by control
pretorin scan results --system "My System" --control ac-2

5. Submit Results to Platform

Results are automatically submitted when scanning with an active system context. For manual submission via MCP:

pretorin_submit_test_results(system_id, results)

MCP Tools for STIG/CCI

Environment Variables

Environment variables override stored configuration values.

Authentication & API

Context

Agent Runtime

Source Attestation

Behavior

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

For the model name:

1. OPENAI_MODEL environment variable (highest)
2. openai_model in ~/.pretorin/config.json
3. Org AI settings from the platform (cached)
4. gpt-4o default

CI/CD Example

export PRETORIN_API_KEY=pretorin_your_key_here
export PRETORIN_DISABLE_UPDATE_CHECK=1
export PRETORIN_SYSTEM_ID=your_system_id

pretorin frameworks list
pretorin evidence push

Artifact Schema Reference

Complete field reference for compliance artifact JSON documents.

Top-Level Fields

Component Fields

Control Implementation Fields

Evidence Fields

Implementation Status Definitions

Confidence Levels

Contributing

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

We welcome contributions to the CLI, MCP server, docs, scanners, developer workflows, and local tooling. This repository is open source under Apache-2.0, while Pretorin-hosted platform services, authenticated API access, and account-scoped data are governed separately by the applicable platform terms.

Scope

Good fits for this repository:

• CLI commands and output improvements
• MCP tools, prompts, and local agent integrations
• Scanner integrations and developer workflow automation
• Documentation, examples, and tests

Out of scope for public contributions:

• Customer data, exported platform data, or private operational runbooks
• Secrets, internal credentials, or private environment details
• Changes that imply trademark rights or suggest an unofficial fork is an official Pretorin service

For brand usage guidance, see Trademarks and Service Terms.

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

Integration tests require a valid API key tied to an account that has accepted the platform terms.

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 main
2. Make your changes
3. Ensure tests pass and code is properly formatted
4. Add a sign-off to each commit with git commit -s
5. Submit a pull request

By submitting a contribution, you certify that:

• You have the right to submit the code, docs, or other materials.
• Your contribution may be distributed under the Apache License, Version 2.0.
• You are not including confidential information, customer data, or material that is governed by separate platform terms.

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

Legal and Platform Boundaries

• The source code in this repository is licensed under Apache-2.0.
• The Pretorin name, logos, and other brand assets remain subject to trademark rights and are not licensed for reuse except for nominative/reference use. See Trademarks and Service Terms.
• Access to Pretorin-hosted APIs, services, and account-scoped data is authenticated and governed by separate platform terms.

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

Trademarks and Service Terms

Pretorin, the Pretorin logo, and related brand assets are trademarks or registered trademarks of Pretorin, Inc.

The Apache-2.0 license for this repository covers the source code and documentation in this repo. It does not grant permission to use Pretorin trademarks, logos, or branding for derivative products or services in a way that suggests sponsorship, endorsement, or official status.

Permitted uses generally include truthful, referential statements such as:

• Saying that your project is based on or compatible with Pretorin CLI
• Linking to this repository or to Pretorin documentation
• Describing changes you made in a fork, as long as you do not imply the fork is an official Pretorin release or hosted service

Not permitted without separate permission:

• Shipping a fork under the Pretorin name as if it were the official product
• Reusing Pretorin logos, trade dress, or marketing assets for another hosted service
• Suggesting endorsement, partnership, certification, or official support where none exists

Access to Pretorin-hosted platform services, APIs, and any account-scoped data returned by those services is governed by the applicable platform terms and account agreements, which are separate from the open-source license for this repository.

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.16.3 - 2026-04-26

Fixed

• CCI chain test fix: test_cci_chain_with_system_status now correctly mocks resolve_execution_context so CCI status rendering is exercised. No production code changes.

0.16.2 - 2026-04-21

Fixed

• pretorin campaign controls --family case-insensitive resolution (#84): --family cc6 now resolves to canonical CC6 before hitting the backend. Unknown families raise a structured error listing available families and pointing at pretorin frameworks families <framework-id>. Same fix applied to pretorin_prepare_campaign MCP handler.

0.16.1 - 2026-04-21

Added

• Gap questions for policy and scope Q&A: MCP tool descriptions guide agents through answer-first workflow with structured gap questions for organizational knowledge gaps.

0.16.0 - 2026-04-21

Changed (BREAKING)

• evidence_type is now required on every CLI, MCP, agent, and workflow write path (#79). CLI paths hard-error when the user omits -t/--type; every other path runs a client-side normalizer before submission.

Added

• Evidence provenance fields: CLI sends code_file_path, code_line_numbers, code_snippet, code_repository, code_commit_hash on all evidence creation paths. Auditors can trace evidence to source files and commits.
• Source verification mapping: Attested source identities mapped to platform’s SourceVerificationPayload with source_type and source_role.
• pretorin evidence upload: Upload files (screenshots, PDFs, configs) as evidence with SHA-256 integrity verification.
• pretorin_upload_evidence MCP tool: Agents and recipes can upload evidence files via MCP.
• File reference validation: Campaign apply reads actual file content as canonical snippet, validates paths and line ranges.
• Code provenance on local evidence: Frontmatter supports code_* fields for local evidence create and push.
• pretorin.evidence.types module: canonical 13-type enum, AI-drift alias map, and normalize_evidence_type() with fuzzy matching.

Changed

• Evidence models include code provenance fields. Campaign extracts code_* and relevance_notes from AI recommendations.
• upsert_evidence() creates enriched evidence as new record when provenance fields are provided.
• AI generation prompt requests code file paths and line numbers in evidence recommendations.

Fixed

• SOC2 campaign batches with non-canonical evidence_type strings now succeed end-to-end via the normalizer.
• Non-campaign write paths can no longer silently tag missing-type evidence as policy_document.

0.15.5 - 2026-04-20

Fixed

• Campaign --apply runs no longer flood the evidence locker with AI-authored summaries typed as policy_document (issue #77). The pipeline now wires recommended_notes through to the platform as real gap notes, rejects evidence recommendations with missing or invalid evidence_type (turning them into synthesized gap notes), and emits a structured campaign.apply.control telemetry line for post-ship measurement.
• Partial failures in the per-control notes write now raise PretorianClientError with the failing indexes, mirroring the existing evidence-batch behavior so checkpoint resumes are idempotent.
• Evidence batch result mapping now aligns offsets to the original recommendation index via the accepted-items list and asserts length match, fixing a latent index-drift bug that appeared once any recommendation was rejected mid-loop.
• Completion note now fires when all pending work has landed across runs, not only when something new was written in the current run.

Changed

• evidence_type is now required on EvidenceBatchItemCreate. The campaign batch write path no longer silently tags missing types as policy_document; pydantic validation raises instead. Other evidence write paths (CLI, MCP, direct API) keep their existing defaults.
• Agent drafting prompts (_build_generation_task, _draft_control_fix, _WORKFLOW_GUARDRAILS, codex system prompt, [[PRETORIN_TODO]] template) now list all 13 valid evidence types verbatim and state that an empty evidence_recommendations list is a valid result — gaps belong in recommended_notes.
• _WORKFLOW_GUARDRAILS merged in the evidence-collection skill’s “concrete, auditable artifacts” language so narrative-generation skill callers inherit the same rules.

0.15.4 - 2026-04-18

Changed

• Updated 6 dependencies to resolve 7 known vulnerabilities (cryptography, pygments, pyjwt, pytest, python-multipart, requests)
• Added CLAUDE.md and AGENTS.md for AI agent context

0.15.3 - 2026-04-18

Fixed

• pretorin update now checks PyPI before running pip, skipping reinstall when already current
• pretorin update verifies the installed version after pip runs, detecting silent failures in pipx/uv-managed environments

Added

• pretorin update [VERSION] accepts an optional version argument to install a specific release

0.15.2 - 2026-04-18

Changed

• Documentation sync: rebuilt all docs to match current codebase

0.15.1 - 2026-04-17

Added

• pretorin evidence delete <evidence-id> command with --yes flag for non-interactive workflows
• MCP tool pretorin_delete_evidence for programmatic evidence deletion within system scope
• API client method delete_evidence for the public DELETE endpoint

0.15.0 - 2026-04-16

Added

• Source manifest requirement policy: declare which external sources a system expects and gate compliance writes on their presence
• pretorin context manifest command for viewing the resolved manifest and evaluating it against detected sources
• Manifest loading from four layered sources: env var, repo-local .pretorin/source-manifest.json, per-system user config, or inline config key
• Family-level source requirements with three requirement levels (required/recommended/optional) and write blocking on missing required sources
• Manifest evaluation results in write provenance (manifest_status and missing_required_sources fields)

Changed

• _enforce_source_attestation now evaluates manifest requirements after the existing MISMATCH check
• resolve_execution_context and build_write_provenance accept optional control_id for family-level manifest enforcement

0.14.0 - 2026-04-10

Changed

• MCP and agent write workflows now treat the active CLI context as a strict execution boundary by default, with an explicit allow_scope_override escape hatch for intentional cross-scope writes
• Control-scoped MCP and agent workflows now route through one shared scope-validation path so exact control lookup happens in the resolved framework before any write proceeds
• Agent guidance now tells built-in workflows to resolve an exact user-supplied control in the active framework before doing broader discovery
• pretorin mcp-serve now emits a non-blocking stderr update prompt when a newer CLI release is available, so MCP-only users can discover upgrades without interrupting active tool calls

Fixed

• apply_campaign now reports apply: true after a successful apply run and persists that state back to the checkpoint summary
• Stored active context and campaign checkpoints are now validated against the current API environment before campaign reads or writes proceed
• Control-scoped MCP and agent updates now refuse silent remaps like cm-04.02 to a different control when the exact control does not resolve in the active framework

Added

• pretorin_get_cli_status and the status://cli MCP resource expose local CLI version, update availability, and upgrade guidance to MCP hosts and agents

0.13.1 - 2026-04-07

Added

• pretorin_get_stig MCP tool for STIG benchmark detail
• pretorin_get_cci_chain MCP tool for full Control → CCI → SRG → STIG rule traceability

0.13.0 - 2026-04-07

Added

• Complete STIG/CCI MCP tools: list_stigs, get_stig, list_stig_rules, get_stig_rule, list_ccis, get_cci, get_cci_chain, get_cci_status, get_stig_applicability, infer_stigs, get_test_manifest, submit_test_results
• STIG/CCI agent tools for OpenAI Agents SDK
• pretorin stig CLI group: list, show, rules, applicable, infer
• pretorin cci CLI group: list, show, chain
• pretorin scan CLI group: doctor, manifest, run, results
• Scanner orchestration module with support for OpenSCAP, InSpec, AWS/Azure Cloud Scanners, and Manual review

0.12.0 - 2026-04-04

Added

• Vendor management CLI: pretorin vendor list/create/get/update/delete/upload-doc/list-docs
• MCP vendor tools: list_vendors, create_vendor, get_vendor, update_vendor, delete_vendor, upload_vendor_document, list_vendor_documents, link_evidence_to_vendor
• Inheritance/responsibility MCP tools: set_control_responsibility, get_control_responsibility, remove_control_responsibility, generate_inheritance_narrative, get_stale_edges, sync_stale_edges

0.11.0 - 2026-04-02

Added

• Campaign CLI: pretorin campaign controls/policy/scope/status
• Campaign MCP tools: prepare_campaign, claim_campaign_items, get_campaign_item_context, submit_campaign_proposal, apply_campaign, get_campaign_status
• External-agent-first campaign pattern with checkpoint persistence and lease-based concurrency
• Campaign builtin executor for local execution

0.10.0 - 2026-03-28

Added

• Workflow state and analytics MCP tools: get_workflow_state, get_analytics_summary, get_family_analytics, get_policy_analytics
• Family operations MCP tools: get_pending_families, get_family_bundle, trigger_family_review, get_family_review_results
• Policy workflow MCP tools: get_pending_policy_questions, get_policy_question_detail, answer_policy_question, get_policy_workflow_state, trigger_policy_generation, trigger_policy_review, get_policy_review_results
• Scope workflow MCP tools: get_pending_scope_questions, get_scope_question_detail, answer_scope_question, trigger_scope_generation, trigger_scope_review, get_scope_review_results
• ExecutionScope for thread-safe parallel agent execution

0.9.7 - 2026-03-25

Fixed

• Aligned CLI control status validation with the live platform status enum set, including partially_implemented
• Aligned MCP control status validation with the live platform status enum set to match public API behavior
• Synced package version metadata and release notes so PyPI builds publish a consistent CLI version

Changed

• Updated CLI and MCP coverage tests to reflect the platform control status contract used by public control workflows

0.8.7 - 2026-03-23

Added

• MCP questionnaire tooling for scope and organization policy workflows

Changed

• MCP documentation now reflects the full 29-tool surface, including batch evidence support

0.8.6 - 2026-03-23

Added

• pretorin context show --quiet for compact shell-friendly context checks
• pretorin context show --check to fail fast when stored scope is missing, stale, or unverified

Changed

• context show caches the last known system name so offline and stale context output stays human-friendly

Fixed

• context show validates stored context against the platform instead of silently treating deleted systems as active

0.8.5 - 2026-03-23

Fixed

• Reset active system/framework context when logging into a different API endpoint or with a different API key
• Model API base URL now follows the configured platform public API endpoint during login
• scope populate --json --apply and policy populate --json --apply now persist questionnaire updates
• Larger Codex subprocess line buffer for policy questionnaire responses

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