up

docs/forensics/evidence-locker.md

@@ -0,0 +1,65 @@
+# 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.

docs/forensics/provenance-attestation.md

@@ -1,15 +1,20 @@
 # Provenance & Attestation Reference
 
+> **Imposed rule:** All exported evidence must ship with DSSE + transparency proof bundles; unsigned or proof-less artifacts are rejected at ingress and may not be stored in the Evidence Locker.
+
 This guide explains how StellaOps generates, signs, verifies, and distributes DSSE attestations for SBOMs, policy evaluations, and runtime evidence.
 
-## 1. Attestation Workflow
+## 1. Attestation Workflow (online and offline)
 
-1. **Scanner** produces signed payload requests (SBOM, report metadata).
-2. **Signer** authenticates the caller, verifies release integrity, and issues DSSE bundles (keyless or KMS-backed).
-3. **Attestor** submits bundles to Rekor v2, caches inclusion proofs, and serves verification packages.
-4. **Consumers** (Export Center, Evidence Locker, CLI, Policy Engine) fetch bundles for verification.
+1. **Producer** (Scanner, Policy Engine, runtime probes) emits a payload and a request to sign.
+2. **Signer** authenticates the caller, validates supply-chain policy (release integrity, image pinning), then signs using keyless or tenant KMS keys.
+3. **Attestor** wraps the payload in DSSE, records it in Rekor v2 (when online), persists the bundle plus inclusion proof, and exposes a verification package API.
+4. **Export Center** and **Evidence Locker** embed the bundle and proof into export artifacts for offline replay; CLI retrieves the same package via `stella attest fetch`.
+5. **Verifiers** (CLI, Policy Engine, auditors) validate signature roots, Rekor proof, and optional transparency witness endorsements.
 
-## 2. DSSE Payload Types
+## 2. DSSE Payload Types & Schemas
+
+Supported payload types (all versioned and protobuf/JSON dual-encoded):
 
 - `StellaOps.BuildProvenance@1`
 - `StellaOps.SBOMAttestation@1`
@@ -17,25 +22,55 @@ This guide explains how StellaOps generates, signs, verifies, and distributes DS
 - `StellaOps.PolicyEvaluation@1`
 - `StellaOps.VEXAttestation@1`
 - `StellaOps.RiskProfileEvidence@1`
+- `StellaOps.PromotionAttestation@1` (predicate `stella.ops/promotion@v1`, see `docs/release/promotion-attestations.md`)
 
-Schemas live under `src/Attestor/StellaOps.Attestor.Types` and are documented in module architecture guides.
+Schema sources: `src/Attestor/StellaOps.Attestor.Types` and module dossiers. All payloads include:
 
-## 3. Verification
+- `subject` (digest + PURL/NEVRA coordinates)
+- `timestamp` (UTC, ISO-8601)
+- `producer` (service + version)
+- `critical` block (policy version, scanner defs, reachability context)
+- `materials` (SBOM/VEX references) and optional `auxiliary_proofs`
 
-- CLI command `stella attest verify` requests proofs from Attestor.
-- Services embed Rekor UUID/index and DSSE digests in their APIs for downstream verification.
-- Verification pipeline checks signature trust roots, Rekor inclusion proofs, and transparency witness endorsements when enabled.
+## 3. Signing & storage controls
 
-## 4. Offline/air-gap considerations
+- **Key policy:** Short-lived OIDC keyless by default; tenant KMS allowed; Ed25519 and ECDSA P-256 supported.
+- **Inclusion:** Rekor v2 UUID + log index cached; when offline, the Attestor stamps a `transparency_pending` marker to be replayed later.
+- **WORM:** Evidence Locker keeps immutable copies; retention and legal hold are enforced per tenant and surfaced in `docs/forensics/evidence-locker.md`.
+- **Redaction:** Sensitive fields (secrets, PII) must be excluded at payload creation; the signer refuses payloads marked `pii=true` without a redaction ticket.
 
-- Export Center bundles incorporate attestations and proofs for offline verification.
-- Evidence Locker stores immutable attestation bundles with retention policies.
+## 4. Verification workflow
 
-## 5. References
+Command-line (online or offline bundle):
+
+```sh
+stella attest verify \
+  --bundle path/to/bundle.dsse.json \
+  --rekor-root pubkeys/rekor.pub \
+  --fulcio-root pubkeys/fulcio.pub \
+  --certificate-chain pubkeys/issuer-chain.pem
+```
+
+Verification steps performed by services and CLI:
+
+- Validate DSSE signature against Fulcio/tenant roots and certificate policies.
+- Confirm subject digest matches expected container/image/SBOM digest.
+- Check Rekor inclusion proof and (if present) transparency witness signatures.
+- Enforce freshness: reject bundles older than `attestation.max_age_days` (tenant policy).
+- Record verification result into Timeline events for auditability.
+
+## 5. Offline / air-gap posture
+
+- Export Center emits self-contained bundles (`*.dsse.json`, `rekor-proof.json`, `cert-chain.pem`) plus a verification manifest for deterministic replay.
+- CLI `stella attest verify --bundle bundle.dsse.json --offline` skips Rekor lookups and relies on embedded proofs.
+- When connectivity returns, the Attestor replays pending `transparency_pending` entries and updates Evidence Locker indexes; Timeline events capture the replay.
+
+## 6. References
 
 - `docs/modules/signer/architecture.md`
 - `docs/modules/attestor/architecture.md`
 - `docs/modules/export-center/architecture.md`
 - `docs/modules/policy/architecture.md`
 - `docs/modules/telemetry/architecture.md`
+- `docs/forensics/evidence-locker.md`
 - `src/Provenance/StellaOps.Provenance.Attestation`

docs/forensics/timeline.md

@@ -1,5 +1,7 @@
 # Timeline Forensics Guide
 
+> **Imposed rule:** Timeline is append-only; events may not be deleted or rewritten. Redactions require creating a compensating `redaction_notice` event that references the original ULID.
+
 The Timeline Indexer service aggregates structured events (scanner runs, policy verdicts, runtime posture, evidence locker activity) so operators can audit changes over time. This guide summarises the event schema, query surfaces, and integration points.
 
 ## 1. Event Model
@@ -15,17 +17,45 @@ The Timeline Indexer service aggregates structured events (scanner runs, policy
 
 Events are stored append-only with tenant-specific partitions. Producers include Scanner WebService, Policy Engine, Zastava Observer, Evidence Locker, and Notify.
 
+### Event kinds (normative)
+
+- `scan.completed` – scanner job finished; includes SBOM digest, findings counts, determinism score.
+- `policy.verdict` – policy engine decision with overlay cache version and allow/deny rationale.
+- `attestation.verified` – attestation verification result with Rekor UUID and bundle digest.
+- `evidence.ingested` – Evidence Locker write with WORM vault identifier.
+- `notify.sent` – outbound notification with target channel and template id.
+- `runtime.alert` – runtime enforcement or observation event from Zastava Observer.
+- `redaction_notice` – compensating entry when data is logically withdrawn; must include `supersedes` ULID.
+
 ## 2. APIs
 
 - `GET /api/v1/timeline/events` – paginated event stream with filters (tenant, category, time window, correlation IDs).
 - `GET /api/v1/timeline/events/{id}` – fetch single event payload.
 - `GET /api/v1/timeline/export` – NDJSON export for offline review.
 
+API headers: `X-Stella-Tenant`, optional `X-Stella-TraceId`, and `If-None-Match` for cache revalidation.
+
 ## 3. Query Tips
 
 - Use `category` + `trace_id` to follow a scan-to-policy-to-notification flow.
 - Combine `tenant` and `timestamp` filters for SLA audits.
 - CLI command `stella timeline list` mirrors the API for automation.
+- For WORM verification, filter `category=evidence` and join on Evidence Locker bundle digest.
+- Use `category=attestation.verified` and `details.rekor_uuid` to reconcile transparency proofs.
+
+Example queries
+
+```sh
+# Recent scan → policy → notify chain for a digest
+stella timeline list --tenant acme --category scan.completed --subject sha256:abc... --limit 5
+stella timeline list --tenant acme --category policy.verdict --trace-id <trace>
+stella timeline list --tenant acme --category notify.sent --trace-id <trace>
+
+# Export window for audit
+curl -H "X-Stella-Tenant: acme" \
+  "https://console.example/api/v1/timeline/export?from=2025-11-01T00:00:00Z&to=2025-11-02T00:00:00Z" \
+  -o timeline-2025-11-01.ndjson
+```
 
 ## 4. Integration
 
@@ -33,6 +63,10 @@ Events are stored append-only with tenant-specific partitions. Producers include
 - Notifier creates acknowledgement events for incident workflows.
 - Offline kits package timeline exports for compliance reviews.
 
+Retention: events are retained per-tenant for at least `timeline.retention_days` (default 400 days) and replicated to cold storage weekly. Index rebuilds must preserve ordering and ULIDs.
+
+Privacy/PII: producers must redact PII before emission; once emitted, redactions occur via `redaction_notice` only.
+
 ## 5. References
 
 - `docs/modules/telemetry/architecture.md`