stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
82a49f6743202b4828f46f369474f26ec0a0edf9
git.stella-ops.org/docs/modules/signer/README.md
StellaOps Bot 82a49f6743 docs consolidation work
2025-12-25 18:50:33 +02:00

6.4 KiB
Raw Blame History

StellaOps Signer

Signer validates callers, enforces Proof-of-Entitlement, and produces signed DSSE bundles for SBOMs, reports, and exports.

Latest updates (Sprint 0186/0401 · 2025-11-26)

  • CryptoDsseSigner implemented with ICryptoProviderRegistry integration (SIGN-CORE-186-004), enabling keyless + KMS signing modes with cosign-compatible DSSE output.
  • SignerStatementBuilder refactored to support StellaOps predicate types (stella.ops/promotion@v1, stella.ops/sbom@v1, stella.ops/vex@v1, etc.) with CanonicalJson canonicalization (SIGN-CORE-186-005).
  • PredicateTypes catalog extended with stella.ops/vexDecision@v1 and stella.ops/graph@v1 for reachability evidence chain (SIGN-VEX-401-018).
  • Helper methods added: IsVexRelatedType, IsReachabilityRelatedType, GetAllowedPredicateTypes, IsAllowedPredicateType for predicate type validation.
  • Integration tests upgraded with real crypto abstraction, fixture predicates (promotion, SBOM, VEX, replay, policy, evidence, graph), and deterministic test data (SIGN-TEST-186-006). All 102 Signer tests passing.

Previous updates (Sprint 11 · 2025-10-21)

  • /sign/dsse pipeline landed with Authority OpTok + PoE enforcement, Fulcio/KMS signing modes, and deterministic DSSE bundles ready for Attestor logging.
  • /verify/referrers endpoint exposes release-integrity checks against scanner OCI referrers so callers can confirm digests before requesting signatures.
  • Plan quota enforcement (QPS/concurrency/artifact size) and audit/metrics wiring now align with the Sprint 11 signing-chain release.

Responsibilities

  • Enforce Proof-of-Entitlement and plan quotas before signing artifacts.
  • Support keyless (Fulcio) and keyful (KMS/HSM) signing backends.
  • Verify scanner release integrity via OCI referrers prior to issuing signatures.
  • Emit DSSE payloads consumed by Attestor/Export Center and maintain comprehensive audit trails.

Key components

  • StellaOps.Signer service host with SignerPipeline orchestrating the signing flow.
  • CryptoDsseSigner for ES256 signature generation via ICryptoProviderRegistry.
  • SignerStatementBuilder for in-toto statement creation with PredicateTypes catalog.
  • DefaultSigningKeyResolver for tenant-aware key resolution (keyless/KMS modes).
  • Crypto providers under StellaOps.Cryptography.*.

Integrations & dependencies

  • Authority for OpTok + PoE validation.
  • Licensing Service for entitlement introspection.
  • OCI registries (Referrers API) for scanner release verification.
  • Attestor for transparency logging and Rekor ingestion.
  • Export Center and CLI for artifact signing flows.

API quick reference

  • POST /api/v1/signer/sign/dsse — validate OpTok/PoE, enforce quotas, return DSSE bundle with signing identity metadata.
  • GET /api/v1/signer/verify/referrers — report scanner release signer and trust verdict for a supplied image digest.

Operational notes

  • Key management via Authority/DevOps runbooks.
  • Metrics for signing latency/throttle states.
  • Offline kit integration for signature verification.

Backlog references

  • Sprint 0186: docs/implplan/SPRINT_0186_0001_0001_record_deterministic_execution.md (SIGN-CORE-186-004, SIGN-CORE-186-005, SIGN-TEST-186-006 DONE; SIGN-REPLAY-186-003 blocked on upstream).
  • Sprint 0401: docs/implplan/SPRINT_0401_0001_0001_reachability_evidence_chain.md (SIGN-VEX-401-018 DONE; AUTH-REACH-401-005 TODO).
  • SIG docs/tasks in ../../TASKS.md (e.g., DOCS-SIG-26-006).

Implementation Status

Phase 1 – Core service & PoE (Complete)

  • OpTok validation with Authority DPoP/mTLS tokens and signer.sign scope
  • Proof-of-Entitlement (PoE) introspection with cloud licensing integration
  • Scanner release verification via OCI referrers
  • DSSE signing pipeline: keyless (Fulcio) and keyful (KMS/HSM/FIDO2)
  • KMS key management foundations (KMSI-73-001, KMSI-73-002)
  • DSSE/SLSA BuildDefinition models with canonical JSON (PROV-OBS-53-001/002)

Phase 2 – Export Center integration (In Progress)

  • CryptoDsseSigner with ICryptoProviderRegistry (keyless + KMS modes)
  • SignerStatementBuilder refactored for StellaOps predicate types
  • PromotionAttestationBuilder with canonicalized payloads (PROV-OBS-53-003)
  • Cosign-compatible DSSE output with provenance manifests
  • Blocking: SIGN-CORE-186-004/005 crypto provider refactoring, replay manifest support

Phase 3 – Attestor alignment (Not Started)

  • DSSE envelope metadata for Attestor ingestion
  • Extended predicate catalog: stella.ops/vexDecision@v1, stella.ops/graph@v1 (SIGN-VEX-401-018 complete)
  • Helper methods: IsVexRelatedType, IsReachabilityRelatedType, predicate validation
  • Blocking: AUTH-REACH-401-005 predicate definitions, verification library (PROV-OBS-54-001/002)

Phase 4 – Observability & resilience (Not Started)

  • Metrics: signing latency, PoE failures, quota hits, key usage distribution
  • Structured logs with trace IDs, subject digests, issuer mode, decision outcomes
  • Alerts for PoE outages, key exhaustion, quota breaches, failure spikes
  • CLI commands: stella promotion attest/verify, stella forensic attest show

Key Acceptance Criteria

  • Signs only requests satisfying OpTok, PoE, quota, scanner provenance checks
  • DSSE outputs verify with standard cosign tooling
  • Export Center receives signed bundles with provenance manifests
  • Audit logs capture every request with tenant, issuer, subject digest, PoE state
  • CLI/Offline workflows verify signatures using Offline Kit trust roots

Technical Decisions & Risks

  • PoE/entitlement outages: cache last-known entitlement within TTL, emergency bypass with audit
  • Key compromise: hardware-backed keys, rotation cadence, immediate revocation, incident runbook
  • Release verification failures: allowlist for trusted scanner digests, manual approval fallback
  • Determinism: canonicalize JSON, lock timestamp sources, regression tests for DSSE hashing

Recent Updates (Sprint 0186/0401 · 2025-11-26)

  • CryptoDsseSigner with ES256 signature generation via ICryptoProviderRegistry
  • PredicateTypes catalog extended with VEX/graph predicates
  • Integration tests upgraded with real crypto, fixture predicates (102 tests passing)
  • CryptoPro signer plugin in progress (SEC-CRYPTO-90-020)

Epic alignment

  • Epic 10 – Export Center: provide signing pipelines, cosign interoperability, and provenance manifests for bundle promotion.
  • Epic 19 – Attestor Console: supply DSSE payloads and Proof-of-Entitlement enforcement feeding attestation workflows described in docs/modules/attestor/.