ecluse:ecluse-core
Safe HaskellNone
LanguageGHC2021

Ecluse.Core.Osv.Epss

Description

The FIRST.org EPSS feed, the exploitability score Pilot joins onto each advisory.

Pilot joins the scores through advisory aliases (Ecluse.Core.Osv.Advisory). Every compile attempts the feed. A failed fetch is an EpssFeedFailure, and the ecosystem's EpssRequirement decides whether it stops publication. Individual missing scores remain absent.

Synopsis

The feed

maxEpssFeedBytes :: Int Source #

64 MiB, applied to the served stream and again to its expansion: several times a feed of one short row per scored CVE.

maxEpssLineBytes :: Int Source #

The longest feed line Pilot holds, 4 KiB. A scored row is under 100 bytes, so a longer line is no row.

data EpssFeed Source #

One fetch of the feed: its scores, and what it says about itself, so a stalled feed shows without a second source.

Constructors

EpssFeed 

Fields

Instances

Instances details
Show EpssFeed Source # 
Instance details

Defined in Ecluse.Core.Osv.Epss

Eq EpssFeed Source # 
Instance details

Defined in Ecluse.Core.Osv.Epss

fetchEpssScores :: (MonadResource m, MonadThrow m, KatipContext m) => Manager -> Int -> String -> m EpssFeed Source #

Fetch and decode the feed, bounded by cap bytes on each side of decompression. A non-2xx, undecodable, over-large, or scoreless feed throws.

data EpssFeedTooLarge Source #

The feed passed a byte ceiling, so the fetch refused it whole. Each carries the ceiling and the bytes seen when it tripped.

Constructors

CompressedTooLarge Int Int

The compressed stream the host served, so an endless one cannot hang the pass.

DecompressedTooLarge Int Int

Its expansion under gzip, which is what a compression bomb inflates.

LineTooLarge Int Int

One line of the expansion (maxEpssLineBytes), however the stream was chunked.

data EpssFeedEmpty Source #

The feed decoded to no scores at all, as an error page served as 200 does. One missing score is not this.

Constructors

EpssFeedEmpty 

data EpssFeedTruncated Source #

A gzip member ended before its end-of-stream marker, so the rows it carried may be a fraction.

Constructors

EpssFeedTruncated 

One compile's attempt

data EpssFeedFailure Source #

Why one attempt at the feed produced no scores.

Constructors

EpssFeedFetch HttpFault

The fetch failed: the feed host's status, or the transport's fault.

EpssFeedOversize EpssFeedTooLarge

The feed passed a byte ceiling.

EpssFeedUndecodable

The feed is not valid gzip, or its stream ended early.

EpssFeedNoScores

The feed decoded to no scores.

renderEpssFeedFailure :: Text -> EpssFeedFailure -> Text Source #

The failure as an operator reads it, after the feed's host:port. It never names the feed URL, which can carry a credential.

classifyEpssFailure :: SomeException -> Maybe EpssFeedFailure Source #

The feed failures a compile can continue past. An invalid URL or an unnamed exception is a fault, never an outage.

acquireEpssFeed :: (MonadResource m, MonadMask m, MonadUnliftIO m, KatipContext m) => Manager -> Int -> String -> m (Either EpssFeedFailure EpssFeed) Source #

Fetch the feed under the advisory retry policy. A failure classifyEpssFailure names is a value. Anything else propagates.

data EpssEnrichment Source #

What one compile joins onto its advisories.

Constructors

EpssEnriched EpssFeed

The feed arrived, so its scores join and its provenance is recorded.

EpssUnavailable EpssFeedFailure

The feed failed where the ecosystem does not require it, so no score joins.

Instances

Instances details
Show EpssEnrichment Source # 
Instance details

Defined in Ecluse.Core.Osv.Epss

Eq EpssEnrichment Source # 
Instance details

Defined in Ecluse.Core.Osv.Epss

resolveEnrichment :: EpssRequirement -> Either EpssFeedFailure EpssFeed -> Either EpssFeedFailure EpssEnrichment Source #

Settle one attempt under the ecosystem's requirement, so an unavailable feed never stands in for a required one.

enrichedFeed :: EpssEnrichment -> Maybe EpssFeed Source #

The feed an enrichment joined, if one arrived.

enrichmentStatus :: EpssEnrichment -> EpssStatus Source #

The status the artifact records for this enrichment.

The score table

data EpssScores Source #

The scores from one fetch, keyed by upper-cased CVE id so a case difference cannot miss the join.

Instances

Instances details
Show EpssScores Source # 
Instance details

Defined in Ecluse.Core.Osv.Epss

Eq EpssScores Source # 
Instance details

Defined in Ecluse.Core.Osv.Epss

mkEpssScores :: [(Text, Double)] -> EpssScores Source #

Build a score table. A duplicate id keeps the higher score, the fail-closed direction for a threshold deny.

epssForIds :: EpssScores -> [Text] -> Maybe Double Source #

The highest score the feed carries for any of these identifiers.

epssScoreCount :: EpssScores -> Int Source #

How many CVEs the table scores.

One feed row

parseEpssLine :: ByteString -> Maybe (Text, Double) Source #

One feed row as (CVE id, probability). Anything else, a score outside [0, 1] included, drops out rather than failing the pass.

The feed's preamble

data EpssPreamble Source #

What the feed's leading comment declares, written as #model_version:v2026.08.01,score_date:2026-08-29T00:00:00+0000.

Instances

Instances details
Show EpssPreamble Source # 
Instance details

Defined in Ecluse.Core.Osv.Epss

Eq EpssPreamble Source # 
Instance details

Defined in Ecluse.Core.Osv.Epss

parseEpssPreamble :: ByteString -> EpssPreamble Source #

Read the feed's leading comment line. Anything this cannot read yields absence, never a substitute value.