stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
5593212b414864ab213082c8945a267451b99901
git.stella-ops.org/docs/features/checked/riskengine/epss-risk-band-mapping.md

2.7 KiB
Raw Blame History

EPSS Risk Band Mapping

Module

RiskEngine

Status

VERIFIED

Description

EPSS provider with bundle loading, fetching, and risk band mapping. Contains two providers: EpssProvider using EPSS probability directly as risk score, and CvssKevEpssProvider combining CVSS + KEV + EPSS with percentile-based bonus thresholds (99th >= +0.10, 90th >= +0.05, 50th >= +0.02).

Implementation Details

  • EPSS Provider: src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/EpssProvider.cs (124 lines) -- two providers: (1) EpssProvider uses EPSS probability score directly (clamped 0-1, rounded to 6 digits), (2) CvssKevEpssProvider combines CVSS + KEV + EPSS with percentile-based bonuses. Parallel signal fetching via Task.WhenAll.
  • EPSS Bundle Loader: src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/EpssBundleLoader.cs (224 lines) -- supports loading from .tar.gz bundle archives, extracted directories, snapshot files, and streams with auto-detection of gzip vs plain JSON. Builds InMemoryEpssSource with case-insensitive dictionary.
  • EPSS Fetcher: src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/EpssFetcher.cs (223 lines) -- fetches from https://api.first.org/data/v1/epss with pagination, deduplication, deterministic ordering, gzip compression, SHA-256 hashing. Includes GetLatestModelDateAsync for freshness.
  • EPSS Sources Interface: src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/IEpssSources.cs -- EpssData record (Score, Percentile, ModelVersion), IEpssSource interface, NullEpssSource, InMemoryEpssSource.
  • In-Memory Result Store: src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Infrastructure/Stores/InMemoryRiskScoreResultStore.cs -- ConcurrentDictionary + ConcurrentQueue for thread-safe, order-preserving storage.

E2E Test Plan

  • Load an EPSS bundle and query score for a known CVE; verify returned probability matches bundle data
  • Verify EPSS score directly returned as risk score (clamped 0-1)
  • Verify unknown CVE returns 0
  • Verify 99th percentile EPSS bonus (+0.10) with combined provider
  • Verify 90th percentile EPSS bonus (+0.05)
  • Verify 50th percentile EPSS bonus (+0.02)
  • Verify below 50th percentile = no bonus
  • Verify bundle loading from gzip and plain JSON streams
  • Verify case-insensitive CVE lookup

Verification

  • Verified: 2026-02-10
  • Method: Tier 1 code review + Tier 2d test verification
  • Build: Passes (0 errors, 0 warnings for Core/Infrastructure)
  • Tests: 14+ tests across 2 test files (EpssBundleTests: 8, RiskScoreWorkerTests EPSS-specific: 6+). All 55/55 module tests pass.