Resolve Concelier/Excititor merge conflicts

2025-10-20 14:19:25 +03:00
parent 6ff35cd50a a07f46231b
commit 01104cccdf
2687 changed files with 212646 additions and 85913 deletions
--- a/docs/EXCITITOR_SCORRING.md
+++ b/docs/EXCITITOR_SCORRING.md
@@ -0,0 +1,104 @@
+## Status
+
+This document tracks the future-looking risk scoring model for Excititor. The calculation below is not active yet; Sprint 7 work will add the required schema fields, policy controls, and services. Until that ships, Excititor 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 Concelier (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 Excititor consensus/claims and Concelier canonical advisories with severity, KEV, EPSS, and expose α/β + weight ceilings in policy. | Sprint 7 tasks `EXCITITOR-CORE-02-001`, `EXCITITOR-POLICY-02-001`, `EXCITITOR-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 `EXCITITOR-CORE-02-002` (backlog). |
+| **Phase 3 – Surfacing & enforcement** | Expose scores via WebService/CLI, integrate with Concelier noise priors, and enforce policy-based suppressions. | To be scheduled after Phase 2. |
+
+## Policy controls (Phase 1)
+
+Operators tune scoring inputs through the Excititor policy document:
+
+```yaml
+excititor:
+  policy:
+    weights:
+      vendor: 1.10      # per-tier weight
+      ceiling: 1.40     # max clamp applied to tiers and overrides (1.0‒5.0)
+    providerOverrides:
+      trusted.vendor: 1.35
+    scoring:
+      alpha: 0.30       # KEV boost coefficient (defaults to 0.25)
+      beta: 0.60        # EPSS boost coefficient (defaults to 0.50)
+```
+
+* All weights (tiers + overrides) are clamped to `[0, weights.ceiling]` with structured warnings when a value is out of range or not a finite number.
+* `weights.ceiling` itself is constrained to `[1.0, 5.0]`, preserving prior behaviour when omitted.
+* `scoring.alpha` / `scoring.beta` accept non-negative values up to 5.0; values outside the range fall back to defaults and surface diagnostics to operators.
+
+## 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**: Concelier delivers severity/KEV/EPSS via the advisory event log; Excititor 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.