Documentation
¶
Overview ¶
Package exploit enriches a finding's severity with real-world exploitability signals: CISA KEV (Known Exploited Vulnerabilities — confirmed exploited in the wild) and FIRST EPSS (Exploit Prediction Scoring System — probability of exploitation). Data is loaded from local files (bring-your-own), so enrichment is optional and works offline.
Index ¶
Constants ¶
const ( // SignalKEV is confirmed, observed exploitation. SignalKEV = "kev" // SignalEPSS is a predicted probability of exploitation. SignalEPSS = "epss" )
The signals a Source can escalate on, as they appear in an Escalation.
Variables ¶
This section is empty.
Functions ¶
func LoadEPSS ¶
LoadEPSS parses a FIRST EPSS scores CSV (columns: cve,epss,percentile; leading #comment and header lines are ignored) into a CVE→score map. Source: https://www.first.org/epss/data_stats
Types ¶
type Options ¶ added in v0.56.0
type Options struct {
// KEV is the set of CVEs CISA has observed being exploited.
KEV map[string]bool
// EPSS maps a CVE to its exploitation probability.
EPSS map[string]float64
// Threshold is the EPSS probability at or above which severity is raised one band. Zero or
// less disables the EPSS bump; KEV still applies.
Threshold float64
// Fetched says when each dataset was obtained, so an escalation can cite a date. Keys are
// SignalKEV and SignalEPSS; a zero time simply omits the date.
Fetched map[string]time.Time
}
Options builds a Source. Every field is optional; a Source with no data enriches nothing.
type Source ¶
type Source struct {
// contains filtered or unexported fields
}
Source holds exploitability data plus the EPSS threshold for a severity bump.
func New ¶
New returns a Source. threshold is the EPSS probability (0–1) at or above which a finding's severity is bumped one band; a threshold ≤ 0 disables the EPSS bump (KEV still applies).
The convenience form, for a caller with nothing to say about where the data came from. Use NewFrom to record fetch dates, without which an escalation cannot cite one.
func (*Source) Consulted ¶ added in v0.107.0
Consulted names the datasets this source can answer from, with the day each was obtained.
Which is a different statement from any escalation, and the one a reader needs first. An escalation is recorded only when a signal *moved* a finding, so its absence covers three unrelated cases: the CVE is not listed, it is listed but was already at the top band, and nobody loaded the data at all. Silence reads as the last of those, which is the reading that makes a ranking look unexplained.
Sorted, so evidence produced twice from the same inputs is byte-identical.
func (*Source) Enrich ¶
Enrich raises base severity using exploitability signals for the CVE referenced by ruleID: on KEV → critical; else EPSS ≥ threshold → one band higher. Findings without a CVE ruleID (secrets, SAST, IaC) or with no matching data return base unchanged.
Source Files