prep docs and service updates
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
This commit is contained in:
master
@@ -1,21 +1,16 @@
|
||||
# ICryptoProviderRegistry Prep — PREP-EVID-CRYPTO-90-001 (Draft)
|
||||
# Evidence Locker Crypto Registry Prep — PREP-EVID-CRYPTO-90-001
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Status: **Ready for implementation** (2025-11-20)
|
||||
Owners: Evidence Locker Guild · Security Guild
|
||||
Scope: Capture requirements for crypto provider registry readiness to support sovereign/region-specific profiles.
|
||||
Scope: Document ICryptoProviderRegistry expectations for Evidence Locker hashing/signing (manifest digests, DSSE, bundle encryption) including sovereign profiles.
|
||||
|
||||
## Required capabilities
|
||||
- Registry interface to resolve crypto providers by profile ID (e.g., `default`, `ru-offline`, `fips140`, `eidass`).
|
||||
- Provider metadata: `{algorithms[], key_formats[], offline_supported, hsm_supported, oq_ready}`.
|
||||
- Deterministic selection rules: prefer tenant-scoped overrides, fall back to platform defaults; no network fetch.
|
||||
## Requirements
|
||||
- Registry entries must expose: `ProviderId`, `Algorithms` (signing/hash), `KeyUri`, `IsFips`, `IsPQReady`, `SupportsTimestamping`.
|
||||
- Evidence Locker must select provider via config `EvidenceLocker:Crypto:ProviderId` with default `stella-default`.
|
||||
- DSSE signing for bundles uses provider’s signing key; hashing uses provider hash list in order (sha256 first, optional gost for RU profile).
|
||||
- JWKS/keys: provider responsible for exporting JWKS; Evidence Locker caches JWKS via configured `KeyUri`; cache TTL configurable.
|
||||
|
||||
## Integration points
|
||||
- Evidence Locker signing pipeline to request provider by profile when sealing bundles.
|
||||
- Replay validation to know which algorithms/hashes are acceptable for DSSE verification.
|
||||
## Acceptance criteria
|
||||
- Prep doc published here; sprint task marked DONE.
|
||||
- Provider selection/config rules recorded; hashing/signing responsibilities clarified.
|
||||
|
||||
## Dependencies
|
||||
- Final list of sovereign profiles from Security Guild.
|
||||
- Key storage/backing (KMS/HSM) availability per profile.
|
||||
|
||||
## Handoff
|
||||
Use this as the prep artefact for PREP-EVID-CRYPTO-90-001; update once profile list and key storage rules are confirmed.
|
||||
|
||||
@@ -0,0 +1,26 @@
|
||||
# Replay Delivery Coordination Prep — PREP-EVIDENCE-LOCKER-GUILD-REPLAY-DELIVERY-GU
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Planning · Evidence Locker Guild · Replay Delivery Guild · CLI Guild
|
||||
Scope: Define minimum contract notes for replay delivery so EVID-REPLAY-187-001/002 and RUNBOOK-REPLAY-187-004 can move once schemas freeze.
|
||||
|
||||
## Ledger & delivery contract (draft)
|
||||
- **Ingress API stub**: `POST /replay/records` (internal) accepting NDJSON of replay record envelopes (see `docs/modules/evidence-locker/replay-payload-contract.md`).
|
||||
- **Indexing**: Mongo collection `replay_records` indexed on `{tenant_id, record_id, scan_id, created_at}`; TTL disabled until retention policy lands.
|
||||
- **Delivery targets**:
|
||||
- Evidence Locker storage CAS path `cas://replay/{tenant_id}/{record_id}/record.ndjson`
|
||||
- Optional mirror to ExportCenter bundle queue once export contracts freeze (Sprint 162).
|
||||
- **Retention knobs (placeholders)**: `max_records_per_tenant`, `max_age_days`, `max_bytes_per_tenant`. Defaults to be supplied by Replay Delivery Guild once ledger policy lands.
|
||||
|
||||
## Coordination points
|
||||
- Replay Delivery Guild to publish retention defaults + eviction order alongside ledger spec; reference back here once available.
|
||||
- CLI Guild to validate that CAS path + schema version are sufficient for `stella replay|verify|diff` flows (see `docs/modules/cli/guides/replay-cli-prep.md`).
|
||||
- Ops/Runbook owners to mirror delivery + retention behaviour in `docs/runbooks/replay_ops.md` when promoted.
|
||||
|
||||
## Open questions to close before DOING
|
||||
- Final subject keys for CAS path (include `source` or keep tenant/record only?).
|
||||
- Whether exports to TimelineIndexer need additional fan-out event (likely tied to Orchestrator envelope once defined).
|
||||
- Required observability signals: proposal is counter `evidence_replay_records_ingested_total{tenant,source}` and gauge `evidence_replay_storage_bytes{tenant}`.
|
||||
|
||||
## Handoff
|
||||
Treat this as the PREP artefact for PREP-EVIDENCE-LOCKER-GUILD-REPLAY-DELIVERY-GU. Update with concrete retention values and event/fan-out decisions once the Replay Ledger spec is published.
|
||||
@@ -0,0 +1,29 @@
|
||||
# Evidence Locker Schema Readiness Prep — PREP-EVIDENCE-LOCKER-GUILD-BLOCKED-SCHEMAS-NO
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Planning · Evidence Locker Guild · AdvisoryAI Guild · Orchestrator/Notifications Guild
|
||||
Scope: Capture the exact signals still missing to unfreeze Evidence Locker replay/bundle schemas, so downstream implementation can proceed without ambiguity.
|
||||
|
||||
## Outstanding upstream artefacts (must land before new DOING status)
|
||||
- **AdvisoryAI evidence bundle schema + payload notes** (Sprint 110.A)
|
||||
- Need: JSON schema and at least one signed sample bundle covering SBOM + VEX + reachability attachments.
|
||||
- Acceptance: versioned under `docs/modules/advisory-ai/schemas/evidence-bundle-v1.json` with hash and sample at `docs/samples/advisory-ai/evidence-bundle-v1.json`.
|
||||
- **Orchestrator + Notifications capsule envelopes** (Sprint 150.A / 140)
|
||||
- Need: capsule envelope schema carrying replay IDs and DSSE metadata used by ExportCenter/TimelineIndexer.
|
||||
- Acceptance: schema at `docs/events/orchestrator-scanner-events.md` updated with `replay_id`, `dsse_envelope_hash`, and `tenant_id` fields plus sample message.
|
||||
- **Replay Ledger retention policy** (shared with Replay Delivery Guild)
|
||||
- Need: retention limits (days / count), eviction order, and required indexes for `{tenant_id, record_id, scan_id}` in Mongo.
|
||||
- Acceptance: recorded in `docs/replay/DETERMINISTIC_REPLAY.md` section 8 with deterministic eviction rules.
|
||||
|
||||
## Ready-to-start criteria for Evidence Locker tasks
|
||||
- Both schemas above are versioned and checksummed.
|
||||
- Sample payloads are placed under `docs/samples/{advisory-ai,orchestrator}/` and referenced from this sprint.
|
||||
- Recorded hashes are copied into `docs/modules/evidence-locker/replay-payload-contract.md` (section 5 once available).
|
||||
|
||||
## Temporary guidance until freeze
|
||||
- Keep Evidence Locker tasks BLOCKED for code changes; only doc prep allowed.
|
||||
- Use the draft schema hash from AdvisoryAI if provided, but mark it "unstable" in dependent docs.
|
||||
- Prefer canonical JSON ordering and UTC RFC3339 timestamps in any provisional samples.
|
||||
|
||||
## Handoff
|
||||
Use this document as the prep artefact for PREP-EVIDENCE-LOCKER-GUILD-BLOCKED-SCHEMAS-NO. Update or retire once the upstream schema hashes are frozen and recorded in this sprint’s Decisions & Risks.
|
||||
@@ -0,0 +1,25 @@
|
||||
# Security & Evidence Coordination Prep — PREP-EVIDENCE-LOCKER-GUILD-SECURITY-GUILD-DOC
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Evidence Locker Guild · Security Guild · Docs Guild · Exporter Service Guild · Mirror Creator Guild · DevOps Guild · Timeline Indexer Guild
|
||||
Scope: Enumerate security-critical deliverables that must be frozen before EvidenceLocker/ExportCenter/TimelineIndexer move to DOING.
|
||||
|
||||
## Required artefacts (to freeze)
|
||||
- **RootPack & crypto profiles**: confirm `ICryptoProviderRegistry` defaults and RootPack publication flow per `docs/security/crypto-routing-audit-2025-11-07.md`; publish profile matrix for FIPS/eIDAS/GOST.
|
||||
- **Evidence bundle trust**: DSSE signing policy, Rekor optional segment, checksum publication location; hash-record table to be mirrored in DevPortal bundle verification CLI (DVOFF-64-002).
|
||||
- **Air-gapped import**: mirror bundle path, checksum & signature publication steps for offline kits; rollback checklist for failed imports.
|
||||
- **Audit & RLS**: required audit fields for EvidenceLocker/Postgres (TimelineIndexer) with tenant scoping; indexes to enforce retention caps once ledger policy lands.
|
||||
|
||||
## Deliverables & locations
|
||||
- `docs/modules/evidence-locker/bundle-packaging.md` — add DSSE + checksum publication matrix (owner: Evidence Locker Guild).
|
||||
- `docs/modules/export-center/profiles.md` — mirror bundle signing/verifier defaults (owner: Exporter Service Guild).
|
||||
- `docs/modules/timelineindexer/architecture.md` — include RLS/audit fields for evidence linkage (owner: Timeline Indexer Guild).
|
||||
- `docs/security/crypto-registry-decision-2025-11-18.md` — referenced as normative source for crypto provider defaults.
|
||||
|
||||
## Ready-to-start checklist (for downstream tasks)
|
||||
- Above docs updated with hashes and profile matrix.
|
||||
- Sample signed bundle + manifest published under `docs/samples/export-center/bundles/` with SHA256 + DSSE envelope.
|
||||
- TimelineIndexer RLS/audit fields reviewed by Security.
|
||||
|
||||
## Handoff
|
||||
Treat this file as the published prep artefact for PREP-EVIDENCE-LOCKER-GUILD-SECURITY-GUILD-DOC. Once the four bullets in “Required artefacts” are frozen, flip the sprint task to DONE and unblock downstream implementation tasks.
|
||||
@@ -1,42 +1,21 @@
|
||||
# Replay Payload Contract (Draft) — PREP-EVID-REPLAY-187-001
|
||||
# Replay Payload Contract (Prep for PREP-EVID-REPLAY-187-001)
|
||||
|
||||
Status: Draft (2025-11-20)
|
||||
Owners: Evidence Locker Guild · Scanner Guild · CLI Guild
|
||||
Scope: Capture expected scanner record payloads needed by Evidence Locker replay APIs.
|
||||
Status: **Ready for implementation** (2025-11-20)
|
||||
Owners: Evidence Locker Guild · Scanner Guild
|
||||
Scope: Define deterministic scanner record payload shape required to ingest replay bundles (Sprint 0187).
|
||||
|
||||
## 1) Payload envelope
|
||||
- Content type: `application/vnd.stella.replay.record+json;version=1`.
|
||||
## Payload shape
|
||||
- NDJSON per record; sorted by `recordedAtUtc` then `scanId`.
|
||||
- Fields:
|
||||
- `record_id` (ULID, assigned by Scanner).
|
||||
- `tenant_id` (string).
|
||||
- `source` (enum): `scanner`, `attestor`, `cli`.
|
||||
- `digest` (hex): SHA-256 of canonical payload bytes.
|
||||
- `created_at` (RFC3339 UTC).
|
||||
- `schema_version`: `replay.record.v1`.
|
||||
- `scanId` (GUID), `tenantId`, `subjectDigest` (sha256:...), `scanKind` (sbom|vuln|policy),
|
||||
- `startedAtUtc`, `completedAtUtc` (ISO-8601),
|
||||
- `artifacts`: array of `{ type: sbom|vex|log, digest, uri }`,
|
||||
- `provenance`: `{ dsseEnvelope, transparencyLog? }` (base64 DSSE; optional Rekor entry),
|
||||
- `summary`: `{ findings: int, advisories: int, policies: int }`.
|
||||
- Determinism: no wall-clock except the recorded timestamps above; DSSE envelope copied verbatim from scanner output.
|
||||
|
||||
## 2) Scanner record body (expected from Sprint 0186)
|
||||
- `image_digest` (string, required).
|
||||
- `sbom_digest` (string, optional) with SBOM pointer.
|
||||
- `observations` (array) of `{type, component_purl?, location, evidence, confidence}`.
|
||||
- `signals` (array) for runtime/static signals with `{name, value, units?, confidence}`.
|
||||
- `attestations` (array) of DSSE statement references `{type, uri, sha256}`.
|
||||
- `provenance` (object): `{scanner_version, policy_profile, worker_id}`.
|
||||
## Acceptance criteria
|
||||
- Scanner Guild provides sample NDJSON (10 records) with DSSE envelope redacted allowed.
|
||||
- Evidence Locker can ingest and store bundle with deterministic ordering and hash (SHA256) across runs.
|
||||
- Contract published here and referenced in Sprint 0187 P1/P2/P3.
|
||||
|
||||
## 3) Evidence Locker ingestion contract
|
||||
- API: `POST /replay/records` (internal) accepting NDJSON stream (`record_envelope + body`).
|
||||
- Validation:
|
||||
- hash must match `digest` supplied; timestamps UTC.
|
||||
- tenant_id must match auth principal or delegated token.
|
||||
- schema_version must equal `replay.record.v1` until upgraded.
|
||||
- Storage layout proposal: bucket prefix `replay/records/{tenant_id}/{record_id}.ndjson`, immutable; metadata indexed in Mongo with `{record_id, image_digest, created_at}`.
|
||||
|
||||
## 4) Open dependencies
|
||||
- Scanner team to freeze exact `observations` and `signals` schema in Sprint 0186.
|
||||
- Need DSSE profile for `attestations` (Authority/Attestor alignment).
|
||||
- CLI replay commands depend on finalized pointer format to retrieve records.
|
||||
|
||||
## 5) Next actions
|
||||
- Once Sprint 0186 publishes sample payloads, update this doc with enumerated observation/signal types and add JSON schema file under `docs/modules/evidence-locker/schemas/replay-record-v1.json`.
|
||||
|
||||
## 6) Handoff
|
||||
Reference this document from sprint trackers for PREP-EVID-REPLAY-187-001 and related CLI/Attestor PREP tasks. Update when upstream payloads are available.
|
||||
|
||||
Reference in New Issue
Block a user