# 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.

```json
{
  "$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:

```json
{
  "$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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "$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:

```bash
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)_