Get started

Audit attestation pack CLI

Source

Export, sign, and verify self-contained vitna.audit-pack.v1 procurement, FinOps, and model-governance attestation packs from the register, from an offline Stackfile, or in an air-gapped CI runner.

bash
DATABASE_MIGRATE_URL=... npm run aperture:audit:pack -- --org convexity --runs 10000 --out ./audit-pack.json
bash
npm run aperture:audit:pack -- --stackfile vitna.stack.json --policy policy.json --lockfile vitna.lock.json --sign ./pack.key --out ./audit-pack.json
bash
npm run aperture:audit:pack -- --verify ./audit-pack.json --pack-key <base64-spki> --record-key <base64-spki> --policy-key <base64-spki> --require-signed --fail-on-rollback --max-monthly-cost-usd 5000

Nothing is mutated in the database. Register export queries aperture.* and witness.* strictly read-only, while --stackfile and --verify open zero database connections and zero network sockets. See Audit and procurement attestation packs for how the six verification layers and cryptographic key boundaries work.

Modes and flags

  • Register export mode (--org <slug>): exports the organisation's canonical vitna.stackfile.v1, standing decisions, latest signed policy.json artifact (unless --no-policy is set), batched RFC 6962 Witness observation Merkle proofs and signed daily roots, customer-entered private SKU rates, provider compliance terms, three-provenance SKU capabilities, rollout watchdog evaluation, and compound pipeline Bill of Materials.
  • Offline Stackfile export mode (--stackfile <vitna.stack.json>): builds a deterministic vitna.audit-pack.v1 with zero database access from a Stackfile, committed Witness market snapshots, and optional --policy, --lockfile, --ledger, --evidence, and --terms files.
  • Standalone offline verification mode (--verify <pack.json>): verifies all six layers of a vitna.audit-pack.v1 file offline against optional pinned Ed25519 SPKI public keys (--pack-key, --record-key, --policy-key) and CI governance gates.
FlagMeaning
--org <slug>Export an audit pack for registered organisation <slug>
--stackfile <file>Build an offline audit pack from a vitna.stackfile.v1 file
--verify <pack.json>Verify an existing vitna.audit-pack.v1 file offline
--stages <spec>Optional comma-separated <slug>[:<invocationsPerRun>][:bg] list in --org mode
--pipeline <slug>Select one named entry from stackfile.pipelines in --stackfile mode
--runs <n>Monthly pipeline execution count (monthlyRuns)
--discover-peersInclude active Witness class-peer exploratory spend levers in pipeline BOMs
--ledger <file.jsonl>Supply vitna-runtime JSONL rows for rollout watchdog and x-vitna-run attribution
--agent <agentId>Filter --ledger rows to one x-vitna-agent identifier
--window YYYY-MM-DD..YYYY-MM-DDRestrict observation proofs and --ledger rows to a closed UTC date range
--evidence <evals.json>Supply offline evaluation measurements in --stackfile mode
--terms <terms.json>Supply offline provider compliance terms in --stackfile mode
--policy <policy.json>Embed a signed policy.json envelope file (overrides register lookup)
--no-policyOmit the latest signed aperture.artifact policy in --org mode
--lockfile <vitna.lock.json>Embed a vitna.lock.json runtime policy lock file
--label <text>Optional human-readable release or procurement review label
--sign <key-file>Sign the exported pack with an Ed25519 private key PEM file (or pass env to read SIGNING_PRIVATE_KEY)
--out <pack.json>Write the exported vitna.audit-pack.v1 JSON to <pack.json>
--pack-key <pub>Pin the expected outer pack Ed25519 SPKI public key (base64, PEM, or file path) in --verify mode
--record-key <pub>Pin the expected Witness record Ed25519 SPKI public key in --verify mode
--policy-key <pub>Pin the expected routing policy Ed25519 SPKI public key in --verify mode
--require-signedFail --verify (exit 4) if the outer pack is unsigned
--require-attested-pricesFail --verify (exit 4) if any Witness price proof lacks a signed daily Merkle root
--fail-on-rollbackFail --verify (exit 4) if rolloutWatchdog.verdict is rollback_recommended
--max-monthly-cost-usd <usd>Fail --verify (exit 4) if totalEstimatedMonthlySpendUsd exceeds <usd> or is unknown
--jsonEmit structured JSON verification report (or print raw pack JSON to stdout when --out is omitted)

Exit codes

CodeMeaning
0Export succeeded, or --verify passed (verified or verified_with_warnings)
1--org mode requested with neither DATABASE_MIGRATE_URL nor DATABASE_URL set
2Invalid flags, unreadable input file, key conflation refusal, or unknown organisation/workload
4--verify failed any cryptographic check, citation-boundary check, or CI governance gate