semi implemented and features implemented save checkpoint

docs/features/unchecked/riskengine/cvss-kev-risk-signal-combination.md

@@ -0,0 +1,33 @@
+# CVSS + KEV Risk Signal Combination
+
+## Module
+RiskEngine
+
+## Status
+IMPLEMENTED
+
+## Description
+Risk engine combining CVSS scores with KEV (Known Exploited Vulnerabilities) data and EPSS scores for prioritization. Deterministic formula tested via integration tests.
+
+## Implementation Details
+- **CVSS+KEV Provider**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/CvssKevProvider.cs` (implements `IRiskScoreProvider`) -- combines CVSS base scores with CISA KEV catalog data; KEV-listed vulnerabilities receive a risk boost reflecting active exploitation.
+- **Risk Score Provider Interface**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/IRiskScoreProvider.cs` -- contract for risk score computation providers.
+- **CVSS+KEV Sources Interface**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/ICvssKevSources.cs` -- data source contract for CVSS scores and KEV catalog.
+- **VEX Gate Provider**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/VexGateProvider.cs` -- applies VEX status as a risk gate, reducing or zeroing risk scores for findings with "not_affected" or "fixed" status.
+- **Fix Exposure Provider**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/FixExposureProvider.cs` -- adjusts risk based on fix availability and exposure window.
+- **Fix Chain Risk Provider**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/FixChain/FixChainRiskProvider.cs` -- computes risk from fix chain analysis including attestation verification.
+- **Fix Chain Attestation Client**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/FixChain/FixChainAttestationClient.cs` (implements `IFixChainAttestationClient`) -- fetches fix chain attestation data for risk computation.
+- **Fix Chain Risk Metrics/Display**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/FixChain/FixChainRiskMetrics.cs`, `FixChainRiskDisplay.cs` -- metrics and display models for fix chain risk.
+- **Default Transforms Provider**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/DefaultTransformsProvider.cs` -- default risk score transformation rules.
+- **Score Request/Result**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Contracts/ScoreRequest.cs`, `RiskScoreResult.cs` -- request/response models for risk score computation.
+- **Risk Score Worker**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Services/RiskScoreWorker.cs` -- background worker processing risk score computation queue.
+- **Risk Score Queue**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Services/RiskScoreQueue.cs` -- queue for asynchronous risk score computation requests.
+- **Tests**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests/RiskEngineApiTests.cs`, `FixChainRiskProviderTests.cs`, `FixChainRiskIntegrationTests.cs`
+
+## E2E Test Plan
+- [ ] Submit a score request for a CVE with a CVSS score of 7.5 that is listed in the KEV catalog and verify the combined risk score is higher than the CVSS score alone
+- [ ] Submit a score request for the same CVSS score but without KEV listing and verify the risk score equals the CVSS base score (no KEV boost)
+- [ ] Verify VEX gate: submit a score request for a KEV-listed CVE with VEX status "not_affected" and confirm the `VexGateProvider` reduces the risk score
+- [ ] Verify fix chain risk: submit a score request for a CVE with a verified fix attestation and confirm `FixChainRiskProvider` reduces the risk score based on fix verification
+- [ ] Verify determinism: compute the same risk score 10 times with identical inputs and confirm all results are bit-for-bit identical
+- [ ] Verify the risk score worker processes queued requests and stores results in `IRiskScoreResultStore`

docs/features/unchecked/riskengine/epss-risk-band-mapping.md

@@ -0,0 +1,27 @@
+# EPSS Risk Band Mapping
+
+## Module
+RiskEngine
+
+## Status
+IMPLEMENTED
+
+## Description
+EPSS provider with bundle loading, fetching, and risk band mapping that converts EPSS probabilities into actionable risk categorizations.
+
+## Implementation Details
+- **EPSS Provider**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/EpssProvider.cs` (implements `IRiskScoreProvider`) -- converts EPSS probability scores into risk band categorizations (Critical, High, Medium, Low) using configurable thresholds.
+- **EPSS Bundle Loader**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/EpssBundleLoader.cs` -- loads EPSS score bundles from local files or cached downloads for offline operation.
+- **EPSS Fetcher**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/EpssFetcher.cs` -- fetches EPSS score data from the FIRST.org EPSS API for periodic updates.
+- **EPSS Sources Interface**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Providers/IEpssSources.cs` -- data source contract for EPSS score lookups.
+- **In-Memory Result Store**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Infrastructure/Stores/InMemoryRiskScoreResultStore.cs` (implements `IRiskScoreResultStore`) -- in-memory store for computed risk scores with EPSS band mappings.
+- **Risk Score Result Store Interface**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Core/Services/IRiskScoreResultStore.cs` -- persistence contract for risk score results.
+- **Tests**: `src/RiskEngine/StellaOps.RiskEngine/StellaOps.RiskEngine.Tests/EpssBundleTests.cs`, `RiskEngineApiTests.cs`
+
+## E2E Test Plan
+- [ ] Load an EPSS bundle via `EpssBundleLoader` and query the score for a known CVE; verify the returned probability matches the bundle data
+- [ ] Map an EPSS probability of 0.95 and verify it is categorized as "Critical" risk band
+- [ ] Map an EPSS probability of 0.01 and verify it is categorized as "Low" risk band
+- [ ] Verify bundle loading from file: place an EPSS CSV bundle in the expected path and confirm `EpssBundleLoader` loads it without network access
+- [ ] Verify the EPSS fetcher downloads fresh data and the bundle loader caches it for subsequent offline lookups
+- [ ] Combine EPSS with CVSS: compute a risk score using both EPSS and CVSS providers and verify the combined score reflects both signals