struct

EPSS::Query

Inherits Struct < Value < Object

A pure value object describing one query to the FIRST EPSS API.

All filter fields are optional. The struct is immutable; use with methods to derive a new query (q.with_date(...), q.with_cves(...)).

Encode to a query-string fragment with #to_params. The EPSS::Client uses this internally and is the usual caller — but the struct is exposed publicly so consumers can build URLs without going through the HTTP client (useful for caching layers and offline tooling).

Constructors

above(threshold : Float64 = 0.95) : Query

CVEs whose EPSS probability is strictly above threshold. Defaults to the 0.95 cutoff commonly used by tier-1 triage policies.

Source
below(threshold : Float64) : Query

CVEs whose EPSS probability is strictly below threshold. Pair with above for inverse filters.

Source
for_cve(cve : String) : Query

Build a query that filters by a single CVE id. Sugar for the common case where with_cves([cve]) would otherwise be required.

EPSS::Query.for_cve("CVE-2022-27225")
Source
for_cves(cves : Enumerable(String)) : Query

Build a query that filters by multiple CVE ids.

Source
new(cves : Array(String) = [] of String, date : Time | Nil = nil, days : Int32 | Nil = nil, epss_gt : Float64 | Nil = nil, percentile_gt : Float64 | Nil = nil, epss_lt : Float64 | Nil = nil, percentile_lt : Float64 | Nil = nil, q : String | Nil = nil, scope : String | Nil = nil, order : String | Nil = nil, offset : Int32 | Nil = nil, limit : Int32 | Nil = nil, fields : Array(String) | Nil = nil, pretty : Bool | Nil = nil, envelope : Bool | Nil = nil)
Source
recent(days : Int32) : Query

Restrict results to scores published in the last days days. Maps to the FIRST days parameter rather than client-side filtering.

Source
search(text : String) : Query

Free-text search query, sorted by EPSS descending.

EPSS::Query.search("openssl")
Source
top(n : Int32) : Query

Highest-EPSS-first query bounded by n rows. Use as a starting point for "top-N" dashboards.

EPSS::Client.new.fetch(EPSS::Query.top(10)).scores
Source

Instance methods

cves

CVE IDs to filter on. Normalized to upper-case at construction so comparisons against query.cves are predictable; the FIRST API itself is case-insensitive on CVE ids. The list is joined with , at request time.

Source
date

Specific publication date to query historical scores for.

Source
days

Time-series window in days. Mutually exclusive with scope.

Source
envelope

Force the FIRST envelope wrapper. The EPSS endpoint already wraps responses by default, but envelope=false can be requested to receive a bare data array — set this explicitly when you want to override the server's default behavior.

Source
epss_gt

Lower-bound thresholds (epss > x / percentile > x).

Source
epss_lt

Upper-bound thresholds (epss < x / percentile < x).

Source
fields

Comma-separated list of fields to return. Maps to FIRST's global fields query param — request a projected payload (e.g. "cve,epss") to skip percentile/date when the caller doesn't need them.

Source
limit
Source
offset

Pagination.

Source
order

Sort order — e.g. "!epss" for descending by EPSS, "epss" for asc.

Source
percentile_gt
Source
percentile_lt
Source
pretty

Request pretty-printed JSON. Off by default (extra whitespace is wasted bandwidth for programmatic consumers); set when capturing API responses to disk for human review.

Source
q

Free-form text query (matches CVE descriptions in the FIRST index).

Source
scope

Scope: "time-series" enables the 30-day series view.

Source
to_params

Encode this query as an array of {key, value} URL parameter pairs, ready to be passed to URI::Params.encode. Returns only the fields that are set — never emits a parameter with an empty value.

Source
to_query_string

Compose this query into a URL path + query string suitable for the FIRST API endpoint (relative form). The host is supplied by Client.

Source
with_cve(cve : String) : Query

Singular form of with_cves. Mirrors Query.for_cve for fluent chains where a Query already exists.

Source
with_cves(cves : Array(String) | String) : Query
Source
with_date(date : Time) : Query
Source
with_days(days : Int32) : Query
Source
with_envelope(value : Bool) : Query
Source
with_epss_gt(value : Float64) : Query
Source
with_epss_lt(value : Float64) : Query
Source
with_fields(value : Array(String) | String) : Query
Source
with_limit(limit : Int32) : Query
Source
with_offset(offset : Int32) : Query
Source
with_order(value : String) : Query
Source
with_percentile_gt(value : Float64) : Query
Source
with_percentile_lt(value : Float64) : Query
Source
with_pretty(value : Bool) : Query
Source
with_q(value : String) : Query
Source
with_scope(value : String) : Query
Source