epss.cr

A Crystal library for the Exploit Prediction Scoring System (EPSS) published by FIRST.

epss.cr covers the two surfaces EPSS is consumed through in practice:

Surface	Source	Module
REST API	`https://api.first.org/data/v1/epss`	`EPSS::Client`
Daily CSV feed	`https://epss.cyentia.com/epss_scores-YYYY-MM-DD.csv.gz`	`EPSS::CSV`

Quick Links

Getting Started — installation and first call
API Client — REST API, filters, retries, pagination
CSV Feed — daily-feed parser with gzip auto-detect
Time-series — 30-day history per CVE
JSON & Bands — round-trip and qualitative classification
API Reference — all types and methods

Highlights

Auto-detecting top-level helpers: EPSS.score(cve), EPSS.scores(cves).
Strict spec-conformant parsing: handles the FIRST API envelope, time-series expansion, and the #-prefixed daily-feed metadata header.
Comparable(Score) — sort and threshold by EPSS probability.
Structural equality + hash — Scores work as Set / Hash keys (CVE + date + values).
JSON round-trip in the FIRST API row shape.
EPSS::Band qualitative bucket (None/Low/Medium/High/Critical) for both raw probability and percentile rank.
Retry-After-aware retries with exponential backoff and SSL/IO/timeout rescue.
Pluggable EPSS::Transport for offline / test-stubbed clients.

Installation

Add the dependency to your shard.yml:

dependencies:
  epss:
    github: hahwul/epss.cr

Then run:

shards install

Quick Example

require "epss"

if score = EPSS.score("CVE-2022-27225")
  puts "EPSS=#{score.epss}"
  puts "Percentile=#{score.percentile}"
  puts "Band=#{score.band}"
end