Pretorin CLI

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

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

Two Usage Modes

Pretorin works in two modes depending on your setup:

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

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

What You Can Do

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

Architecture

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

Links

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

Installation

Pretorin CLI requires Python 3.10 or later.

Recommended: uv

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

uv tool install pretorin

pip

pip install pretorin

pipx

pipx provides isolated installation similar to uv:

pipx install pretorin

Docker

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

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

Verify Installation

pretorin version

Expected output:

pretorin version 0.8.1

Updating

Check for and install the latest version:

pretorin update

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

export PRETORIN_DISABLE_UPDATE_CHECK=1
# or
pretorin config set disable_update_check true

Development Installation

For contributing to Pretorin CLI:

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

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

Authentication

Getting an API Key

Get your API key from platform.pretorin.com.

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

Login

pretorin login

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

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

Verify Authentication

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

Logout

Clear stored credentials:

pretorin logout

API Key via Environment Variable

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

export PRETORIN_API_KEY=pretorin_your_key_here

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

Quick Start

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

Browse Frameworks

List all available compliance frameworks:

pretorin frameworks list

Get details on a specific control:

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

Set Up Context

Set your active system and framework for platform operations:

# Interactive selection
pretorin context set

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

Create Evidence

Create a local evidence file:

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

Push evidence to the platform:

pretorin evidence push

Run an Agent Task

Use the Codex agent for compliance analysis:

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

Or use a predefined skill:

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

Connect Your AI Tool via MCP

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

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

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

See the MCP Setup Guides for other tools.

Run the Demo Walkthrough

An interactive demo script is included in the repository:

bash scripts/demo-walkthrough.sh

Framework Browsing

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

List All Frameworks

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

Total: 8 framework(s)

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

Get Framework Details

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

List Control Families

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

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

CMMC Family IDs

CMMC frameworks use level-specific family slugs:

$ pretorin frameworks families cmmc-l2

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

Get Family Details

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

List Controls

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

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

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

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

Get Control Details

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

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

With References

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

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

This adds:

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

Common Mistakes

Using the wrong ID format produces an error:

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

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

Document Requirements

pretorin frameworks documents fedramp-moderate

Returns explicit and implicit document requirements for the framework.

Framework Metadata

Get per-control metadata for a framework:

pretorin frameworks metadata nist-800-53-r5

Submit Artifacts

Submit a compliance artifact JSON file:

pretorin frameworks submit-artifact artifact.json

See Artifact Generation for the artifact schema.

JSON Output

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

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

Context Management

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

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

List Available Systems

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

Set Active Context

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

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

Show Current Context

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

Clear Context

pretorin context clear

Single-Scope Enforcement

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

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

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

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

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

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

Evidence Commands

The evidence command group manages local evidence files and syncs them to the Pretorin platform.

Create Local Evidence

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

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

List Local Evidence

# List all local evidence
pretorin evidence list

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

Push Evidence to Platform

pretorin evidence push

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

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

Search Platform Evidence

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

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

Upsert Evidence

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

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

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

Evidence Types

Valid evidence types:

Markdown Quality Requirements

Evidence descriptions must be auditor-ready markdown:

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

These requirements are validated before push/upsert operations.

Narrative Commands

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

Get Current Narrative

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

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

Push a Narrative File

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

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

Markdown Quality Requirements

Narratives must be auditor-ready markdown:

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

These requirements are validated before push.

Generating Narratives with AI

To generate narratives using the agent runtime:

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

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

See Skills for more on agent-powered narrative generation.

No-Hallucination Requirements

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

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

Notes Commands

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

List Notes

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

Add a Note

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

Gap Note Format

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

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

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

Monitoring Commands

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

Push a Monitoring Event

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

Event Types

Severity Levels

Context Requirement

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

Review Commands

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

Run a Review

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

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

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

Check Implementation Status

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

Configuration

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

List Configuration

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

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

Get a Config Value

pretorin config get api_key

Set a Config Value

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

Show Config File Path

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

Config File Format

The config file is JSON:

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

Configuration Keys

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

Evidence Commands

Narrative Commands

Notes Commands

Monitoring Commands

Agent Commands

Review Commands

Config Commands

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 23 compliance tools.

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

Scope

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

Tool Categories

The 23 MCP tools are organized into categories:

See Tool Reference for the complete list.

Quick Setup

# 1. Install
uv tool install pretorin

# 2. Authenticate
pretorin login

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

See Setup Guides for other AI tools.

Example Conversations

Getting Started with a Framework

You: What compliance frameworks are available for government systems?

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

Understanding a Control

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

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

Control Family Overview

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

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

MCP Setup Guides

Prerequisites

Install and authenticate the Pretorin CLI:

uv tool install pretorin
pretorin login

Claude Code

Quick setup — run a single command:

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

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

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

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

Claude Code detects the file automatically.

Claude Desktop

Add to your Claude Desktop configuration file:

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

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

Restart Claude Desktop after saving.

Cursor

Add to ~/.cursor/mcp.json:

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

Restart Cursor after saving.

OpenAI Codex CLI

Add to ~/.codex/config.toml:

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

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

Windsurf

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

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

Restart Windsurf after saving.

Other MCP Clients

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

To test the server manually:

pretorin mcp-serve

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

PATH Considerations

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

# Find the full path
command -v pretorin

Then use that path in your configuration:

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

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

MCP Tool Reference

The MCP server provides 23 tools organized by category.

Framework & Control Reference

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

pretorin_list_frameworks

List all available compliance frameworks.

Parameters: None

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

pretorin_get_framework

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

Parameters:

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

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

pretorin_list_control_families

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

Parameters:

• framework_id (required)

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

pretorin_list_controls

List controls for a framework, optionally filtered by family.

Parameters:

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

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

pretorin_get_control

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

Parameters:

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

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

pretorin_get_control_references

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

Parameters:

• framework_id (required)
• control_id (required)

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

pretorin_get_document_requirements

Get document requirements for a framework.

Parameters:

• framework_id (required)

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

Systems

pretorin_list_systems

List systems in the current organization.

Parameters: None

Returns: System IDs, names, and summary metadata.

pretorin_get_system

Get system metadata including attached frameworks and security impact level.

Parameters:

• system_id (required) — System ID or name

Returns: System metadata.

pretorin_get_compliance_status

Get framework progress and implementation posture for a system.

Parameters:

• system_id (required)

Returns: Framework status summaries and progress metrics.

Evidence Management

pretorin_search_evidence

Search current evidence items.

Parameters:

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

Returns: Matching evidence items.

pretorin_create_evidence

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

Parameters:

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

Returns:

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

pretorin_link_evidence

Link an existing evidence item to a control.

Parameters:

• system_id (required)
• evidence_id (required)
• control_id (required)
• framework_id (optional)

Returns: Link confirmation.

pretorin_get_narrative

Get the current narrative record for a control.

Parameters:

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

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

Implementation Context

pretorin_get_control_context

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

Parameters:

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

Returns: Combined control metadata and implementation details.

pretorin_get_scope

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

Parameters:

• system_id (required)

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

pretorin_get_control_implementation

Get implementation details for a control in a system.

Parameters:

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

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

pretorin_get_control_notes

Get notes for a control implementation.

Parameters:

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

Returns: Note list with total count.

pretorin_update_narrative

Push a narrative text update for a control implementation.

Parameters:

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

Returns: Update confirmation.

pretorin_add_control_note

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

Parameters:

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

Returns: The created note record.

Compliance Updates

pretorin_update_control_status

Update the implementation status for a control.

Parameters:

• system_id (required)
• control_id (required)
• status (required)
• framework_id (optional)

Returns: Status update confirmation.

pretorin_push_monitoring_event

Create a monitoring event for a system.

Parameters:

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

Returns: The created monitoring event.

pretorin_generate_control_artifacts

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

Parameters:

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

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

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

MCP Resources

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

Available Resources

Usage

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

Analysis Schema

analysis://schema

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

Framework Analysis Guide

analysis://guide/{framework_id}

Available framework guides:

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

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

Control Analysis Guidance

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

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

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

MCP Troubleshooting

“Not authenticated” Error

Ensure you’ve logged in:

pretorin login
pretorin whoami  # Verify authentication

MCP Server Not Found

1. Verify pretorin is installed and in your PATH:

   which pretorin
   pretorin --version
   

2. Try using the full path in your configuration:

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

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

   command -v pretorin
   

Server Crashes or Hangs

Check the MCP server logs:

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

Ensure your API key is valid:

pretorin whoami

Framework or Control Not Found

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

Common ID Mistakes

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/v1

# 3. Validate runtime
pretorin agent doctor
pretorin agent install

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

Model Key Precedence

The agent runtime resolves model keys in this order:

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

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

Custom Model Endpoints

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

• Azure OpenAI
• vLLM
• LiteLLM
• Ollama

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

How It Works

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

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

Agent Skills

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

Available Skills

Using Skills

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

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

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

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

List Skills

pretorin agent skills

Skill Details

Gap Analysis

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

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

See Gap Analysis Workflow for the detailed methodology.

Narrative Generation

Generates control implementation narratives that meet auditor-readiness requirements:

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

Evidence Collection

Searches the codebase for evidence that maps to specific controls:

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

Security Review

Reviews the codebase against specific controls:

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

Agent Runtime Management

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

Check Runtime Health

pretorin agent doctor

Validates that the Codex runtime is properly installed and configured.

Install Codex Binary

pretorin agent install

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

Check Version

pretorin agent version

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

Manage MCP Servers

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

List Configured Servers

pretorin agent mcp-list

Add a Server

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

Example:

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

Remove a Server

pretorin agent mcp-remove <name>

Runtime Architecture

The Codex runtime is fully isolated:

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

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

Supported Frameworks

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

Framework Overview

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

Framework Relationships

Understanding how frameworks relate helps with cross-compliance:

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

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

NIST SP 800-53 Rev 5

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

Target audience: Federal agencies

NIST SP 800-171 Rev 3

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

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

FedRAMP

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

Impact levels:

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:

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:

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.

4. Draft Updates

Prepare three types of updates:

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

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

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

Gap Notes — Unresolved items requiring manual follow-up:

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

5. Push Updates

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

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

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

Read-Only Draft Workflow

When you want AI drafts before any platform writes:

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

Markdown Quality Rules

All narratives and evidence must pass markdown quality validation:

Narratives

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

Evidence

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

Evidence Deduplication

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

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

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

Gap Analysis Workflow

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

Step 1: Scope the Assessment

Determine which framework and control families to assess.

# List frameworks if not specified
pretorin frameworks list

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

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

Step 2: Prioritize Control Families

High Priority (Direct Code Evidence)

These families typically have strong evidence in source code:

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
   

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

3. Search the codebase using guidance-informed patterns:

File patterns:

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

Keyword patterns:

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

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

Step 4: Assess Implementation Status

For each control, assign a status:

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

Step 5: Produce the Report

Structure the gap analysis output as:

Summary

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

Family-by-Family Findings

For each assessed family:

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

Priority Remediation Items

Rank gaps by:

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

Evidence Summary

For each assessed control:

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

Example Output

See the example gap analysis for a complete sample report.

Tips

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

Example: Gap Analysis Report

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

Gap Analysis: Acme Web Platform — FedRAMP Moderate

Summary

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

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 --references
pretorin frameworks control fedramp-moderate ac-02 --references
pretorin frameworks control nist-800-171-r3 03.01.01 --references
pretorin frameworks control cmmc-l2 AC.L2-3.1.1 --references

Compare what each framework emphasizes. For Account Management:

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

Step 4: Identify Gaps and Overlaps

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

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

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

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

Using MCP for Cross-Framework Mapping

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

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

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

Environment Variables

Environment variables override stored configuration values.

Authentication & API

Agent Runtime

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

CI/CD Example

export PRETORIN_API_KEY=pretorin_your_key_here
export PRETORIN_DISABLE_UPDATE_CHECK=1

pretorin frameworks list
pretorin evidence push

Artifact Schema Reference

Complete field reference for compliance artifact JSON documents.

Top-Level Fields

Component Fields

Control Implementation Fields

Evidence Fields

Implementation Status Definitions

Confidence Levels

Contributing

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

Getting Started

1. Fork the repository
2. Clone your fork:

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

3. Install development dependencies:

   uv pip install -e ".[dev]"
   

Development Workflow

Running Tests

pytest

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

pytest -m integration

Type Checking

mypy src/pretorin

Linting

ruff check src/pretorin
ruff format src/pretorin

Full CI Check

Run the same checks as the CI pipeline:

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

Submitting Changes

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

Code Style

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

CI Pipeline

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

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

Reporting Issues

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

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

Questions?

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

Changelog

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

0.8.0 - 2026-03-07

Added

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

Changed

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

0.7.0 - 2026-03-07

Fixed

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

Changed

• MCP and legacy agent evidence search tools accept optional system_id context

0.6.1 - 2026-03-05

Fixed

• Added required MCP registry ownership marker for PyPI validation

0.6.0 - 2026-03-05

Added

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

Changed

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

Removed

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

0.5.4 - 2026-03-05

Added

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

Changed

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

Removed

• Automatic control status updates from CLI evidence push workflow

0.5.3 - 2026-03-02

Fixed

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

0.5.2 - 2026-02-27

Fixed

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

Changed

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

0.5.0 - 2026-02-27

Added

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

Changed

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

Removed

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

Security

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

0.2.0 - 2026-02-06

Added

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

Changed

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

0.1.0 - 2025-02-03

Added

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

Supported Frameworks

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