168 lines
12 KiB
Markdown
168 lines
12 KiB
Markdown
# Implementation plan — Attestor
|
||
|
||
## Delivery phases
|
||
- **Phase 1 – Foundations**
|
||
Build the Attestor service skeleton, DSSE bundle ingestion, mTLS/OpTok enforcement, Rekor v2 client, and cache the `{uuid,index,proof}` tuple. Publish base API (`POST /rekor/entries`, `GET /entries/{uuid}`) and Mongo schemas.
|
||
- **Phase 2 – Policies & UI**
|
||
Deliver verification policy authoring (Policy Studio integration), console views (evidence browser, verification reports, issuer management), and CLI verbs (`stella attest sign|verify|list|fetch`).
|
||
- **Phase 3 – Scan & VEX support**
|
||
Accept SBOM, ScanResults, VEX, and PolicyEvaluation predicates; integrate with Scanner, Export Center, Excititor, and Policy Engine pipelines. Ensure AOC invariants on ingestion.
|
||
- **Phase 4 – Transparency & keys**
|
||
Add multi-log submission (primary + mirror), witness endorsements, KMS/HSM/FIDO2 drivers, key rotation/revocation workflows, and audit trails.
|
||
- **Phase 5 – Bulk & air gap**
|
||
Implement batch submission/verification, DSSE archival to CAS/object storage, export/import bundles for Offline Kit, and mirror transparency log snapshots.
|
||
- **Phase 6 – Performance & hardening**
|
||
Optimise cache usage, parallel verification (target ≥1 k envelopes/minute per worker), extend observability (metrics/logs/traces), fuzz parsers, and finalise incident playbooks.
|
||
|
||
## Work breakdown
|
||
- **Attestor service & libraries**
|
||
- DSSE validation pipeline (payload whitelist, signature verification, trust roots).
|
||
- Rekor client with inclusion-proof acquisition, retry/backoff, mirroring controls.
|
||
- Mongo repositories for entries, dedupe, audit; CAS storage for DSSE envelopes.
|
||
- Batch submission/verification APIs, verification cache, deterministic serialization.
|
||
- Observability hooks: metrics (`attestor_submission_total`, `attestor_verify_seconds`), structured logs, OpenTelemetry traces.
|
||
- **Signer & Authority integration**
|
||
- Enforce mTLS peer validation, Authority scope mapping (`attestor.write`, `attestor.verify`), and DPoP binding.
|
||
- Provide signer identity attestation metadata consumed by Attestor.
|
||
- **Policy & Console**
|
||
- Extend Policy Studio with `VerificationPolicy` authoring, approvals, and simulated results.
|
||
- Console workflows: Evidence browser, verification reports, chain-of-custody graph, key management UI, bulk verification screens.
|
||
- **CLI & SDK**
|
||
- `stella attest` command group (sign/verify/list/fetch/key management) with DSSE canonicalisation and cosign interoperability.
|
||
- SDK helpers for DSSE envelope creation, verification, and proof inspection.
|
||
- **Export Center & Offline Kit**
|
||
- Export Center adapters for attestation bundles; CLI/Console flows to export & import evidence in air-gapped environments.
|
||
- Offline Kit scripts for replaying verification, mirroring transparency logs, and reporting gaps.
|
||
- **Security & key management**
|
||
- KMS/HSM/FIDO2 driver abstraction, key rotation and revocation runbooks, witness endorsements, and revocation telemetry.
|
||
- **Docs & training**
|
||
- Update module dossier (overview, architecture, implementation plan), key management guides, transparency reference, CLI/Console documentation, and air-gap runbooks.
|
||
|
||
## Cross-module dependencies
|
||
- **Policy Studio / Policy Engine:** verification policy artefacts, explain integration, remediation hints.
|
||
- **Export Center:** attestation bundle export/import, provenance linking.
|
||
- **Authority & Tenancy:** scopes, identity attestations, tenant-aware issuer catalogues.
|
||
- **Notifications:** attestation success/failure events, key rotation alerts.
|
||
- **Observability:** dashboards and alerting for signing/verification pipelines.
|
||
|
||
## Acceptance criteria
|
||
- Service ingests DSSE envelopes for all supported predicate types, logs them to configured transparency logs, and returns proofs with deterministic hashes.
|
||
- Verification APIs/CLI/UI validate signatures, inclusion proofs, and policy compliance; cached verification accelerates repeated checks.
|
||
- Verification policies gate attestation usage, enforcing issuer, freshness, signature count, and witness requirements.
|
||
- Export Center and Offline Kit workflows bundle attestations and replay verification offline.
|
||
- Observability coverage includes metrics, traces, logs, audit events, and alert triggers for key compromise, log outages, and verification failure spikes.
|
||
- Performance target met (≥1 k envelopes/minute per worker) with horizontal scaling.
|
||
|
||
## Risks & mitigations
|
||
- **Key compromise or leakage:** enforce hardware-backed keys, rotation procedures, revocation checks, and incident runbooks.
|
||
- **Parser bugs / malformed DSSE:** fuzz DSSE and predicate schemas, strict schema validation, fail closed.
|
||
- **Transparency outage:** mirror logs, support witness endorsements, queue submissions for retry with exponential backoff.
|
||
- **Policy complexity:** ship curated starter policies, provide simulation tooling, and document common scenarios.
|
||
- **Offline gaps:** archive bundles and proof material, surface gaps to operators, and document compensating controls.
|
||
|
||
## Test strategy
|
||
- **Unit:** DSSE validation, Rekor client, dedupe logic, key drivers, policy enforcement.
|
||
- **Integration:** submit/verify flows across predicate types, multi-log publishing, batch operations, CLI/UI end-to-end exercises.
|
||
- **Security:** tenant isolation, scope enforcement, key rotation regression, tamper detection.
|
||
- **Performance:** throughput benchmarks, cache hit-rate monitoring, large batch verification.
|
||
- **Chaos:** inject Rekor outages, network failures, corrupt bundles; ensure graceful degradation and auditable alerts.
|
||
|
||
## Definition of done
|
||
- Phased milestones delivered with telemetry, documentation, and runbooks in place.
|
||
- CLI/Console parity verified; Offline Kit procedures validated in sealed environment.
|
||
- Cross-module dependencies acknowledged in ./TASKS.md and ../../TASKS.md.
|
||
- Documentation set refreshed (overview, architecture, key management, transparency, CLI/UI) with imposed rule statement.
|
||
|
||
## Sprint alignment (2025-11-30)
|
||
- Docs sprint: `docs/implplan/SPRINT_0313_0001_0001_docs_modules_attestor.md`; statuses mirrored in `docs/modules/attestor/TASKS.md`.
|
||
- Observability evidence stub lives in `operations/observability.md` with Grafana placeholder under `operations/dashboards/`; finalize after next demo outputs.
|
||
- ATTESTOR-OPS-0001 remains BLOCKED until next demo provides observability data; update sprint/TASKS when available.
|
||
|
||
---
|
||
|
||
## Sprint readiness tracker
|
||
|
||
> Last updated: 2025-11-27 (ATTESTOR-ENG-0001)
|
||
|
||
This section maps delivery phases to implementation sprints and tracks readiness checkpoints.
|
||
|
||
### Phase 1 — Foundations
|
||
| Task ID | Status | Sprint | Notes |
|
||
|---------|--------|--------|-------|
|
||
| ATTEST-73-001 | ✅ DONE (2025-11-25) | SPRINT_110_ingestion_evidence | Attestation claims builder verified; TRX archived. |
|
||
| ATTEST-73-002 | ✅ DONE (2025-11-25) | SPRINT_110_ingestion_evidence | Internal verify endpoint validated; TRX archived. |
|
||
| ATTEST-PLAN-2001 | ✅ DONE (2025-11-24) | SPRINT_0200_0001_0001_attestation_coord | Coordination plan published at `docs/modules/attestor/prep/2025-11-24-attest-plan-2001.md`. |
|
||
| ELOCKER-CONTRACT-2001 | ✅ DONE (2025-11-24) | SPRINT_0200_0001_0001_attestation_coord | Evidence Locker contract published. |
|
||
| KMSI-73-001/002 | ✅ DONE (2025-11-03) | SPRINT_100_identity_signing | KMS key management and FIDO2 profile. |
|
||
|
||
**Checkpoint:** Foundations complete — service skeleton, DSSE ingestion, Rekor client, and cache layer operational.
|
||
|
||
### Phase 2 — Policies & UI
|
||
| Task ID | Status | Sprint | Notes |
|
||
|---------|--------|--------|-------|
|
||
| POLICY-ATTEST-73-001 | ⏳ BLOCKED | SPRINT_0123_0001_0001_policy_reasoning | VerificationPolicy schema/persistence; awaiting prep artefact finalization. |
|
||
| POLICY-ATTEST-73-002 | ⏳ BLOCKED | SPRINT_0123_0001_0001_policy_reasoning | Editor DTOs/validation; depends on 73-001. |
|
||
| POLICY-ATTEST-74-001 | ⏳ BLOCKED | SPRINT_0123_0001_0001_policy_reasoning | Surface attestation reports; depends on 73-002. |
|
||
| POLICY-ATTEST-74-002 | ⏳ BLOCKED | SPRINT_0123_0001_0001_policy_reasoning | Console report integration; depends on 74-001. |
|
||
| CLI-ATTEST-73-001 | ⏳ BLOCKED | SPRINT_0201_0001_0001_cli_i | `stella attest sign` command; blocked by scanner analyzer issues. |
|
||
| CLI-ATTEST-73-002 | ⏳ BLOCKED | SPRINT_0201_0001_0001_cli_i | `stella attest verify` command; depends on 73-001. |
|
||
| CLI-ATTEST-74-001 | ⏳ BLOCKED | SPRINT_0201_0001_0001_cli_i | `stella attest list` command; depends on 73-002. |
|
||
| CLI-ATTEST-74-002 | ⏳ BLOCKED | SPRINT_0201_0001_0001_cli_i | `stella attest fetch` command; depends on 74-001. |
|
||
|
||
**Checkpoint:** Policy Studio integration and Console verification views blocked on upstream schema/API deliverables.
|
||
|
||
### Phase 3 — Scan & VEX support
|
||
| Task ID | Status | Sprint | Notes |
|
||
|---------|--------|--------|-------|
|
||
| ATTEST-01-003 | ✅ DONE (2025-11-23) | SPRINT_110_ingestion_evidence | Excititor attestation payloads shipped on frozen bundle v1. |
|
||
| CONCELIER-ATTEST-73-001 | ✅ DONE (2025-11-25) | SPRINT_110_ingestion_evidence | Core/WebService attestation suites executed. |
|
||
| CONCELIER-ATTEST-73-002 | ✅ DONE (2025-11-25) | SPRINT_110_ingestion_evidence | Attestation verify endpoint validated. |
|
||
|
||
**Checkpoint:** Scan/VEX attestation payloads integrated; ingestion flows verified.
|
||
|
||
### Phase 4 — Transparency & keys
|
||
| Task ID | Status | Sprint | Notes |
|
||
|---------|--------|--------|-------|
|
||
| NOTIFY-ATTEST-74-001 | ✅ DONE (2025-11-16) | SPRINT_0171_0001_0001_notifier_i | Notification templates for verification/key events created. |
|
||
| NOTIFY-ATTEST-74-002 | 📝 TODO | SPRINT_0171_0001_0001_notifier_i | Wire notifications to key rotation/revocation; blocked on payload localization freeze. |
|
||
| ATTEST-REPLAY-187-003 | 📝 TODO | SPRINT_187_evidence_locker_cli_integration | Wire Attestor/Rekor anchoring for replay manifests. |
|
||
|
||
**Checkpoint:** Key event notifications partially complete; witness endorsements and rotation workflows pending.
|
||
|
||
### Phase 5 — Bulk & air gap
|
||
| Task ID | Status | Sprint | Notes |
|
||
|---------|--------|--------|-------|
|
||
| EXPORT-ATTEST-74-001 | ⏳ BLOCKED | SPRINT_0162_0001_0001_exportcenter_i | Export job producing attestation bundles; needs EvidenceLocker DSSE layout. |
|
||
| EXPORT-ATTEST-74-002 | ⏳ BLOCKED | SPRINT_0162_0001_0001_exportcenter_i | CI/offline kit integration; depends on 74-001. |
|
||
| EXPORT-ATTEST-75-001 | ⏳ BLOCKED | SPRINT_0162_0001_0001_exportcenter_i | CLI `stella attest bundle verify/import`; depends on 74-002. |
|
||
| EXPORT-ATTEST-75-002 | ⏳ BLOCKED | SPRINT_0162_0001_0001_exportcenter_i | Offline kit integration; depends on 75-001. |
|
||
|
||
**Checkpoint:** Bulk/air-gap workflows blocked awaiting Export Center contracts.
|
||
|
||
### Phase 6 — Performance & hardening
|
||
| Task ID | Status | Sprint | Notes |
|
||
|---------|--------|--------|-------|
|
||
| ATTEST-73-003 | 📝 TODO | SPRINT_302_docs_tasks_md_ii | Evidence documentation; waiting on ATEL0102 evidence. |
|
||
| ATTEST-73-004 | 📝 TODO | SPRINT_302_docs_tasks_md_ii | Extended documentation; depends on 73-003. |
|
||
|
||
**Checkpoint:** Performance benchmarks and incident playbooks pending; observability coverage to be validated.
|
||
|
||
---
|
||
|
||
### Overall readiness summary
|
||
|
||
| Phase | Status | Blocking items |
|
||
|-------|--------|----------------|
|
||
| **1 – Foundations** | ✅ Complete | — |
|
||
| **2 – Policies & UI** | ⏳ Blocked | POLICY-ATTEST-73-001 prep; CLI build issues |
|
||
| **3 – Scan & VEX** | ✅ Complete | — |
|
||
| **4 – Transparency & keys** | 🔄 In progress | NOTIFY-ATTEST-74-002 payload freeze |
|
||
| **5 – Bulk & air gap** | ⏳ Blocked | EXPORT-ATTEST-74-001 contract |
|
||
| **6 – Performance** | 📝 Not started | Upstream phase completion |
|
||
|
||
### Next actions
|
||
1. Track POLICY-ATTEST-73-001 prep artefact publication (Sprint 0123).
|
||
2. Resolve CLI build blockers to unblock CLI-ATTEST-73-001 (Sprint 0201).
|
||
3. Complete NOTIFY-ATTEST-74-002 wiring once payload localization freezes (Sprint 0171).
|
||
4. Monitor Export Center contract finalization for Phase 5 tasks (Sprint 0162).
|