git.stella-ops.org/docs/modules/attestor/implementation_plan.md

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 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).