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

up
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
sdk-generator-smoke / sdk-smoke (push) Has been cancelled
Details
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Details
api-governance / spectral-lint (push) Has been cancelled
Details
oas-ci / oas-validate (push) Has been cancelled
Details
Mirror Thin Bundle Sign & Verify / mirror-sign (push) Has been cancelled
Details

Browse Source
This commit is contained in:
StellaOps Bot
2025-11-27 07:46:56 +02:00
parent d63af51f84
commit ea970ead2a
302 changed files with 43161 additions and 1534 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/modules/cli/guides/policy.md
View File

@@ -1,6 +1,7 @@
# Stella CLI — Policy Commands
> **Audience:** Policy authors, reviewers, operators, and CI engineers using the `stella` CLI to interact with Policy Engine.
# Stella CLI — Policy Commands
> **Audience:** Policy authors, reviewers, operators, and CI engineers using the `stella` CLI to interact with Policy Engine.
> **Imposed rule:** Submit/approve/publish flows must include lint, simulate, coverage, and shadow evidence; CLI blocks if required attachments are missing.
> **Supported from:** `stella` CLI ≥ 0.20.0 (Policy Engine v2 sprint line).
> **Prerequisites:** Authority-issued bearer token with the scopes noted per command (export `STELLA_TOKEN` or pass `--token`).
> **2025-10-27 scope update:** CLI/CI tokens issued prior to Sprint 23 (AUTH-POLICY-23-001) must drop `policy:write`/`policy:submit`/`policy:edit` and instead request `policy:read`, `policy:author`, `policy:review`, and `policy:simulate` (plus `policy:approve`/`policy:operate`/`policy:activate` for promotion pipelines).
@@ -218,7 +219,15 @@ Options:
`stella policy run status <runId>` retrieves run metadata.
`stella policy run list --status failed --limit 20` returns recent runs.
### 4.3 Replay & Cancel
### 4.3 History
```
stella policy history P-7 --limit 20 --format table
```
Shows version list with status, shadow flag, IR hash, attestation, submission/approval timestamps. Add `--runs` to include last run status per version. Exit code `0` success; `12` on RBAC error.
### 4.4 Replay & Cancel
```
stella policy run replay run:P-7:2025-10-26:auto --output bundles/replay.tgz
@@ -315,4 +324,4 @@ All non-zero exits emit structured error envelope on stderr when `--format json`
---
*Last updated: 2025-10-27 (Sprint 20).*
*Last updated: 2025-11-26 (Sprint 307).*

10
docs/modules/policy/architecture.md
View File

@@ -5,7 +5,7 @@
> **Ownership:** Policy Guild • Platform Guild
> **Services:** `StellaOps.Policy.Engine` (Minimal API + worker host)
> **Data Stores:** MongoDB (`policies`, `policy_runs`, `effective_finding_*`), Object storage (explain bundles), optional NATS/Mongo queue
> **Related docs:** [Policy overview](../../policy/overview.md), [DSL](../../policy/dsl.md), [Lifecycle](../../policy/lifecycle.md), [Runs](../../policy/runs.md), [REST API](../../api/policy.md), [Policy CLI](../cli/guides/policy.md), [Architecture overview](../platform/architecture-overview.md), [AOC reference](../../ingestion/aggregation-only-contract.md)
> **Related docs:** [Policy overview](../../policy/overview.md), [DSL](../../policy/dsl.md), [SPL v1](../../policy/spl-v1.md), [Lifecycle](../../policy/lifecycle.md), [Runtime](../../policy/runtime.md), [Governance](../../policy/governance.md), [REST API](../../policy/api.md), [Policy CLI](../cli/guides/policy.md), [Architecture overview](../platform/architecture-overview.md), [AOC reference](../../ingestion/aggregation-only-contract.md)
This dossier describes the internal structure of the Policy Engine service delivered in Epic 2. It focuses on module boundaries, deterministic evaluation, orchestration, and integration contracts with Concelier, Excititor, SBOM Service, Authority, Scheduler, and Observability stacks.
@@ -21,6 +21,7 @@ The service operates strictly downstream of the **Aggregation-Only Contract (AOC
- Emit per-finding OpenVEX decisions anchored to reachability evidence, forward them to Signer/Attestor for DSSE/Rekor, and publish the resulting artifacts for bench/verification consumers.
- Consume reachability lattice decisions (`ReachDecision`, `docs/reachability/lattice.md`) to drive confidence-based VEX gates (not_affected / under_investigation / affected) and record the policy hash used for each decision.
- Honor **hybrid reachability attestations**: graph-level DSSE is required input; when edge-bundle DSSEs exist, prefer their per-edge provenance for quarantine, dispute, and high-risk decisions. Quarantined edges (revoked in bundles or listed in Unknowns registry) must be excluded before VEX emission.
- Enforce **shadow + coverage gates** for new/changed policies: shadow runs record findings without enforcement; promotion blocked until shadow and coverage fixtures pass (see lifecycle/runtime docs). CLI/Console enforce attachment of lint/simulate/coverage evidence.
- Operate incrementally: react to change streams (advisory/vex/SBOM deltas) with ≤ 5 min SLA.
- Provide simulations with diff summaries for UI/CLI workflows without modifying state.
- Enforce strict determinism guard (no wall-clock, RNG, network beyond allow-listed services) and RBAC + tenancy via Authority scopes.
@@ -109,12 +110,13 @@ Key notes:
| **Authority Client** (`Authority/`) | Acquire tokens, enforce scopes, perform DPoP key rotation. | Only service identity uses `effective:write`. |
| **DSL Compiler** (`Dsl/`) | Parse, canonicalise, IR generation, checksum caching. | Uses Roslyn-like pipeline; caches by `policyId+version+hash`. |
| **Selection Layer** (`Selection/`) | Batch SBOM ↔ advisory ↔ VEX joiners; apply equivalence tables; support incremental cursors. | Deterministic ordering (SBOM → advisory → VEX). |
| **Evaluator** (`Evaluation/`) | Execute IR with first-match semantics, compute severity/trust/reachability weights, record rule hits. | Stateless; all inputs provided by selection layer. |
| **Materialiser** (`Materialization/`) | Upsert effective findings, append history, manage explain bundle exports. | Mongo transactions per SBOM chunk. |
| **Evaluator** (`Evaluation/`) | Execute IR with first-match semantics, compute severity/trust/reachability weights, record rule hits. | Stateless; all inputs provided by selection layer. |
| **Signals** (`Signals/`) | Normalizes reachability, trust, entropy, uncertainty, runtime hits into a single dictionary passed to Evaluator; supplies default `unknown` values when signals missing. | Aligns with `signals.*` namespace in DSL. |
| **Materialiser** (`Materialization/`) | Upsert effective findings, append history, manage explain bundle exports. | Mongo transactions per SBOM chunk. |
| **Orchestrator** (`Runs/`) | Change-stream ingestion, fairness, retry/backoff, queue writer. | Works with Scheduler Models DTOs. |
| **API** (`Api/`) | Minimal API endpoints, DTO validation, problem responses, idempotency. | Generated clients for CLI/UI. |
| **Observability** (`Telemetry/`) | Metrics (`policy_run_seconds`, `rules_fired_total`), traces, structured logs. | Sampled rule-hit logs with redaction. |
| **Offline Adapter** (`Offline/`) | Bundle export/import (policies, simulations, runs), sealed-mode enforcement. | Uses DSSE signing via Signer service. |
| **Offline Adapter** (`Offline/`) | Bundle export/import (policies, simulations, runs), sealed-mode enforcement. | Uses DSSE signing via Signer service; bundles include IR hash, input cursors, shadow flag, coverage artefacts. |
| **VEX Decision Emitter** (`Vex/Emitter/`) | Build OpenVEX statements, attach reachability evidence hashes, request DSSE signing, and persist artifacts for Export Center / bench repo. | New (Sprint 401); integrates with Signer predicate `stella.ops/vexDecision@v1` and Attestor Rekor logging. |
---

13
docs/modules/scanner/architecture.md
View File

@@ -478,9 +478,16 @@ ResolveEntrypoint(ImageConfig cfg, RootFs fs):
return Unknown(reason)
```
### Appendix A.1 — EntryTrace Explainability
EntryTrace emits structured diagnostics and metrics so operators can quickly understand why resolution succeeded or degraded:
### Appendix A.1 — EntryTrace Explainability
### Appendix A.0 — Replay / Record mode
- WebService ships a **RecordModeService** that assembles replay manifests (schema v1) with policy/feed/tool pins and reachability references, then writes deterministic input/output bundles to the configured object store (RustFS default, S3/Minio fallback) under `replay/<head>/<digest>.tar.zst`.
- Bundles contain canonical manifest JSON plus inputs (policy/feed/tool/analyzer digests) and outputs (SBOM, findings, optional VEX/logs); CAS URIs follow `cas://replay/...` and are attached to scan snapshots as `ReplayArtifacts`.
- Reachability graphs/traces are folded into the manifest via `ReachabilityReplayWriter`; manifests and bundles hash with stable ordering for replay verification (`docs/replay/DETERMINISTIC_REPLAY.md`).
- Deterministic execution switches (`docs/modules/scanner/deterministic-execution.md`) must be enabled when generating replay bundles to keep hashes stable.
EntryTrace emits structured diagnostics and metrics so operators can quickly understand why resolution succeeded or degraded:
| Reason | Description | Typical Mitigation |
|--------|-------------|--------------------|

38
docs/modules/scanner/deterministic-execution.md Normal file
View File

@@ -0,0 +1,38 @@
# Scanner Deterministic Execution Invariants
> **Imposed rule:** Deterministic mode must pin clock, RNG, feeds, policy, tooling, and concurrency; any nondeterministic output is a test failure.
This note collects the invariants required for reproducible Scanner runs and replays.
## Runtime switches (config/env)
- Clock: `scanner:determinism:fixedClock=true`, `scanner:determinism:fixedInstantUtc=2024-01-01T00:00:00Z` or `SCANNER__DETERMINISM__FIXEDCLOCK=true`, `SCANNER__DETERMINISM__FIXEDINSTANTUTC=...`.
- RNG: `scanner:determinism:rngSeed=1337` or `SCANNER__DETERMINISM__RNGSEED=1337`.
- Concurrency cap: `scanner:determinism:concurrencyLimit=1` (worker clamps `MaxConcurrentJobs` to this) or `SCANNER__DETERMINISM__CONCURRENCYLIMIT=1`.
- Feed/policy pins: `scanner:determinism:feedSnapshotId=<frozen-feed>` and `scanner:determinism:policySnapshotId=<rev>` to stamp submissions and reject mismatched runtime policies.
- Log filtering: `scanner:determinism:filterLogs=true` to strip timestamps/PIDs before hashing.
## Ordering
- Sort inputs (images, layers, files, findings) deterministically before processing/serialization.
- Canonical JSON writers: sorted keys, UTF-8, stable float formatting.
## Hashing & manifests
- Compute SHA-256 for each artefact; aggregate into Merkle root for replay bundles.
- Record tool/policy/feed hashes in `replay.yaml`; include analyzer versions.
## Outputs to verify
- SBOM (CycloneDX/SPDX), findings, VEX, reachability graphs, logs.
- Optional entropy reports (`entropy.report.json`, `layer_summary.json`).
- `determinism.json` when harness is run.
## CI/bench hooks
- `bench:determinism` runs replay with fixed switches; fails on hash deltas.
- `stella replay run --sealed --fixed-clock ... --seed 1337 --single-threaded` for local.
## Offline/air-gap
- All inputs from bundle; no egress.
- Rekor lookups skipped; rely on bundled proofs.
## References
- `docs/replay/DETERMINISTIC_REPLAY.md`
- `docs/replay/TEST_STRATEGY.md`
- `docs/modules/scanner/determinism-score.md`

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

@@ -1,22 +1,32 @@
# StellaOps Signer
# StellaOps Signer
Signer validates callers, enforces Proof-of-Entitlement, and produces signed DSSE bundles for SBOMs, reports, and exports.
## Latest updates (Sprint 11 · 2025-10-21)
## 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.
- Crypto providers under `StellaOps.Cryptography.*`.
## 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.
@@ -27,15 +37,17 @@ Signer validates callers, enforces Proof-of-Entitlement, and produces signed DSS
## 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
- SIG docs/tasks in ../../TASKS.md (e.g., DOCS-SIG-26-006).
## 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/`.
## 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).
## 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/`.