d63af51f84
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Docs CI / lint-and-preview (push) Has been cancelled
oas-ci / oas-validate (push) Has been cancelled
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Policy Simulation / policy-simulate (push) Has been cancelled
devportal-offline / build-offline (push) Has been cancelled
66 lines
2.9 KiB
Markdown
66 lines
2.9 KiB
Markdown
# Evidence Locker
|
|
|
|
Status: Draft (2025-11-26) — DOCS-FORENSICS-53-001.
|
|
|
|
## Purpose
|
|
Capture forensic artefacts (bundles, logs, attestations) in a WORM-friendly store with retention/legal-hold controls.
|
|
|
|
## Storage model
|
|
- Object storage (preferred) with:
|
|
- Bucket per tenant (or tenant prefix) and immutable retention policy.
|
|
- Server-side encryption (KMS) and optional client-side DSSE envelopes.
|
|
- Versioning enabled; deletion disabled during legal hold.
|
|
- Index (Mongo/Postgres) for metadata:
|
|
- `artifactId`, `tenant`, `type` (bundle/attestation/log), `sha256`, `size`, `createdAt`, `retentionUntil`, `legalHold`.
|
|
- `provenance`: source service, job/run ID, DSSE envelope hash, signer.
|
|
- `immutability`: `worm=true|false`, `legalHold=true|false`, `expiresAt`.
|
|
|
|
## Ingest rules
|
|
- Only append; no overwrite. Use content-addressed paths: `tenant/<type>/<sha256>/<filename>`.
|
|
- Every artefact must include:
|
|
- SHA256 (and size)
|
|
- DSSE or Sigstore bundle for attestations
|
|
- Source metadata (service, run ID)
|
|
- Retention/hold directives
|
|
- Reject uploads lacking tenant, hash, or provenance.
|
|
|
|
## Retention & legal hold
|
|
- Default retention per tenant (e.g., 180d); configurable via policy.
|
|
- Legal hold flag prevents deletion/expiry; requires dual-approval to clear.
|
|
- Expiry job runs daily; deletes only items past `retentionUntil` and not on hold; produce audit log.
|
|
|
|
## Access & audit
|
|
- RBAC scopes: `locker:read`, `locker:write`, `locker:hold`.
|
|
- All actions logged with tenant, actor, artefact ID, hash, and result.
|
|
- Provide `/locker/manifest` endpoint to list artefacts by tenant/time/type with pagination.
|
|
|
|
## Verification
|
|
- `locker verify <artifactId>`:
|
|
- Recompute SHA256
|
|
- Verify DSSE/Sigstore signature and signer against trust roots
|
|
- Return status + provenance summary
|
|
- Periodic background verification: sample N artefacts/day; emit `locker.verify.failed` events on mismatch.
|
|
|
|
## Bundle format (minimum)
|
|
- Manifest (`manifest.json`):
|
|
- `artifactId`, `tenant`, `type`, `hashes`, `createdAt`, `retentionUntil`, `legalHold`
|
|
- `provenance` (source, signer, dsseEnvelopeHash)
|
|
- `paths` with bytes and hashes
|
|
- Data files under `data/` (gzip/zstd optional)
|
|
- Signature under `signatures/` if provided
|
|
|
|
## Migration from legacy storage
|
|
- Export legacy artefacts with hashes; import via Locker API with retention/hold fields.
|
|
- Maintain mapping of legacy IDs → new `artifactId` in index.
|
|
- Keep legacy store read-only until verification completes.
|
|
|
|
## Operational runbook (abridged)
|
|
- On ingest failure: log and return 400 with reason; do not partially store.
|
|
- On verification failure: mark artefact `suspect=true`, emit event, and investigate signer and storage integrity.
|
|
- For legal hold requests: require ticket/approval metadata; set `legalHold=true` and extend retention.
|
|
|
|
## References
|
|
- DSSE: in-toto DSSE spec.
|
|
- Sigstore bundles: `docs/forensics/provenance-attestation.md` (pending).
|
|
- Export Center mirror imports and policy attestations feed artefacts here.
|