# Vulnerability Determinations (Md.XI draft)

> Status: DRAFT (awaiting GRAP0101 + findings ledger doc + DevOps rollout); keep TODO until signals/simulation semantics confirmed.

## Scope
- Capture rationale and signals used to determine vulnerability states in Vuln Explorer (policy overlay, VEX, reachability, DevOps signals).
- Document simulation semantics and precedence/weighting; align with Policy Engine gateways.

## Inputs & Dependencies
| Input | Status | Notes |
| --- | --- | --- |
| Findings Ledger doc (DOCS-VULN-29-005) | in progress | Must align on field names/hashes. |
| DevOps rollout plan (telemetry + signals) | pending | Needed for final weighting and thresholds. |
| GRAP0101 contract | pending | Confirms identifiers used in policies. |

## Signals (draft list)
- Advisory severity + KEV flag.
- Reachability: call graph + runtime facts (from Signals module) — weighting TBD.
- VEX status: CSAF-mapped decisions (NOT_AFFECTED, AFFECTED_*).
- SBOM component context: version range, path, scope (prod/dev/test).
- Observability: error/traffic indicators (if enabled) — DevOps to confirm.

## Simulation Semantics (draft)
- Deterministic evaluation order: VEX > Reachability > Policy gates > Overrides.
- Precedence to `NOT_AFFECTED` when confidence ≥ threshold (TBD) unless explicit policy override.
- Shadow/simulation runs mirror production gates but do not emit notifications; results stored with flag `simulation=true` and excluded from audit unless promoted.

## Policy Outputs
- Status mapping: {`blocked`, `warn`, `pass`} with rationale bundle references.
- Required fields in outputs: `findingId`, `policyVersion`, `signalsUsed`, `weighting`, `explainBundleRef`, `timestamp` (UTC, ISO-8601).
- Determinism: stable sorting by `findingId` then `policyVersion`; hashes recorded when examples added.

## Offline/Determinism Notes
- All sample policy outputs must be hashed in `docs/assets/vuln-explorer/SHA256SUMS`.
- Use fixed fixture inputs; avoid live metrics; keep ordering stable.

## Open Items
- Finalize signal weights and thresholds after DevOps rollout plan.
- Insert concrete examples once Findings Ledger and GRAP0101 finalize fields.
- Add simulation vs. production side-by-side examples with hashes.

_Last updated: 2025-12-05 (UTC)_