Skip to content
Cosmictron Docs

Audit Bundles

What is an audit bundle?

Section titled “What is an audit bundle?”

An audit bundle is a self-contained, cryptographically signed archive of events for a given time range or session. It contains everything an auditor or regulator needs to independently verify the event history — no connection to the Cosmictron server required.

A bundle contains:

  • All events in scope (BSATN + JSON representations)
  • Ed25519 signatures for each event
  • SHA-256 hash chain
  • RFC 3161 timestamp tokens (if enabled)
  • FROST threshold signature over the bundle (if configured)
  • Public key certificate chain for verification
  • Verification metadata and a README for auditors

Exporting a bundle

Section titled “Exporting a bundle”
Terminal window
# Export by date range
cosmictron-cli audit export \
  --from 2026-01-01 \
  --to 2026-01-31 \
  --output audit-jan-2026.bundle


# Export a specific session
cosmictron-cli audit export \
  --session-id session-abc \
  --output session-abc-audit.bundle


# Export with threshold signing (requires M-of-N participants)
cosmictron-cli audit export \
  --from 2026-01-01 --to 2026-01-31 \
  --threshold-sign \
  --output audit-jan-2026-signed.bundle

Bundle format

Section titled “Bundle format”
audit-jan-2026.bundle (tar.gz)
├── manifest.json          # Bundle metadata, event count, date range
├── events/
│   ├── 000000001.bsatn    # Event #1 (binary)
│   ├── 000000001.json     # Event #1 (human-readable)
│   └── ...
├── signatures/
│   ├── 000000001.sig      # Ed25519 signature for event #1
│   └── ...
├── timestamps/
│   ├── 000000001.tsr      # RFC 3161 token for event #1
│   └── ...
├── keys/
│   ├── signing.pub        # Public key used for signatures
│   └── chain.crt          # Certificate chain
├── threshold_signature/
│   └── bundle.frost       # FROST threshold signature (if applicable)
└── VERIFICATION.md        # Human-readable verification instructions

Verifying a bundle

Section titled “Verifying a bundle”

Recipients can verify bundles using the Cosmictron CLI:

Terminal window
cosmictron-cli audit verify-bundle audit-jan-2026.bundle

Or using the standalone verifier (no server needed):

Terminal window
# Download the standalone verifier binary
curl -L https://github.com/cosmictron/cosmictron/releases/latest/download/cosmictron-verify \
  -o cosmictron-verify
chmod +x cosmictron-verify


./cosmictron-verify audit-jan-2026.bundle

Output:

Bundle: audit-jan-2026.bundle
Events: 12,847
Date range: 2026-01-01T00:00:00Z – 2026-01-31T23:59:59Z


Checks:
  ✓ Hash chain integrity (12,847 events)
  ✓ Ed25519 signatures (12,847/12,847 valid)
  ✓ RFC 3161 timestamps (12,847/12,847 valid)
  ✓ FROST threshold signature (3-of-5 confirmed)
  ✓ Certificate chain valid


Result: PASS

Automating bundle export

Section titled “Automating bundle export”

Schedule regular exports for compliance retention:

Terminal window
# Cron: export previous month's bundle on the 1st
0 2 1 * * cosmictron-cli audit export \
  --from $(date -d "last month" +%Y-%m-01) \
  --to $(date -d "last day of last month" +%Y-%m-%d) \
  --output /audit-archive/$(date -d "last month" +%Y-%m).bundle