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

sprints and audit work

Browse Source
This commit is contained in:
StellaOps Bot
2026-01-07 09:36:16 +02:00
parent 05833e0af2
commit ab364c6032
377 changed files with 64534 additions and 1627 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -118,10 +118,61 @@ Key notes:
| **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; 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. |
| **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. || **Determinization** (`Policy.Determinization/`) | Scores uncertainty/trust based on signal completeness and age; calculates entropy (0.0 = complete, 1.0 = no knowledge), confidence decay (exponential half-life), and aggregated trust scores; emits metrics for uncertainty/decay/trust; supports VEX-trust integration. | Library consumed by Signals and VEX subsystems; configuration via `Determinization` section. |
---
### 3.1 · Determinization Configuration
The Determinization subsystem calculates uncertainty scores based on signal completeness (entropy), confidence decay based on observation age (exponential half-life), and aggregated trust scores. Configuration options in `appsettings.json` under `Determinization`:
```json
{
"Determinization": {
"SignalWeights": {
"VexWeight": 0.35,
"EpssWeight": 0.10,
"ReachabilityWeight": 0.25,
"RuntimeWeight": 0.15,
"BackportWeight": 0.10,
"SbomLineageWeight": 0.05
},
"PriorDistribution": "Conservative",
"ConfidenceHalfLifeDays": 14.0,
"ConfidenceFloor": 0.1,
"ManualReviewEntropyThreshold": 0.60,
"RefreshEntropyThreshold": 0.40,
"StaleObservationDays": 30.0,
"EnableDetailedLogging": false,
"EnableAutoRefresh": true,
"MaxSignalQueryRetries": 3
}
}
```
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `SignalWeights` | Object | See above | Relative weights for each signal type in entropy calculation. Weights are normalized to sum to 1.0. VEX carries highest weight (0.35), followed by Reachability (0.25), Runtime (0.15), EPSS/Backport (0.10 each), and SBOM lineage (0.05). |
| `PriorDistribution` | Enum | `Conservative` | Prior distribution for missing signals. Options: `Conservative` (pessimistic), `Neutral`, `Optimistic`. Affects uncertainty tier classification when signals are unavailable. |
| `ConfidenceHalfLifeDays` | Double | `14.0` | Half-life period for confidence decay in days. Confidence decays exponentially: `exp(-ln(2) * age_days / half_life_days)`. |
| `ConfidenceFloor` | Double | `0.1` | Minimum confidence value after decay (0.0-1.0). Prevents confidence from decaying to zero, maintaining baseline trust even for very old observations. |
| `ManualReviewEntropyThreshold` | Double | `0.60` | Entropy threshold for triggering manual review (0.0-1.0). Findings with entropy ≥ this value require human intervention due to insufficient signal coverage. |
| `RefreshEntropyThreshold` | Double | `0.40` | Entropy threshold for triggering signal refresh (0.0-1.0). Findings with entropy ≥ this value should attempt to gather more signals before verdict. |
| `StaleObservationDays` | Double | `30.0` | Maximum age before an observation is considered stale (days). Used in conjunction with decay calculations and auto-refresh triggers. |
| `EnableDetailedLogging` | Boolean | `false` | Enable verbose logging for entropy/decay/trust calculations. Useful for debugging but increases log volume significantly. |
| `EnableAutoRefresh` | Boolean | `true` | Automatically trigger signal refresh when entropy exceeds `RefreshEntropyThreshold`. Requires integration with signal providers. |
| `MaxSignalQueryRetries` | Integer | `3` | Maximum retry attempts for failed signal provider queries before marking signal as unavailable. |
**Metrics emitted:**
- `stellaops_determinization_uncertainty_entropy` (histogram, unit: ratio): Uncertainty entropy score per CVE/PURL pair. Tags: `cve`, `purl`.
- `stellaops_determinization_decay_multiplier` (histogram, unit: ratio): Confidence decay multiplier based on observation age. Tags: `half_life_days`, `age_days`.
**Usage in policies:**
Determinization scores are exposed to SPL policies via the `signals.trust.*` and `signals.uncertainty.*` namespaces. Use `signals.uncertainty.entropy` to access entropy values and `signals.trust.score` for aggregated trust scores that combine VEX, reachability, runtime, and other signals with decay/weighting.
---
## 4 · Data Model & Persistence
### 4.1 Collections