59 lines
2.3 KiB
Markdown
59 lines
2.3 KiB
Markdown
# 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
|
||
```json
|
||
{
|
||
"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)
|
||
```json
|
||
{"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)
|
||
```json
|
||
{"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)
|
||
```json
|
||
{"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/modules/evidence-locker/samples/evidence-bundle-m0.tar.gz`
|
||
- SHA256: `$(cat docs/modules/evidence-locker/samples/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.
|
||
- DSSE subject uses the Merkle root derived from `checksums.txt` (sha256 of sorted entry hashes). Record the OCI tarball digest as metadata, not the subject.
|
||
|
||
## Change log
|
||
- 2025-12-04: Updated subject to Merkle root and aligned with EB1–EB10 docs/fixtures.
|
||
- 2025-11-19: v1 frozen (initial publication). Add real sample tarball + hashes once produced.
|