stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
02e384a7d64ebbc66fcde3c206f5b9e7f87e4b17
git.stella-ops.org/docs/modules/signer/implementation_plan.md
master 7b5bdcf4d3 feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules 
- 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.
2025-10-30 00:09:39 +02:00

4.3 KiB
Raw Blame History

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.