docs consoliation work
This commit is contained in:
StellaOps Bot
215
docs/modules/signals/architecture.md
Normal file
215
docs/modules/signals/architecture.md
Normal file
@@ -0,0 +1,215 @@
|
||||
# Signals Module Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
The **Signals** module provides a unified evidence-weighted scoring system for vulnerability findings. It aggregates evidence from multiple sources (reachability analysis, runtime observations, backport detection, exploit intelligence, source trust, and mitigations) into a single 0-100 score that enables rapid triage.
|
||||
|
||||
## Module Purpose
|
||||
|
||||
- **Unify Scoring:** Combine disparate evidence signals into one actionable score
|
||||
- **Enable Triage:** Support sorting, filtering, and prioritization by evidence strength
|
||||
- **Maintain Determinism:** Same inputs + policy = same score, always
|
||||
- **Provide Transparency:** Decomposable scores with explanations
|
||||
|
||||
## Location
|
||||
|
||||
```
|
||||
src/Signals/
|
||||
├── StellaOps.Signals/
|
||||
│ └── EvidenceWeightedScore/
|
||||
│ ├── EvidenceWeightedScoreCalculator.cs
|
||||
│ ├── EvidenceWeightedScoreInput.cs
|
||||
│ ├── EvidenceWeightedScoreResult.cs
|
||||
│ ├── Normalizers/
|
||||
│ │ ├── BackportEvidenceNormalizer.cs
|
||||
│ │ ├── ExploitLikelihoodNormalizer.cs
|
||||
│ │ ├── MitigationNormalizer.cs
|
||||
│ │ ├── ReachabilityNormalizer.cs
|
||||
│ │ ├── RuntimeSignalNormalizer.cs
|
||||
│ │ └── SourceTrustNormalizer.cs
|
||||
│ ├── Guardrails/
|
||||
│ │ └── ScoreGuardrails.cs
|
||||
│ └── Policy/
|
||||
│ ├── EvidenceWeightPolicy.cs
|
||||
│ └── EvidenceWeightPolicyProvider.cs
|
||||
└── __Tests/
|
||||
└── StellaOps.Signals.Tests/
|
||||
└── EvidenceWeightedScore/
|
||||
```
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Evidence Dimensions
|
||||
|
||||
| Dimension | Symbol | Description | Source Module |
|
||||
|-----------|--------|-------------|---------------|
|
||||
| Reachability | RCH | Code path reachability to vulnerable sink | Policy |
|
||||
| Runtime | RTS | Live observation strength (eBPF/dyld/ETW) | Policy |
|
||||
| Backport | BKP | Patch evidence from distro/changelog/binary | Concelier |
|
||||
| Exploit | XPL | Exploit probability (EPSS + KEV) | Scanner, Concelier |
|
||||
| Source Trust | SRC | VEX source trustworthiness | Excititor |
|
||||
| Mitigations | MIT | Active protective controls | Policy |
|
||||
|
||||
### Scoring Formula
|
||||
|
||||
```
|
||||
Score = clamp01(W_rch*RCH + W_rts*RTS + W_bkp*BKP + W_xpl*XPL + W_src*SRC - W_mit*MIT) * 100
|
||||
```
|
||||
|
||||
Note: MIT is **subtractive** — mitigations reduce risk.
|
||||
|
||||
### Guardrails
|
||||
|
||||
Hard caps and floors based on evidence conditions:
|
||||
|
||||
1. **Not-Affected Cap:** If vendor says not-affected (BKP=1) and no runtime contradiction (RTS<0.6), cap at 15
|
||||
2. **Runtime Floor:** If strong live signal (RTS>=0.8), floor at 60
|
||||
3. **Speculative Cap:** If no reachability and no runtime (RCH=0, RTS=0), cap at 45
|
||||
|
||||
### Score Buckets
|
||||
|
||||
| Bucket | Range | Meaning |
|
||||
|--------|-------|---------|
|
||||
| ActNow | 90-100 | Strong evidence of exploitable risk; immediate action |
|
||||
| ScheduleNext | 70-89 | Likely real; schedule for next sprint |
|
||||
| Investigate | 40-69 | Moderate evidence; investigate when touching component |
|
||||
| Watchlist | 0-39 | Low/insufficient evidence; monitor |
|
||||
|
||||
## Architecture
|
||||
|
||||
### Component Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Signals Module │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌──────────────────────────────────┐ │
|
||||
│ │ NormalizerAggr. │───▶│ EvidenceWeightedScoreCalculator │ │
|
||||
│ └────────┬────────┘ └──────────────┬───────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────┐ ┌──────────────────────────────────┐ │
|
||||
│ │ Normalizers │ │ ScoreGuardrails │ │
|
||||
│ │ ┌─────┐ ┌─────┐ │ └──────────────────────────────────┘ │
|
||||
│ │ │ BKP │ │ XPL │ │ │
|
||||
│ │ └─────┘ └─────┘ │ ┌──────────────────────────────────┐ │
|
||||
│ │ ┌─────┐ ┌─────┐ │ │ EvidenceWeightPolicyProvider │ │
|
||||
│ │ │ MIT │ │ RCH │ │ └──────────────────────────────────┘ │
|
||||
│ │ └─────┘ └─────┘ │ │
|
||||
│ │ ┌─────┐ ┌─────┐ │ │
|
||||
│ │ │ RTS │ │ SRC │ │ │
|
||||
│ │ └─────┘ └─────┘ │ │
|
||||
│ └─────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────┐ ┌───────────────────────────────────────┐
|
||||
│ External Modules │ │ Consumers │
|
||||
│ │ │ │
|
||||
│ • Policy (RCH, RTS) │ │ • Policy Engine (verdict enrichment) │
|
||||
│ • Concelier (BKP) │ │ • Findings API (score endpoints) │
|
||||
│ • Scanner (XPL) │ │ • Web UI (score components) │
|
||||
│ • Excititor (SRC) │ │ │
|
||||
└─────────────────────┘ └───────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Data Flow
|
||||
|
||||
1. **Finding arrives** for scoring
|
||||
2. **NormalizerAggregator** collects evidence from source modules
|
||||
3. **Individual normalizers** convert raw evidence to 0-1 values
|
||||
4. **EvidenceWeightedScoreCalculator** applies formula
|
||||
5. **ScoreGuardrails** apply caps/floors
|
||||
6. **Result** returned with score, bucket, breakdown, explanations
|
||||
|
||||
### Policy Configuration
|
||||
|
||||
Weight policies are loaded from YAML and can vary by:
|
||||
- **Tenant:** Different organizations may prioritize differently
|
||||
- **Environment:** Production may weight runtime higher than dev
|
||||
- **Policy version:** Changes are versioned for reproducibility
|
||||
|
||||
```yaml
|
||||
version: "ews.v1"
|
||||
profile: production
|
||||
|
||||
weights:
|
||||
rch: 0.30
|
||||
rts: 0.25
|
||||
bkp: 0.15
|
||||
xpl: 0.15
|
||||
src: 0.10
|
||||
mit: 0.10
|
||||
|
||||
guardrails:
|
||||
not_affected_cap:
|
||||
enabled: true
|
||||
max_score: 15
|
||||
runtime_floor:
|
||||
enabled: true
|
||||
min_score: 60
|
||||
speculative_cap:
|
||||
enabled: true
|
||||
max_score: 45
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Inbound (Evidence Sources)
|
||||
|
||||
| Source | Data | Interface |
|
||||
|--------|------|-----------|
|
||||
| Policy/ConfidenceCalculator | ReachabilityEvidence, RuntimeEvidence | Direct type reference |
|
||||
| Concelier/BackportProofService | ProofBlob | Direct type reference |
|
||||
| Scanner/EpssPriorityCalculator | EPSS score, percentile | Direct type reference |
|
||||
| Concelier/VendorRiskSignalExtractor | KEV status | Direct type reference |
|
||||
| Excititor/TrustVector | Trust vector components | Direct type reference |
|
||||
| Policy/GateMultipliers | Active mitigations | Direct type reference |
|
||||
|
||||
### Outbound (Consumers)
|
||||
|
||||
| Consumer | Usage |
|
||||
|----------|-------|
|
||||
| Policy Engine | Verdict enrichment, score-based rules |
|
||||
| Findings API | Score endpoints (calculate, get, history) |
|
||||
| Web UI | Score display components |
|
||||
| Webhooks | Score change notifications |
|
||||
| Attestor | Scoring proofs in attestations |
|
||||
|
||||
## Determinism
|
||||
|
||||
The Signals module maintains strict determinism:
|
||||
|
||||
1. **Same inputs + same policy = same score:** No randomness, no time-dependent factors in formula
|
||||
2. **Policy versioning:** Every policy has a digest; scores include policy digest
|
||||
3. **Reproducible proofs:** Scoring proofs can be verified by recalculation
|
||||
4. **Stable ordering:** Input order doesn't affect result
|
||||
|
||||
## Performance
|
||||
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| Single score calculation | <10ms |
|
||||
| Batch (100 findings) | <1s |
|
||||
| Policy load | <100ms |
|
||||
| Cache hit ratio | >80% |
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
| Level | Focus | Location |
|
||||
|-------|-------|----------|
|
||||
| L0 Unit | Calculator, normalizers, guardrails | `*.Tests` |
|
||||
| L0 Property | Monotonicity, bounds, determinism | `*.Tests/Properties` |
|
||||
| S1 Integration | Cross-module evidence flow | `*.Tests/Integration` |
|
||||
| S1 Snapshot | Result JSON structure | `*.Tests/Snapshots` |
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- Product Advisory: `docs/product-advisories/24-Dec-2025 - Evidence-Weighted Score Model.md`
|
||||
- Sprint Plans: `docs/implplan/SPRINT_8200_0012_*.md`
|
||||
- Policy Confidence (deprecated): `docs/modules/policy/confidence-scoring.md`
|
||||
- Backport Detection: `docs/modules/concelier/backport-detection.md`
|
||||
- EPSS Enrichment: `docs/modules/scanner/epss-enrichment.md`
|
||||
- Trust Vector: `docs/modules/excititor/trust-vector.md`
|
||||
Reference in New Issue
Block a user