# 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
- [x] Load an EPSS bundle and query score for a known CVE; verify returned probability matches bundle data
- [x] Verify EPSS score directly returned as risk score (clamped 0-1)
- [x] Verify unknown CVE returns 0
- [x] Verify 99th percentile EPSS bonus (+0.10) with combined provider
- [x] Verify 90th percentile EPSS bonus (+0.05)
- [x] Verify 50th percentile EPSS bonus (+0.02)
- [x] Verify below 50th percentile = no bonus
- [x] Verify bundle loading from gzip and plain JSON streams
- [x] 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.