84 lines
3.5 KiB
Markdown
84 lines
3.5 KiB
Markdown
## Status
|
||
|
||
This document tracks the future-looking risk scoring model for Vexer. The calculation below is not active yet; Sprint 7 work will add the required schema fields, policy controls, and services. Until that ships, Vexer emits consensus statuses without numeric scores.
|
||
|
||
## Scoring model (target state)
|
||
|
||
**S = Gate(VEX_status) × W_trust(source) × [Severity_base × (1 + α·KEV + β·EPSS)]**
|
||
|
||
* **Gate(VEX_status)**: `affected`/`under_investigation` → 1, `not_affected`/`fixed` → 0. A trusted “not affected” or “fixed” still zeroes the score.
|
||
* **W_trust(source)**: normalized policy weight (baseline 0‒1). Policies may opt into >1 boosts for signed vendor feeds once Phase 1 closes.
|
||
* **Severity_base**: canonical numeric severity from Feedser (CVSS or org-defined scale).
|
||
* **KEV flag**: 0/1 boost when CISA Known Exploited Vulnerabilities applies.
|
||
* **EPSS**: probability [0,1]; bounded multiplier.
|
||
* **α, β**: configurable coefficients (default α=0.25, β=0.5) stored in policy.
|
||
|
||
Safeguards: freeze boosts when product identity is unknown, clamp outputs ≥0, and log every factor in the audit trail.
|
||
|
||
## Implementation roadmap
|
||
|
||
| Phase | Scope | Artifacts |
|
||
| --- | --- | --- |
|
||
| **Phase 1 – Schema foundations** | Extend Vexer consensus/claims and Feedser canonical advisories with severity, KEV, EPSS, and expose α/β + weight ceilings in policy. | Sprint 7 tasks `VEXER-CORE-02-001`, `VEXER-POLICY-02-001`, `VEXER-STORAGE-02-001`, `FEEDCORE-ENGINE-07-001`. |
|
||
| **Phase 2 – Deterministic score engine** | Implement a scoring component that executes alongside consensus and persists score envelopes with hashes. | Planned task `VEXER-CORE-02-002` (backlog). |
|
||
| **Phase 3 – Surfacing & enforcement** | Expose scores via WebService/CLI, integrate with Feedser noise priors, and enforce policy-based suppressions. | To be scheduled after Phase 2. |
|
||
|
||
## Data model (after Phase 1)
|
||
|
||
```json
|
||
{
|
||
"vulnerabilityId": "CVE-2025-12345",
|
||
"product": "pkg:name@version",
|
||
"consensus": {
|
||
"status": "affected",
|
||
"policyRevisionId": "rev-12",
|
||
"policyDigest": "0D9AEC…"
|
||
},
|
||
"signals": {
|
||
"severity": {"scheme": "CVSS:3.1", "score": 7.5},
|
||
"kev": true,
|
||
"epss": 0.40
|
||
},
|
||
"policy": {
|
||
"weight": 1.15,
|
||
"alpha": 0.25,
|
||
"beta": 0.5
|
||
},
|
||
"score": {
|
||
"value": 10.8,
|
||
"generatedAt": "2025-11-05T14:12:30Z",
|
||
"audit": [
|
||
"gate:affected",
|
||
"weight:1.15",
|
||
"severity:7.5",
|
||
"kev:1",
|
||
"epss:0.40"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Operational guidance
|
||
|
||
* **Inputs**: Feedser delivers severity/KEV/EPSS via the advisory event log; Vexer connectors load VEX statements. Policy owns trust tiers and coefficients.
|
||
* **Processing**: the scoring engine (Phase 2) runs next to consensus, storing results with deterministic hashes so exports and attestations can reference them.
|
||
* **Consumption**: WebService/CLI will return consensus plus score; scanners may suppress findings only when policy-authorized VEX gating and signed score envelopes agree.
|
||
|
||
## Pseudocode (Phase 2 preview)
|
||
|
||
```python
|
||
def risk_score(gate, weight, severity, kev, epss, alpha, beta, freeze_boosts=False):
|
||
if gate == 0:
|
||
return 0
|
||
if freeze_boosts:
|
||
kev, epss = 0, 0
|
||
boost = 1 + alpha * kev + beta * epss
|
||
return max(0, weight * severity * boost)
|
||
```
|
||
|
||
## FAQ
|
||
|
||
* **Can operators opt out?** Set α=β=0 or keep weights ≤1.0 via policy.
|
||
* **What about missing signals?** Treat them as zero and log the omission.
|
||
* **When will this ship?** Phase 1 is planned for Sprint 7; later phases depend on connector coverage and attestation delivery.
|