stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

docs consolidation work

Browse Source
This commit is contained in:
StellaOps Bot
2025-12-25 18:48:11 +02:00
parent 2a06f780cf
commit 82a49f6743
102 changed files with 3550 additions and 1679 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/modules/signer/README.md
View File

@@ -48,6 +48,54 @@ Signer validates callers, enforces Proof-of-Entitlement, and produces signed DSS
- 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/`.

136
docs/modules/signer/implementation_plan.md
View File

@@ -1,136 +0,0 @@
# 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.
---
## Sprint readiness tracker
> Last updated: 2025-11-27 (SIGNER-ENG-0001)
This section maps delivery phases to implementation sprints and tracks readiness checkpoints.
### Phase 1 — Core service & PoE
| Task ID | Status | Sprint | Notes |
|---------|--------|--------|-------|
| KMSI-73-001 | ✅ DONE (2025-11-03) | SPRINT_100_identity_signing | KMS key management foundations with staffing + DSSE contract. |
| KMSI-73-002 | ✅ DONE (2025-11-03) | SPRINT_100_identity_signing | FIDO2 profile integration. |
| PROV-OBS-53-001 | ✅ DONE (2025-11-17) | SPRINT_0513_0001_0001_provenance | DSSE/SLSA BuildDefinition + BuildMetadata models with canonical JSON serializer. |
| PROV-OBS-53-002 | ✅ DONE (2025-11-23) | SPRINT_0513_0001_0001_provenance | Signer abstraction (cosign/KMS/offline) with key rotation hooks and audit logging. |
| SEC-CRYPTO-90-020 | 🔄 IN PROGRESS | SPRINT_0514_0001_0001_sovereign_crypto | CryptoPro signer plugin; Windows CSP runner pending. |
**Checkpoint:** Core signing infrastructure operational — KMS drivers, signer abstractions, and DSSE models delivered.
### Phase 2 — Export Center integration
| Task ID | Status | Sprint | Notes |
|---------|--------|--------|-------|
| PROV-OBS-53-003 | ✅ DONE (2025-11-23) | SPRINT_0513_0001_0001_provenance | PromotionAttestationBuilder feeding canonicalised payloads to Signer. |
| SIGN-REPLAY-186-003 | 📝 TODO | SPRINT_186_record_deterministic_execution | Extend Signer/Authority DSSE flows for replay manifest/bundle payloads. |
| SIGN-CORE-186-004 | 📝 TODO | SPRINT_186_record_deterministic_execution | Replace HMAC demo with StellaOps.Cryptography providers (keyless + KMS). |
| SIGN-CORE-186-005 | 📝 TODO | SPRINT_186_record_deterministic_execution | Refactor SignerStatementBuilder for StellaOps predicate types. |
| SIGN-TEST-186-006 | 📝 TODO | SPRINT_186_record_deterministic_execution | Upgrade signer integration tests with real crypto + fixture predicates. |
**Checkpoint:** Export Center signing APIs partially complete; replay manifest support and crypto provider refactoring pending.
### Phase 3 — Attestor alignment
| Task ID | Status | Sprint | Notes |
|---------|--------|--------|-------|
| AUTH-REACH-401-005 | 📝 TODO | SPRINT_0401_0001_0001_reachability_evidence_chain | DSSE predicate types for SBOM/Graph/VEX/Replay; blocked on predicate definitions. |
| SIGN-VEX-401-018 | 📝 TODO | SPRINT_0401_0001_0001_reachability_evidence_chain | Extend predicate catalog with `stella.ops/vexDecision@v1`. |
| PROV-OBS-54-001 | 📝 TODO | SPRINT_0513_0001_0001_provenance | Verification library for DSSE signatures, Merkle roots, timeline chain. |
| PROV-OBS-54-002 | 📝 TODO | SPRINT_0513_0001_0001_provenance | .NET global tool for local verification + CLI `stella forensic verify`. |
**Checkpoint:** Attestor DSSE alignment pending; predicate catalog extension and verification library not started.
### Phase 4 — Observability & resilience
| Task ID | Status | Sprint | Notes |
|---------|--------|--------|-------|
| DOCS-PROMO-70-001 | 📝 TODO | SPRINT_0304_0001_0004_docs_tasks_md_iv | Promotion attestations doc (CLI commands, Signer/Attestor integration, offline verification). |
| CLI-PROMO-70-002 | 📝 TODO | SPRINT_203_cli_iii | `stella promotion attest` / `promotion verify` commands. |
| CLI-FORENSICS-54-002 | 📝 TODO | SPRINT_202_cli_ii | `stella forensic attest show <artifact>` listing signer details. |
**Checkpoint:** Observability and CLI integration pending; waiting on upstream signing pipeline completion.
---
### Overall readiness summary
| Phase | Status | Blocking items |
|-------|--------|----------------|
| **1 – Core service & PoE** | ✅ Complete | — |
| **2 – Export Center integration** | 🔄 In progress | SIGN-CORE-186-004/005 crypto provider refactoring |
| **3 – Attestor alignment** | 📝 Not started | AUTH-REACH-401-005 predicate definitions |
| **4 – Observability & resilience** | 📝 Not started | Upstream phase completion |
### Cross-module dependencies
| Dependency | Required by | Status |
|------------|-------------|--------|
| Attestor DSSE bundle schema | SIGN-VEX-401-018 | Documented in `docs/modules/attestor/architecture.md` §1 |
| Provenance library canonicalisation | SIGN-CORE-186-005 | Available via PROV-OBS-53-001/002 |
| Export Center bundle manifest | SIGN-REPLAY-186-003 | Pending Sprint 162/163 deliverables |
| Authority predicate definitions | AUTH-REACH-401-005 | Schema draft pending |
### Next actions
1. Complete CryptoPro signer plugin Windows smoke test (SEC-CRYPTO-90-020, Sprint 0514).
2. Start SIGN-CORE-186-004 once replay bundle schema finalises (Sprint 186).
3. Track AUTH-REACH-401-005 predicate schema draft for Attestor alignment (Sprint 401).
4. Monitor PROV-OBS-54-001/002 for verification library availability.