Quick Start

Prerequisites

• Bun runtime (required to run the CLI)
• Homebrew installs Bun automatically via the oven-sh/bun tap; npm install does not

Installation

# Install the CLI (pick one)
brew install grcorsair/corsair/corsair
npm install -g @grcorsair/cli

AI Agent Skill (Claude Code, Cursor, Copilot)

Add Corsair to any AI agent with one command:

npx skills add grcorsair/corsair

Your agent can then sign evidence, verify CPOEs, detect compliance drift, and autonomously assess vendor compliance via trust.txt. Works with 25+ AI agents.

Persistence

• CLI / local use: file-based, no database required.
• Hosted API / production: Postgres required via DATABASE_URL for keys, SCITT, and audit trails.

Sign and Verify Your First CPOE

Initialize keys + example evidence, then sign and verify:

# Initialize (generates keys + example evidence)
corsair init

# Sign the example evidence into a CPOE
corsair sign --file example-evidence.json --output cpoe.jwt

# Verify the CPOE with your local public key
corsair verify --file cpoe.jwt --pubkey ./keys/corsair-signing.pub

Publish Your DID Document (Required for DID:web Verification)

To enable --did verification, publish a DID document at:

https://<your-domain>/.well-known/did.json

Generate the DID document (and optional JWKS) from your keys:

corsair did generate --domain your-domain.com --output did.json
corsair did jwks --domain your-domain.com --output jwks.json

Host the outputs at:

• https://your-domain.com/.well-known/did.json
• https://your-domain.com/.well-known/jwks.json

Then verify via DID:web:

corsair verify --file cpoe.jwt --did

See JWT-VC Integration for the DID document format.

Publish trust.txt (Discovery)

# Generate trust.txt for discovery
corsair trust-txt generate \
  --did did:web:your-domain.com \
  --cpoe-url https://your-domain.com/cpoe/cpoe.jwt \
  -o trust.txt

# Host at:
# https://your-domain.com/.well-known/trust.txt

# Validate from the outside
corsair trust-txt discover your-domain.com --verify

Advanced Verification (Optional)

# Verify against local evidence JSONL (strict)
corsair verify --file cpoe.jwt --evidence ./evidence/corsair-evidence.jsonl

# Require tool-attested receipts + SCITT anchors
corsair verify --file cpoe.jwt --receipts ./receipts.json --require-receipts --require-scitt

# Verify raw evidence hash binding
corsair verify --file cpoe.jwt --source-document evidence.json --require-input-binding

# Apply a policy artifact
corsair verify --file cpoe.jwt --policy ./policy.json

Sign Tool Output into a CPOE

Corsair takes structured output from security tools and signs it into a cryptographically verifiable CPOE:

# Sign tool output via a mapping pack
corsair sign --file toolx-output.json --mapping ./mappings/toolx.json

# Force generic parsing (bypass mapping registry)
corsair sign --file evidence.json --format generic

Compare CPOEs Over Time

Track how your compliance posture changes between assessments:

# Compare two CPOEs (like git diff for compliance)
corsair diff --current cpoe-v2.jwt --previous cpoe-v1.jwt

Generate Signing Keys

If you already ran corsair init, your keys live in ./keys.

# Generate Ed25519 keypair for CPOE signing
corsair keygen --output ./keys

Re-sign an Expiring CPOE

# Renew with fresh dates (same evidence)
corsair renew --file cpoe.jwt --output renewed.jwt

# Renew with new evidence
corsair renew --file cpoe.jwt --evidence new-findings.json --output renewed.jwt

CLI Commands

Next Steps

• Learn about the CPOE lifecycle
• Ask IT for a delegated trust subdomain using the IT request template
• Understand the provenance model
• Explore the Parley protocol