stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
43e2af88f621a3a015293b86e03e302ba92ab752
git.stella-ops.org/docs/modules/signals/architecture.md
StellaOps Bot 5540ce9430 docs consoliation work
2025-12-24 14:19:46 +02:00

9.9 KiB
Raw Blame History

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
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