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

Add determinism tests for verdict artifact generation and update SHA256 sums script

Browse Source 
- Implemented comprehensive tests for verdict artifact generation to ensure deterministic outputs across various scenarios, including identical inputs, parallel execution, and change ordering.
- Created helper methods for generating sample verdict inputs and computing canonical hashes.
- Added tests to validate the stability of canonical hashes, proof spine ordering, and summary statistics.
- Introduced a new PowerShell script to update SHA256 sums for files, ensuring accurate hash generation and file integrity checks.
This commit is contained in:
StellaOps Bot
2025-12-24 02:17:34 +02:00
parent e59921374e
commit 7503c19b8f
390 changed files with 37389 additions and 5380 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/40_ARCHITECTURE_OVERVIEW.md
View File

@@ -1,6 +1,6 @@
# Architecture Overview (High-Level)
This document is a high-level orientation to StellaOps: what components exist, how they fit together, and what "offline-first + deterministic + evidence-linked decisions" means in practice.
This document is the 10-minute tour for StellaOps: what components exist, how they fit together, and what "offline-first + deterministic + evidence-linked decisions" means in practice.
For the full reference map (services, boundaries, detailed flows), see `docs/07_HIGH_LEVEL_ARCHITECTURE.md`.
@@ -12,20 +12,32 @@ For the full reference map (services, boundaries, detailed flows), see `docs/07_
- **Aggregation-not-merge:** upstream advisories and VEX are stored and exposed with provenance; conflicts are visible, not silently collapsed.
- **Offline-first:** the same workflow runs connected or air-gapped via Offline Kit snapshots and signed bundles.
## System Map (What Runs)
At a high level, StellaOps is a set of services grouped by responsibility:
- **Identity and authorization:** Authority (OIDC/OAuth2, scopes/tenancy)
- **Scanning and SBOM:** Scanner WebService + Worker (facts generation)
- **Advisories:** Concelier (ingest/normalize/export vulnerability sources)
## System Map (What Runs)
```
Build -> Sign -> Store -> Scan -> Decide -> Attest -> Notify/Export
```
At a high level, StellaOps is a set of services grouped by responsibility:
- **Identity and authorization:** Authority (OIDC/OAuth2, scopes/tenancy)
- **Scanning and SBOM:** Scanner WebService + Worker (facts generation)
- **Advisories:** Concelier (ingest/normalize/export vulnerability sources)
- **VEX:** Excititor + VEX Lens (VEX observations/linksets and exploration)
- **Decisioning:** Policy Engine surfaces (lattice-style explainable policy)
- **Signing and transparency:** Signer + Attestor (DSSE/in-toto and optional transparency)
- **Orchestration and delivery:** Scheduler, Notify, Export Center
- **Console:** Web UI for operators and auditors
## Infrastructure (What Is Required)
- **Orchestration and delivery:** Scheduler, Notify, Export Center
- **Console:** Web UI for operators and auditors
| Tier | Services | Key responsibilities |
|------|----------|----------------------|
| **Edge / Identity** | `StellaOps.Authority` | Issues short-lived tokens (DPoP + mTLS), exposes OIDC device-code + auth-code flows, rotates JWKS. |
| **Scan & attest** | `StellaOps.Scanner` (API + Worker), `StellaOps.Signer`, `StellaOps.Attestor` | Accept SBOMs/images, drive analyzers, produce DSSE bundles, optionally log to a Rekor mirror. |
| **Evidence graph** | `StellaOps.Concelier`, `StellaOps.Excititor`, `StellaOps.Policy.Engine` | Ingest advisories/VEX, correlate linksets, run lattice policy and VEX-first decisioning. |
| **Experience** | `StellaOps.Web` (Console), `StellaOps.Cli`, `StellaOps.Notify`, `StellaOps.ExportCenter` | Operator UX, automation, notifications, and offline/mirror packaging. |
| **Data plane** | PostgreSQL, Valkey, RustFS/object storage (optional NATS JetStream) | Canonical store, counters/queues, and artifact storage with deterministic layouts. |
## Infrastructure (What Is Required)
**Required**
@@ -38,23 +50,29 @@ At a high level, StellaOps is a set of services grouped by responsibility:
- **NATS JetStream:** optional messaging transport in some deployments.
- **Transparency log services:** Rekor mirror (and CA services) when transparency is enabled.
## End-to-End Flow (Typical)
## End-to-End Flow (Typical)
1. **Evidence enters** via Concelier and Excititor connectors (Aggregation-Only Contract).
2. **SBOM arrives** from CLI/CI; Scanner deduplicates layers and enqueues work.
3. **Analyzer bundle** runs inside the Worker and stores evidence in content-addressed caches.
4. **Policy Engine** merges advisories, VEX, and inventory/usage facts; emits explain traces and stable dispositions.
5. **Signer + Attestor** wrap outputs into DSSE bundles and (optionally) anchor them in a Rekor mirror.
6. **Console/CLI/Export** surface findings and package verifiable evidence; Notify emits digests/incidents.
1. **Ingest evidence sources:** Concelier and Excititor ingest upstream advisories/VEX into immutable observations with provenance.
2. **Scan:** Scanner accepts an SBOM or image reference, produces scan facts and evidence artifacts.
3. **Decide:** Policy evaluation merges scan facts with advisory/VEX evidence to produce an explainable verdict.
4. **Seal:** Signer/Attestor wrap outputs into signed bundles (DSSE/in-toto) and optionally anchor in transparency logs.
5. **Export and notify:** Export Center produces portable evidence bundles and Offline Kit material; Notify delivers digests/incidents.
6. **Operate:** Console exposes triage, explainability, verification, and governance workflows.
## Extension Points (Where You Customize)
## Extension Points (Where You Customize)
- **Scanner analyzers** (restart-time plug-ins) for ecosystem-specific parsing and facts extraction.
- **Concelier connectors** for new advisory sources (preserving aggregation-only guardrails).
- **Policy packs** for organization-specific gating and waivers/justifications.
- **Export profiles** for output formats and offline bundle shapes.
## References
- **Export profiles** for output formats and offline bundle shapes.
## Offline & Sovereign Notes
- Offline Kit carries vulnerability feeds, container images, signatures, and verification material so the workflow stays identical when air-gapped.
- Authority + token verification remain local; quota enforcement is verifiable offline.
- Attestor can cache transparency proofs for offline verification.
## References
- `docs/07_HIGH_LEVEL_ARCHITECTURE.md`
- `docs/24_OFFLINE_KIT.md`