git.stella-ops.org/docs/modules/evidence-locker/evidence-bundle-v1.md

Evidence Bundle v1 Contract (2025-11-19)

Scope

Frozen contract for Evidence Bundle v1 covering AdvisoryAI/Concelier/Excititor evidence exports used by air-gap and attestation flows.

Artefact layout

• Tarball name: evidence-bundle-<id>.tar.gz
• Manifest (required): manifest.json
• Payloads (required): observations.ndjson, linksets.ndjson
• Optional: timeline.ndjson (time anchors), transparency.json (Rekor UUID or skip_reason)
• Hash list: hashes.sha256 (sha256 of each file)

manifest.json fields

{
  "bundle_id": "evidence-bundle-m0",
  "version": "1.0.0",
  "created": "2025-11-19T00:00:00Z",
  "tenant": "demo",
  "scope": "vex",
  "inputs": ["sha256:payload-obs", "sha256:payload-linksets"],
  "aoc": {"guardrails": true, "details": ["schema:frozen:1.0", "limits:chunk:max=2000"]}
}

observations.ndjson (sample record)

{"observationId":"obs-ossl-001","advisoryId":"CVE-2024-1234","component":"pkg:deb/openssl@1.1.1w","source":"nvd","fetchedAt":"2025-11-18T12:00:00Z"}

linksets.ndjson (sample record)

{"linksetId":"lnm-ossl-001","advisoryId":"CVE-2024-1234","components":["pkg:deb/openssl@1.1.1w"],"normalized":true,"createdAt":"2025-11-18T12:05:00Z"}

transparency.json (optional)

{"rekor_uuid": null, "skip_reason": "offline"}

Determinism rules

• All timestamps must be UTC RFC3339.
• Ordering: sort NDJSON by advisoryId, then component, ascending.
• Hashes: compute sha256 on raw file bytes; record in hashes.sha256 and in manifest inputs.
• Tenant must be lowercase; include in manifest and any attestation subject claims.

Example bundle (sample)

• Path: docs/samples/evidence-bundle/evidence-bundle-m0.tar.gz
• SHA256: $(cat docs/samples/evidence-bundle/evidence-bundle-m0.tar.gz.sha256 | awk '{print $1}')
• Contains sample manifest/observations/linksets/transparency per above.

Attestation linkage

• See attestation-scope-note.md for required claims.
• Subject digest should reference the tarball sha256; include bundle_id and tenant.

Change log

• 2025-11-19: v1 frozen (initial publication). Add real sample tarball + hashes once produced.