git.stella-ops.org/docs/modules/cli/guides/audit-bundle-format.md

Audit Bundle Format Specification

Sprint: SPRINT_20260117_027_CLI_audit_bundle_command
Task: AUD-001 - Audit Bundle Format Specification
Version: 1.0.0

Overview

The Stella Ops Audit Bundle is a self-contained, tamper-evident package containing all evidence required for an auditor to verify a release decision. The bundle is designed for:

• Completeness: Contains everything needed to verify a verdict without additional tool invocations
• Reproducibility: Includes replay instructions for deterministic re-verification
• Portability: Standard formats (JSON, Markdown) readable by common tools
• Integrity: Cryptographic manifest ensures tamper detection

Bundle Structure

audit-bundle-<digest>-<timestamp>/
├── manifest.json              # Bundle manifest with cryptographic hashes
├── README.md                  # Human-readable guide for auditors
├── verdict/
│   ├── verdict.json           # StellaVerdict artifact
│   └── verdict.dsse.json      # DSSE envelope with signatures
├── evidence/
│   ├── sbom.json              # SBOM (CycloneDX format)
│   ├── vex-statements/        # All VEX statements considered
│   │   ├── index.json         # VEX index with sources
│   │   └── *.json             # Individual VEX documents
│   ├── reachability/
│   │   ├── analysis.json      # Reachability analysis result
│   │   └── call-graph.dot     # Call graph visualization (optional)
│   └── provenance/
│       └── slsa-provenance.json
├── policy/
│   ├── policy-snapshot.json   # Policy version and rules used
│   ├── gate-decision.json     # Gate evaluation result
│   └── evaluation-trace.json  # Full policy trace (optional)
├── replay/
│   ├── knowledge-snapshot.json  # Frozen inputs for replay
│   └── replay-instructions.md   # How to replay verdict
└── schema/                    # Schema references (optional)
    ├── verdict-schema.json
    └── vex-schema.json

File Specifications

manifest.json

The manifest provides cryptographic integrity and bundle metadata.

{
  "$schema": "https://schema.stella-ops.org/audit-bundle/manifest/v1",
  "version": "1.0.0",
  "bundleId": "urn:stella:audit-bundle:sha256:abc123...",
  "artifactDigest": "sha256:abc123...",
  "generatedAt": "2026-01-17T10:30:00Z",
  "generatedBy": "stella-cli/2.5.0",
  "files": [
    {
      "path": "verdict/verdict.json",
      "sha256": "abc123...",
      "size": 12345,
      "required": true
    },
    {
      "path": "evidence/sbom.json",
      "sha256": "def456...",
      "size": 98765,
      "required": true
    }
  ],
  "totalFiles": 12,
  "totalSize": 234567,
  "integrityHash": "sha256:manifest-hash-of-all-file-hashes"
}

README.md

Auto-generated guide for auditors with:

• Bundle overview and artifact identification
• Quick verification steps
• File inventory with descriptions
• Contact information for questions

verdict/verdict.json

The StellaVerdict artifact in standard format:

{
  "$schema": "https://schema.stella-ops.org/verdict/v1",
  "artifactDigest": "sha256:abc123...",
  "artifactType": "container-image",
  "decision": "BLOCKED",
  "timestamp": "2026-01-17T10:25:00Z",
  "gates": [
    {
      "gateId": "vex-trust",
      "status": "BLOCKED",
      "reason": "Trust score below threshold (0.45 < 0.70)",
      "evidenceRefs": ["evidence/vex-statements/vendor-x.json"]
    }
  ],
  "contentId": "urn:stella:verdict:sha256:xyz..."
}

verdict/verdict.dsse.json

DSSE (Dead Simple Signing Envelope) containing the signed verdict:

{
  "payloadType": "application/vnd.stella-ops.verdict+json",
  "payload": "base64-encoded-verdict",
  "signatures": [
    {
      "keyid": "urn:stella:key:sha256:...",
      "sig": "base64-signature"
    }
  ]
}

evidence/sbom.json

CycloneDX SBOM in JSON format (or SPDX if configured).

evidence/vex-statements/

Directory containing all VEX statements considered during evaluation:

• index.json - Index of VEX statements with metadata
• Individual VEX documents named by source and ID

evidence/reachability/analysis.json

Reachability analysis results:

{
  "artifactDigest": "sha256:abc123...",
  "analysisType": "static",
  "analysisTimestamp": "2026-01-17T10:20:00Z",
  "components": [
    {
      "purl": "pkg:npm/lodash@4.17.21",
      "vulnerabilities": [
        {
          "id": "CVE-2021-23337",
          "reachable": false,
          "reason": "Vulnerable function not in call graph"
        }
      ]
    }
  ]
}

policy/policy-snapshot.json

Snapshot of policy configuration at evaluation time:

{
  "policyVersion": "v2.3.1",
  "policyDigest": "sha256:policy-hash...",
  "gates": ["sbom-required", "vex-trust", "cve-threshold"],
  "thresholds": {
    "vexTrustScore": 0.70,
    "maxCriticalCves": 0,
    "maxHighCves": 5
  },
  "evaluatedAt": "2026-01-17T10:25:00Z"
}

policy/gate-decision.json

Detailed gate evaluation result:

{
  "artifactDigest": "sha256:abc123...",
  "overallDecision": "BLOCKED",
  "gates": [
    {
      "gateId": "vex-trust",
      "decision": "BLOCKED",
      "inputs": {
        "vexStatements": 3,
        "trustScore": 0.45,
        "threshold": 0.70
      },
      "reason": "Trust score below threshold",
      "suggestion": "Obtain VEX from trusted issuer or adjust trust registry"
    }
  ]
}

replay/knowledge-snapshot.json

Frozen inputs for deterministic replay:

{
  "$schema": "https://schema.stella-ops.org/knowledge-snapshot/v1",
  "snapshotId": "urn:stella:snapshot:sha256:...",
  "capturedAt": "2026-01-17T10:25:00Z",
  "inputs": {
    "sbomDigest": "sha256:sbom-hash...",
    "vexStatements": ["sha256:vex1...", "sha256:vex2..."],
    "policyDigest": "sha256:policy-hash...",
    "reachabilityDigest": "sha256:reach-hash..."
  },
  "replayCommand": "stella replay snapshot --manifest replay/knowledge-snapshot.json"
}

replay/replay-instructions.md

Human-readable replay instructions (auto-generated, see AUD-004).

Archive Formats

The bundle can be output in three formats:

Format	Extension	Use Case
Directory	(none)	Local inspection, development
tar.gz	.tar.gz	Transfer, archival (default for remote)
zip	.zip	Windows compatibility

Verification

To verify a bundle's integrity:

stella audit verify ./audit-bundle-sha256-abc123/

Verification checks:

1. Parse manifest.json
2. Verify each file's SHA-256 hash matches manifest
3. Verify integrityHash (hash of all file hashes)
4. Optionally verify DSSE signatures

Compliance Mapping

Compliance Framework	Bundle Component
SOC 2 (CC7.1)	verdict/, policy/
ISO 27001 (A.12.6)	evidence/sbom.json
FedRAMP	All components
SLSA Level 3	evidence/provenance/

Extensibility

Custom evidence can be added to evidence/custom/ directory. Custom files must be:

• Listed in manifest.json
• JSON or Markdown format
• Include schema reference if JSON

---

Last updated: 2026-01-17 (UTC)