58 lines
2.1 KiB
Markdown
58 lines
2.1 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/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.
|