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

feat: Add archived advisories and implement smart-diff as a core evidence primitive

Browse Source 
- Introduced new advisory documents for archived superseded advisories, including detailed descriptions of features already implemented or covered by existing sprints.
- Added "Smart-Diff as a Core Evidence Primitive" advisory outlining the treatment of SBOM diffs as first-class evidence objects, enhancing vulnerability verdicts with deterministic replayability.
- Created "Visual Diffs for Explainable Triage" advisory to improve user experience in understanding policy decisions and reachability changes through visual diffs.
- Implemented "Weighted Confidence for VEX Sources" advisory to rank conflicting vulnerability evidence based on freshness and confidence, facilitating better decision-making.
- Established a signer module charter detailing the mission, expectations, key components, and signing modes for cryptographic signing services in StellaOps.
- Consolidated overlapping concepts from triage UI, visual diffs, and risk budget visualization advisories into a unified specification for better clarity and implementation tracking.
This commit is contained in:
StellaOps Bot
2025-12-26 13:01:43 +02:00
parent 22390057fc
commit 7792749bb4
50 changed files with 6844 additions and 130 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
src/Signer/AGENTS.md Normal file
View File

@@ -0,0 +1,71 @@
# Signer Module — Agent Charter
## Mission
Provide cryptographic signing services for StellaOps attestations:
- Sign DSSE envelopes for SBOMs, verdicts, and reports
- Support multiple signing modes: keyless (Fulcio), KMS, HSM, FIDO2
- Enforce entitlement (PoE), release integrity, and plan quotas
- Return verifiable bundles suitable for Rekor transparency logging
- Maintain audit trails for all signing operations
## Expectations
- Coordinate with Authority for OIDC tokens and DPoP/mTLS validation
- Coordinate with Attestor for downstream Rekor submission
- Maintain deterministic serialization for reproducible signatures
- Support offline operation with KMS/HSM modes for air-gapped deployments
- Provide REST APIs for signing operations and release verification
- Keep signing key management schema current with migrations
## Key Components
- **StellaOps.Signer.Core**: Core abstractions, pipeline, and contracts
- **StellaOps.Signer.Infrastructure**: Signing implementations, DI extensions
- **StellaOps.Signer.WebService**: REST API endpoints
- **StellaOps.Signer.Keyless**: Fulcio integration for keyless signing (Sprint 20251226_001)
- **__Libraries/StellaOps.Signer.KeyManagement**: Key rotation and trust anchor management
- **__Tests**: Unit and integration tests
## Required Reading
- `docs/modules/signer/architecture.md`
- `docs/modules/signer/README.md` (if exists)
- `docs/modules/platform/architecture-overview.md`
- `docs/product-advisories/25-Dec-2025 - Planning Keyless Signing for Verdicts.md`
- Sigstore Fulcio documentation: https://docs.sigstore.dev/certificate_authority/overview/
## Working Agreement
1. Update task status to `DOING`/`DONE` in both corresponding sprint file `/docs/implplan/SPRINT_*.md` and local `TASKS.md` when you start or finish work.
2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
## Signing Modes
- **Keyless (Fulcio)**: Ephemeral ECDSA/Ed25519 keys, short-lived X.509 certs from Fulcio, OIDC identity binding
- **KMS**: AWS KMS, GCP KMS, Azure Key Vault — hardware-backed, no key exposure
- **HSM (PKCS#11)**: On-premise HSM integration for sovereign/air-gapped environments
- **FIDO2**: WebAuthn authenticator for dual-control scenarios
- **File**: Encrypted key files for development/testing
## Predicate Types
- `stella.ops/sbom@v1`: SBOM attestation (CycloneDX/SPDX)
- `stella.ops/report@v1`: Final PASS/FAIL vulnerability report
- `stella.ops/vexDecision@v1`: OpenVEX decision with reachability evidence
- `verdict.stella/v1`: Policy verdict attestation (Sprint 20251226_001)
- `stella.ops/promotion@v1`: Promotion/release gate evidence
## Guardrails
- Ephemeral keys MUST NOT persist to disk; zero memory on disposal
- All timestamps in UTC ISO-8601
- Preserve determinism: canonical JSON (RFC 8785), stable ordering
- No bearer token fallbacks — DPoP/mTLS enforced for `aud=signer`
- Fulcio certificate chains MUST validate to configured roots
- Audit every signing decision; expose metrics
- Keep Offline Kit parity in mind — document air-gapped workflows for KMS/HSM modes
## Active Sprints
- `SPRINT_20251226_001_SIGNER_fulcio_keyless_client.md` — Fulcio keyless signing implementation
## Related Modules
- **Authority**: OIDC tokens, DPoP, mTLS validation
- **Attestor**: Rekor submission, attestation storage, verification
- **Cryptography**: Crypto profiles (ECDSA, Ed25519, SM2)
- **Scheduler**: Bundle rotation jobs