44 lines
1.8 KiB
Markdown
44 lines
1.8 KiB
Markdown
# Excititor Attestation Plan (Sprint 110)
|
|
|
|
## Goals
|
|
- Align Excititor chunk API and attestation envelopes with Evidence Locker contract.
|
|
- Provide offline-ready chunk submission/attestation flow for VEX evidence.
|
|
|
|
## Chunk API shape (`/vex/evidence/chunks`)
|
|
- POST body (NDJSON, deterministic order by `chunk_id`):
|
|
```json
|
|
{
|
|
"chunk_id": "uuid",
|
|
"tenant": "acme",
|
|
"source": "ghsa",
|
|
"schema": "stellaops.vex.chunk.v1",
|
|
"items": [ {"advisory_id":"GHSA-123","status":"affected","purl":"pkg:npm/foo@1.0.0"} ],
|
|
"provenance": {"fetched_at":"2025-11-20T00:00:00Z","artifact_sha":"abc"}
|
|
}
|
|
```
|
|
- At submission, Excititor returns `chunk_digest` (sha256 of canonical JSON) and queue id.
|
|
|
|
## Attestation envelope
|
|
- Subject: `chunk_digest` from above.
|
|
- Predicates attached:
|
|
- `stellaops.vex.chunk.meta.v1` (tenant, source, schema version, item count).
|
|
- `stellaops.vex.chunk.integrity.v1` (sha256 per item block, canonical order).
|
|
- Optional `stellaops.transparency.v1` (Rekor UUID/logIndex) when online.
|
|
- Envelope format: DSSE using Evidence Locker provider registry; signing profile mirrors Evidence Locker bundle profile for tenant.
|
|
|
|
## DSSE bundling rules
|
|
- Deterministic JSON (sorted keys) before hashing.
|
|
- Canonical NDJSON for chunk payload; no gzip inside envelope.
|
|
- Attach verification report alongside attestation as `chunk-verify.json` (hashes + signature check results).
|
|
|
|
## Sample payloads
|
|
- `docs/modules/excititor/samples/chunk-sample.ndjson`
|
|
- `docs/modules/excititor/samples/chunk-attestation-sample.json`
|
|
|
|
## Integration points
|
|
- Evidence Locker contract v1 (see `docs/modules/evidence-locker/attestation-contract.md`).
|
|
- Concelier LNM schemas (observations remain aggregation-only; attestation is evidence, not merge).
|
|
|
|
## Ownership
|
|
- Excititor Guild (primary); Evidence Locker Guild reviewer.
|