@grcorsair/cli

v1.1.7

Published

3 months ago

CORSAIR - CPOE ingestion and trust exchange platform

0High
0Medium
0Low

grcorsair

compliance verifiable-credentials cpoe grc soc2 jwt-vc scitt ed25519 trust

Your security tools already know if your controls work. Nobody can verify that. Until now.

Website · Documentation · CPOE Spec · Verify a CPOE · Generate trust.txt

The Problem

Compliance trust today is exchanged via PDF. SOC 2 reports, pentest results, ISO 27001 certificates — emailed as attachments, stored in shared drives, re-requested every quarter. They are machine-unreadable, unverifiable, and impossible to validate without trusting the sender.

The Solution

CORSAIR signs tool output as a CPOE (Certificate of Proof of Operational Effectiveness) — a W3C Verifiable Credential with an Ed25519 signature. Your scanner says PASS, Corsair signs "the scanner said PASS." The tool's finding, signed, verifiable.

A CPOE is:

Machine-readable — structured JSON, not a PDF
Cryptographically verifiable — Ed25519 signature, anyone can check
Provenance-tracked — records who produced the evidence, not just what it says

Anyone can verify a CPOE. Free to check. No account required. Four steps with any JWT library.

Quick Start

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

# Runtime
# Bun is required to run the CLI. Homebrew installs Bun automatically via the `oven-sh/bun` tap; npm does not.
npx skills add grcorsair/corsair               # AI agent skill (Claude Code, Cursor, 25+ agents)

# Initialize a project (generates keys + example evidence)
corsair init

# Sign your tool output as a CPOE (keys auto-generate on first use)
corsair sign --file evidence.json

# Keyless sign via API (OIDC or API key)
corsair sign --file evidence.json --auth-token $OIDC_TOKEN --api-url https://api.grcorsair.com

# Verify any CPOE (always free, no account needed)
corsair verify --file cpoe.jwt

# Verify by domain (resolves trust.txt + catalog)
corsair verify --domain acme.com

# Compare two CPOEs over time (like git diff)
corsair diff --current q2.jwt --previous q1.jwt

Production Environment Variables

CORSAIR_OIDC_CONFIG example:

{
  "providers": [
    {
      "issuer": "https://accounts.google.com",
      "audiences": ["corsair-sign"],
      "requireJti": true,
      "claimMapping": {
        "subject": "sub",
        "email": "email",
        "organization": "hd"
      }
    }
  ]
}

Persistence

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

Three Production Pillars

Corsair ships with a simple, shareable surface that maps directly to how people verify compliance in the real world.

trust.txt — publish discoverable proofs at /.well-known/trust.txt or via delegated DNS
4-line verification — verify any CPOE with standard JWT libs (see CPOE_SPEC.md)
corsair diff — drift detection that reads like git diff

corsair diff --current q2.jwt --previous q1.jwt

CLI Primitives (Full Surface)

Corsair does six things. Like git.

| Primitive | Command | What It Does | Analogy | |:----------|:--------|:-------------|:--------| | SIGN | corsair sign --file <path> | Parse tool output, record provenance, sign JWT-VC | git commit | | LOG | corsair log | List CPOEs from local files or a SCITT log | git log | | PUBLISH | corsair trust-txt generate | Generate trust.txt for proof discovery | git push | | VERIFY | corsair verify --file <cpoe.jwt> | Verify Ed25519 signature, apply policy checks | git verify-commit | | DIFF | corsair diff --current <new> --previous <old> | Compare two CPOEs, detect regressions | git diff | | SIGNAL | corsair signal generate | Generate FLAGSHIP SETs for real-time notifications | git webhooks |

DID Helpers

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

Sign Options

corsair sign --file evidence.json              # Auto-detect mapping pack, sign
corsair sign --file evidence.json --json       # Structured JSON output
corsair sign --file evidence.json --dry-run    # Preview without signing
corsair sign --file evidence.json --strict     # Enforce minimum ingestion contract
corsair sign --file evidence.json --sd-jwt     # SD-JWT selective disclosure
corsair sign --file evidence.json --sd-jwt --sd-fields scope  # Disclose only scope
corsair sign --file evidence.json --mapping ./mappings/toolx.json  # Apply mapping file
corsair sign --file evidence.json --mapping ./mappings/            # Apply mapping directory
corsair sign --file evidence.json --dependency https://vendor.com/cpoe.jwt  # Attach dependency proof
corsair sign --file evidence.json --source tool  # Override provenance source
corsair sign --file evidence.json --baseline baseline.cpoe.jwt --gate  # Fail on regression vs baseline
corsair sign --file evidence.json --auth-token $OIDC_TOKEN --api-url https://api.grcorsair.com  # Keyless sign
corsair sign --file - < data.json              # Sign from stdin

Mapping Registry

corsair mappings list                          # Show loaded mappings
corsair mappings list --json                   # Machine-readable output
corsair mappings validate --json               # Validate mappings
corsair mappings add https://example.com/pack.json  # Add a mapping pack
corsair mappings pack --id wiz --version 1.1.7 --mapping ./mappings  # Build a pack
corsair mappings sign --file pack.json --key ./keys/mapping-pack.key  # Sign a pack

Mapping packs can be signed. If a pack includes a signature, set CORSAIR_MAPPING_PACK_PUBKEY to the Ed25519 public key PEM to enforce verification.

Verify Options

corsair verify --file cpoe.jwt --json          # Structured JSON output
corsair verify --file cpoe.jwt --did           # Verify via DID:web
corsair verify --url https://acme.com/cpoe.jwt  # Verify remote CPOE
corsair verify --domain acme.com               # Resolve trust.txt + catalog
corsair verify --domain acme.com --all         # Verify all published CPOEs
corsair verify --file cpoe.jwt --require-issuer did:web:acme.com
corsair verify --file cpoe.jwt --require-framework SOC2,ISO27001
corsair verify --file cpoe.jwt --max-age 30 --min-score 90
corsair verify --file cpoe.jwt --receipts receipts.json
corsair verify --file cpoe.jwt --evidence evidence.jsonl
corsair verify --file cpoe.jwt --require-source tool --require-source-identity "Scanner v1.2"
corsair verify --file cpoe.jwt --require-tool-attestation --require-receipts --receipts receipts.json
corsair verify --file cpoe.jwt --require-evidence-chain --evidence evidence.jsonl
corsair verify --file cpoe.jwt --require-input-binding --source-document raw-evidence.json
corsair verify --file cpoe.jwt --require-scitt --receipts receipts.json
corsair verify --file cpoe.jwt --policy policy.json
corsair verify --file cpoe.jwt --dependencies
corsair verify --file cpoe.jwt --dependencies --dependency-depth 2

--source-document computes a canonical JSON hash (sorted keys) and compares it to provenance.sourceDocument.

Policy Artifacts

Policies encode acceptance criteria as portable JSON files:

corsair policy validate --file policy.json
corsair verify --file cpoe.jwt --policy policy.json

Evidence Receipts (Optional)

Evidence receipts prove that a specific evidence record exists in the evidence chain without revealing the record itself.

corsair receipts generate --evidence evidence.jsonl --index 0 --output receipt.json
corsair receipts verify --file receipt.json --cpoe cpoe.jwt

Diff Options

corsair diff --current new.jwt --previous old.jwt
corsair diff --current new.jwt --previous old.jwt --verify
corsair diff --current new.jwt --previous old.jwt --json
corsair diff --domain acme.com --verify

Signal Streams (FLAGSHIP)

corsair signal stream create --auth-token $API_KEY --api-url https://api.grcorsair.com \\
  --delivery push --endpoint https://receiver.example.com/ssf \\
  --events colors-changed,compliance-change --audience did:web:buyer.com

Trust Discovery (trust.txt)

Corsair supports a discovery layer modeled after security.txt. Organizations publish /.well-known/trust.txt so verifiers can discover DID identity, current CPOEs, SCITT log endpoints, optional catalog snapshots, policy artifacts, and FLAGSHIP streams. For large numbers of proofs, keep trust.txt tiny and point to SCITT + catalog. If you don’t run your own SCITT log, you can use the hosted Corsair log at https://api.grcorsair.com/scitt/entries.

If you can’t host at the root domain, delegate discovery via DNS:

TXT: _corsair.example.com TXT "corsair-trusttxt=https://trust.example.com/trust.txt"
TXT (optional hash pin): _corsair.example.com TXT "corsair-trusttxt-sha256=<sha256>"
CNAME: trust.example.com CNAME trust.your-host.com

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

corsair trust-txt generate --did did:web:acme.com --scitt https://api.grcorsair.com/scitt/entries?issuer=did:web:acme.com
corsair trust-txt generate --did did:web:acme.com --catalog https://acme.com/compliance/catalog.json
corsair trust-txt generate --did did:web:acme.com --policy https://acme.com/.well-known/policy.json
corsair trust-txt generate --did did:web:acme.com --cpoe-url https://acme.com/soc2.jwt
corsair trust-txt discover acme.com --verify

Hosted option: use POST /trust-txt/host on the API to generate a hosted trust.txt URL plus DNS TXT records for delegation.

Supported Inputs

Corsair auto-detects evidence via mapping packs or falls back to the generic format. Use the mapping registry to extract controls or passthrough fields without code changes (see --mapping and CORSAIR_MAPPING_DIR). Mappings are evaluated by priority (higher wins), then filename order. Mappings may set sourceTier (native|tool|platform|human) to override tier classification.

| Format | Purpose | Detection | |:-------|:--------|:----------| | mapping-pack | Tool-specific mappings (config-driven) | Auto-detected via --mapping or CORSAIR_MAPPING_* | | generic | Any JSON with { metadata, controls[] } | Default fallback |

Minimum ingestion contract: evidence must include an issuer (or auditor), assessment date, and scope. Use --strict to fail fast when any of these are missing; otherwise Corsair returns warnings.

Source tiers (deterministic): Corsair derives a source tier from the document source. Tool outputs (tool, json) map to the tool tier, while audits and manual evidence (soc2, iso27001, pentest, manual) map to the human tier.

CPOE Format

A CPOE is a JWT with three base64url-encoded segments: header.payload.signature

┌──────────────────────────────────────────────────────────────────┐
│ HEADER   { "alg": "EdDSA", "typ": "vc+jwt", "kid": "did:web:..." }      │
├──────────────────────────────────────────────────────────────────┤
│ PAYLOAD  { "iss": "did:web:...", "vc": { ... CPOE ... }, "parley": "2.0" }│
├──────────────────────────────────────────────────────────────────┤
│ SIGNATURE  Ed25519                                                        │
└──────────────────────────────────────────────────────────────────┘

The credential subject records provenance and summary — who produced the evidence, what they found:

{
  "type": "CorsairCPOE",
  "scope": "SOC 2 Type II — Acme Cloud Platform",
  "provenance": {
    "source": "tool",
    "sourceIdentity": "Cloud Scanner v1.2",
    "sourceDate": "2026-01-15"
  },
  "summary": {
    "controlsTested": 46,
    "controlsPassed": 42,
    "controlsFailed": 4,
    "overallScore": 91
  },
  "evidenceChain": {
    "chainType": "hash-linked",
    "algorithm": "sha256",
    "canonicalization": "sorted-json-v1",
    "recordCount": 128,
    "chainVerified": true,
    "chainDigest": "f4c1..."
  },
  "frameworks": {
    "SOC2": { "controlsMapped": 24, "passed": 22, "failed": 2 },
    "NIST-800-53": { "controlsMapped": 22, "passed": 20, "failed": 2 }
  },
  "extensions": {
    "mapping": { "id": "toolx-evidence-only", "evidenceOnly": true },
    "passthrough": { "summary": { "passed": 12, "failed": 2 } }
  },
  "processProvenance": {
    "chainDigest": "a7f3e2...",
    "receiptCount": 4,
    "chainVerified": true,
    "format": "in-toto/v1+cose-sign1"
  }
}

Verification

1. Decode    ─── Parse JWT header + payload (base64url)
2. Resolve   ─── Fetch issuer's DID document via HTTPS
3. Extract   ─── Find the public key matching header.kid
4. Verify    ─── Check Ed25519 signature

Anyone can do this. No Corsair account needed.

Provenance Model

Corsair records where evidence came from and lets buyers decide what's sufficient.

| Provenance | Source | Example | |:-----------|:-------|:--------| | Self | Organization self-reports | Policy documents, manual attestation | | Tool | Automated scanning tools | CSPM, SAST, vuln scanners | | Auditor | Independent third party | SOC 2 auditor, ISO 27001 certification body |

The CPOE is a signed fact: "The scanner said PASS on Jan 15." Not an opinion. Not a score. A verifiable record of what a tool found.

Privacy Architecture

Companies fear publishing detailed control data. Corsair solves this with three privacy layers — share proof, not secrets.

| Layer | What It Does | How | |:------|:-------------|:----| | Summary-Only CPOEs | Aggregate pass/fail counts, no raw evidence | Default CPOE omits control details and configuration data | | Evidence Sanitization | Strip sensitive identifiers before signing | ARNs, IPs, file paths, account IDs, API keys removed recursively | | SD-JWT Selective Disclosure | Reveal only chosen claims per verifier | IETF SD-JWT — holder controls which fields are disclosed |

Proof-Only SCITT

Register a CPOE in the transparency log without storing the credential itself — only a SHA-256 hash and COSE receipt. The CPOE is shared bilaterally while the log proves it was registered at a specific time.

corsair log register --file cpoe.jwt --scitt https://log.example.com/scitt/entries --proof-only

Dependency Proofs (Trust Graph)

Attach other issuers’ CPOEs as dependency proofs to build a composable trust graph. Each dependency stores the issuer, scope, and a hash of the referenced CPOE:

corsair sign --file evidence.json --dependency https://vendor.com/cpoe.jwt
corsair verify --file cpoe.jwt --dependencies

SD-JWT in the Sign Pipeline

corsair sign --file evidence.json --sd-jwt                    # SD-JWT with default disclosable fields
corsair sign --file evidence.json --sd-jwt --sd-fields scope  # Only scope is disclosable

Architecture

          ┌─────────────────────┐
          │  Tool / Platform     │   CSPM, SAST, vuln scanners,
          │  Evidence Output     │   API exports, tool outputs
          └──────────┬──────────┘
                     │
          ┌──────────▼──────────┐
    01    │       SIGN           │   Parse → Provenance → Sign JWT-VC (Ed25519)
          └──────────┬──────────┘
                     │
          ┌──────────▼──────────┐
    02    │        LOG           │   Register in SCITT transparency log
          └──────────┬──────────┘
                     │
          ┌──────────▼──────────┐
    03    │      VERIFY          │   Anyone verifies (free, no account)
          └──────────┬──────────┘
                     │
          ┌──────────▼──────────┐
    04    │       DIFF           │   Compare CPOEs, detect regressions
          └──────────┘

That's it. Tool output goes in, signed proof comes out.

Parley Protocol

The protocol composing Corsair is called Parley. It composes open standards so any JWT library can verify a CPOE. Zero vendor lock-in.

| Standard | Role | Implementation | |:---------|:-----|:---------------| | JWT-VC | Attestation envelope | CPOE as W3C Verifiable Credential, Ed25519-signed | | DID:web | Issuer identity | DNS-based decentralized identifiers | | SCITT | Transparency log | Append-only registry with COSE receipts + Merkle proofs | | SSF/CAEP | Real-time signals | Compliance change notifications via signed SETs | | Ed25519 | Signatures | Curve25519 — fast, compact, no weak keys | | in-toto/SLSA | Process provenance | COSE-signed pipeline receipts with Merkle root chain | | SD-JWT | Selective disclosure | Prove specific claims without revealing the full CPOE |

DID Identity

Organizations are identified via did:web DIDs. The DID document at /.well-known/did.json contains the Ed25519 public key for CPOE verification.

did:web:grcorsair.com  →  https://grcorsair.com/.well-known/did.json
did:web:acme.com       →  https://acme.com/.well-known/did.json

FLAGSHIP Events

Real-time compliance signals via OpenID SSF/CAEP:

| Event | CAEP Type | Trigger | |:------|:----------|:--------| | FLEET_ALERT | compliance-change | Drift detected | | PAPERS_CHANGED | credential-change | CPOE issued, renewed, or revoked | | MARQUE_REVOKED | session-revoked | Emergency revocation |

Integrations

Agent Skill (Recommended for AI Agents)

npx skills add grcorsair/corsair

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

MCP Server

bun run bin/corsair-mcp.ts

Tools: corsair_sign, corsair_verify, corsair_diff, corsair_formats

{ "corsair": { "command": "bun", "args": ["run", "bin/corsair-mcp.ts"], "env": { "CORSAIR_KEY_DIR": "./keys" } } }

GitHub Action

- uses: grcorsair/corsair@main
  with:
    file: evidence.json
  id: sign

API

# Sign (requires auth: API key or OIDC token)
curl -X POST https://api.grcorsair.com/sign \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -d '{"evidence": {...}, "registerScitt": true}'

# Onboard (generate did.json, jwks.json, trust.txt)
curl -X POST https://api.grcorsair.com/onboard \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -d '{"contact":"[email protected]","frameworks":["SOC2"]}'

# Verify (no auth required)
curl -X POST https://api.grcorsair.com/verify \
  -d '{"cpoe": "eyJ..."}'

SDK

The SDK is coming soon and not actively maintained. It is not published to npm. If you need a packaged dependency today, use the CLI or API.

For internal development only, you can use packages/sdk as a workspace after cloning the repo.

Testing

bun test   # 1184 tests, 64 files — all passing

Tech Stack

| Component | Technology | |:----------|:-----------| | Runtime | Bun — TypeScript, no build step | | Crypto | Ed25519 via Node.js crypto + jose | | Database | Postgres via Bun.sql — zero-dep driver | | Web | Next.js 15 + Tailwind 4 + shadcn/ui | | Standards | W3C VC 2.0, IETF SCITT, OpenID SSF/CAEP |

Dependencies: 1 runtime dep — jose (JWT/JWK). Everything else is hand-rolled.

Glossary

Lost in the acronyms? Here's every term in plain English.

Corsair Terms

| Term | What It Means | |:-----|:--------------| | CPOE | Certificate of Proof of Operational Effectiveness — a signed compliance proof. Think "digitally signed SOC 2 result." | | Parley | The open protocol behind Corsair. Like SMTP is for email, Parley is for compliance proofs. | | MARQUE | A signed CPOE — the actual JWT you hand to a verifier. Named after letters of marque (pirate commissions). | | FLAGSHIP | Real-time compliance change notifications. If your controls drift, subscribers know immediately. |

Standards Used

| Term | What It Means | |:-----|:--------------| | JWT-VC | JSON Web Token — Verifiable Credential. A W3C standard for digitally signed claims. The envelope a CPOE lives in. | | DID:web | Decentralized Identifier anchored to a domain. did:web:acme.com means "look up acme.com's public key at /.well-known/did.json." | | Ed25519 | A modern digital signature algorithm. Fast, small, no weak keys. What Corsair signs with. | | SCITT | Supply Chain Integrity, Transparency, and Trust — an IETF draft for append-only transparency logs. Corsair's audit trail. | | SSF/CAEP | Shared Signals Framework / Continuous Access Evaluation Protocol — OpenID standards for real-time security events. Powers FLAGSHIP. | | SD-JWT | Selective Disclosure JWT — prove specific claims without revealing the full document. Share your SOC 2 score without exposing every control. | | in-toto/SLSA | Supply chain provenance standards. Records the full pipeline that produced a CPOE — who ran what, when, in what order. | | COSE | CBOR Object Signing and Encryption — a compact binary signing format. Used in SCITT receipts. |

GRC Terms

| Term | What It Means | |:-----|:--------------| | GRC | Governance, Risk, and Compliance — the industry Corsair operates in. | | SOC 2 | A trust framework for service organizations. The most common compliance report in SaaS. | | NIST 800-53 | A US government catalog of security controls. One of many frameworks Corsair maps evidence to. |

corsair.ts                 # CLI entry point

src/
  types.ts                 # Core type definitions
  evidence.ts              # JSONL evidence engine with SHA-256 hash chain

  sign/                    # Sign engine
  ingestion/               # Evidence parsing (mapping packs + generic)
  parley/                  # Parley protocol (JWT-VC, SCITT, DID, COSE, CBOR, Merkle)
  flagship/                # FLAGSHIP real-time signals (SSF/CAEP)
  security/                # URL validation for DID resolver
  middleware/              # HTTP auth, rate-limit, security headers
  db/                      # Postgres via Bun.sql + migrations
  api/                     # Versioned API router
  mcp/                     # MCP server

bin/                       # Standalone CLIs (verify, DID, MCP)
functions/                 # Railway API endpoints
apps/web/                  # grcorsair.com (Next.js 15)
  packages/sdk/              # @grcorsair/sdk (coming soon, not actively maintained)
tests/                     # Test suite

Data Retention

SCITT entries are append-only by design. Entries cannot be deleted or modified after registration.
Signing keys are encrypted at rest (AES-256-GCM). Retired keys are preserved for historical CPOE verification.

Security

See SECURITY.md for vulnerability reporting.

Network access notice: the CLI and libraries perform outbound HTTPS requests for DID:web resolution, trust.txt discovery, SCITT, and SSF/CAEP endpoints. Offline usage is supported by providing local CPOEs and public keys and avoiding discovery calls.

Contributing

See CONTRIBUTING.md for the Pirate's Code.

License

Code is licensed under Apache 2.0. Specifications (CPOE_SPEC.md) are licensed under CC BY 4.0. See NOTICE for the full licensing architecture.

Verify trust. Don't assume it.