stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
ab794e167c2759162758096872c5941d308e57b8
git.stella-ops.org/docs/features/checked/riskengine/epss-risk-band-mapping.md
master 5bca406787 save checkpoint: save features
2026-02-12 10:27:23 +02:00

8.1 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 2a live API replay + Tier 2d regression verification
  • Build: Passes (0 errors, 0 warnings for Core/Infrastructure)
  • Tests: RiskEngine suite re-run in Release with 94/94 passing, including added API/provider regression coverage (Simulations_Epss_UsesInlineSignals, Simulations_CvssKevEpss_UsesInlineSignals, and inline EPSS signal provider tests).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-002/tier2-api-check.json

Recheck (Run-003)

  • Verified: 2026-02-10
  • Method: Tier 2a API replay via in-process WebApplicationFactory + full suite replay.
  • Tests: PASS (src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests: 94/94).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-003/tier2-api-check.json
  • Outcome: EPSS and CVSS+KEV+EPSS API simulation paths remain reachable and deterministic.

Recheck (Run-004)

  • Verified: 2026-02-10
  • Method: Tier 2a API replay via in-process WebApplicationFactory + full suite replay.
  • Tests: PASS (src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests: 94/94).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-004/tier2-api-check.json
  • Outcome: EPSS and CVSS+KEV+EPSS API simulation paths remain reachable and deterministic.

Recheck (Run-005)

  • Verified: 2026-02-10
  • Method: Tier 2a API replay validated via RiskEngine integration suite.
  • Tests: PASS (src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests: 94/94).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-005/tier2-api-check.json
  • Outcome: EPSS risk band mapping behavior remains healthy.

Recheck (Run-006)

  • Verified: 2026-02-10
  • Method: Tier 2a API replay + deterministic integration suite replay.
  • Tests: PASS (src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests: 94/94).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-006/tier2-api-check.json
  • Outcome: Checked RiskEngine behavior remains healthy in continued replay.

Recheck (Run-007)

  • Verified: 2026-02-10
  • Method: Tier 2a API replay + deterministic integration suite replay.
  • Tests: PASS (src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests: 94/94).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-007/tier2-api-check.json
  • Outcome: Checked RiskEngine behavior remains healthy in continued replay.

Recheck (Run-008)

  • Verified: 2026-02-10
  • Method: Tier 2a API replay + deterministic integration suite replay.
  • Tests: PASS (src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests: 94/94).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-008/tier2-api-check.json
  • Outcome: Checked RiskEngine behavior remains healthy in continued replay.

Recheck (Run-009)

  • Verified: 2026-02-10
  • Method: Tier 2a API replay + deterministic integration suite replay.
  • Tests: PASS (src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests: 94/94).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-009/tier2-api-check.json
  • Outcome: Checked RiskEngine behavior remains healthy in continued replay.

Recheck (Run-010)

  • Verified: 2026-02-10
  • Method: Tier 2d deterministic integration replay.
  • Tests: PASS (src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests: 94/94).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-010/tier2-integration-check.json
  • Outcome: Checked risk engine behavior remains healthy in continued replay.

Recheck (Run-011)

  • Verified: 2026-02-10
  • Method: Tier 2d deterministic integration replay.
  • Tests: PASS (src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests: 94/94).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-011/tier2-integration-check.json
  • Outcome: Checked risk engine behavior remains healthy in continued replay.

Recheck (Run-012)

  • Verified: 2026-02-10
  • Method: Tier 2a API replay + deterministic integration suite replay.
  • Tests: PASS (src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests: 94/94).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-012/tier2-api-check.json
  • Outcome: Checked risk engine behavior remains healthy in continued replay.

Recheck (Run-013)

  • Verified: 2026-02-10
  • Method: Tier 2a live HTTPS API verification with fresh request/response capture.
  • Tests: PASS (src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests: 94/94).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-013/tier2-api-check.json
  • Captured Requests: /risk-scores/simulations for EPSS direct score (0.77), CVSS+KEV+EPSS percentile bonus (0.55), and missing-signal fallback (0).
  • Outcome: EPSS mapping behavior revalidated from live API transactions.

Recheck (Run-014)

  • Verified: 2026-02-11
  • Method: Tier 2a live HTTPS API verification with fresh request/response capture.
  • Tests: PASS (src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests: 94/94).
  • Tier 2 Evidence: docs/qa/feature-checks/runs/riskengine/epss-risk-band-mapping/run-014/tier2-api-check.json
  • Captured Requests: /risk-scores/simulations for EPSS direct score (0.77), CVSS+KEV+EPSS percentile bonus (0.55), and missing-signal fallback (0).
  • Outcome: EPSS mapping checked behavior remains stable with fresh live API replay.