master
7b5bdcf4d3
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes. - Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes. - Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables. - Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
62 lines
4.3 KiB
Markdown
62 lines
4.3 KiB
Markdown
# Implementation plan — Signer
|
||
|
||
## Delivery phases
|
||
- **Phase 1 – Core service & PoE**
|
||
Harden OpTok validation, Proof-of-Entitlement (PoE) checks, quota enforcement, scanner release verification, and DSSE signing pipeline (keyless + keyful).
|
||
- **Phase 2 – Export Center integration**
|
||
Produce signing bundles with provenance manifests for Export Center, deliver cosign-compatible outputs, and document verification workflows for offline exports.
|
||
- **Phase 3 – Attestor alignment**
|
||
Emit DSSE envelopes, metadata, and signer identity information required by Attestor (key metadata, certificate chains, bundle hashes); expose audit APIs.
|
||
- **Phase 4 – Observability & resilience**
|
||
Complete telemetry, throttling dashboards, audit trails, fallback key rotation, and offline kit packaging.
|
||
|
||
## Work breakdown
|
||
- **Authentication & entitlement**
|
||
- Enforce Authority-issued DPoP/mTLS tokens with `signer.sign` scope and tenant checks.
|
||
- Integrate PoE introspection (cloud licensing) and plan quotas.
|
||
- Validate scanner release signature via OCI referrers before signing reports/SBOMs.
|
||
- **Signing pipeline**
|
||
- Implement DSSE canonicalisation, keyless (Fulcio) and keyful (KMS/HSM/FIDO2) signing.
|
||
- Support multi-signature output, certificate chain embedding, and deterministic bundle hashing.
|
||
- Provide policy metadata (policy digest, view set) for report predicates.
|
||
- **Integrations**
|
||
- Coordinate with Attestor on bundle schema, signer identity payload, and error codes.
|
||
- Expose Export Center-ready signing API (`/sign/export`) that returns manifest + signature tuple.
|
||
- Surface CLI flows (`stella sign sbom/report`, offline verification helpers).
|
||
- **Security & key management**
|
||
- Key rotation and revocation runbooks; separation of signing keys per tenancy/plan.
|
||
- Hardware-backed key support (HSM/FIDO2) with audit logging and attested builds.
|
||
- **Observability**
|
||
- Metrics: signing latency, PoE failures, quota hits, key usage distribution.
|
||
- Structured logs with trace/context IDs, subject digests, issuer mode, decision outcome.
|
||
- Alerts for PoE outages, key exhaustion, quota breach, signing failure spikes.
|
||
- **Documentation & runbooks**
|
||
- Update README/architecture/implementation plan, operator runbooks, offline verification guidance, and CLI reference.
|
||
|
||
## Acceptance criteria
|
||
- Signer only signs requests that satisfy OpTok, PoE, quota, and scanner provenance checks.
|
||
- DSSE outputs (keyless + keyful) verify with standard cosign tooling; Attestor logs them without additional transformation.
|
||
- Export Center receives signed bundles, provenance manifests, and signature metadata to package exports deterministically.
|
||
- Audit logs capture every signing request with tenant, issuer, subject digest, PoE state, and key source.
|
||
- Observability dashboards/alerts reflect latency, failure rate, PoE status, and quota usage.
|
||
- CLI/Offline workflows verify signatures using Offline Kit trust roots.
|
||
|
||
## Risks & mitigations
|
||
- **PoE/entitlement outages:** cache last-known entitlement within TTL, provide emergency bypass toggles with audit trail.
|
||
- **Key compromise:** enforce hardware-backed keys, rotation cadence, immediate revocation workflow, incident runbook.
|
||
- **Release verification failures:** maintain allowlist for trusted scanner digests, fallback to manual approval with audit.
|
||
- **Determinism drift:** canonicalise JSON, lock timestamp sources, regression tests for DSSE hashing.
|
||
|
||
## Test strategy
|
||
- **Unit:** OpTok/PoE validation, quota enforcement, scanner signature verification, DSSE canonicalisation, multi-sig bundling.
|
||
- **Integration:** end-to-end signing for SBOM, report, export artifacts; Attestor ingestion; Export Center bundle signing.
|
||
- **Security:** fuzz signing inputs, simulate PoE tampering, ensure unauthorized actors are rejected.
|
||
- **Performance:** signing throughput benchmarks (keyless vs keyful), quota pressure, concurrency checks.
|
||
- **Offline:** verify signatures using Offline Kit trust roots and cosign CLI without network access.
|
||
|
||
## Definition of done
|
||
- Signing pipeline deployed with observability and incident runbooks.
|
||
- Export Center + Attestor dependencies validated; CLI parity confirmed.
|
||
- Documentation updated (README, architecture, runbooks, CLI guides) with imposed rule compliance.
|
||
- ./TASKS.md and ../../TASKS.md reflect the latest status transitions.
|