Hole Monitor

Filters

A filter belongs to one endpoint and matches when all of its conditions hold. An endpoint with several filters receives an event when any of them matches, and receives it once.

Field Type Condition
sources List The record has data from any listed source: cve, nvd, ghsa, drupal, drupal_osv, kev, wordfence, epss, redhat, vulncheck_kev, osv
event_types List, default all four The event type is listed: published, updated, kev_added, withdrawn
vendors List of strings Normalized exact match on an affected entry's vendor or CPE vendor
products List of strings Normalized exact match on an affected entry's product or CPE product
packages List of { "ecosystem", "name", "version" } or { "purl" }. version, or a version in the purl, is optional Match on affected[].package. With a version, only records that affect that version. See Versions
min_cvss 0 to 10 max_base_score is at or above it
include_unscored Boolean, default false A record with no CVSS score passes min_cvss
min_epss 0 to 1 EPSS score at or above it. A record with no score fails
kev_only Boolean The record is in CISA's KEV catalog
exploited_only Boolean Any source marks the record as exploited (CISA KEV or VulnCheck KEV)
drupal_risk List The Drupal risk level contains one of these words, for example Critical

When a filter gives both vendors and products, one affected entry must satisfy both. Normalization lowercases, trims, and reduces runs of punctuation and whitespace to one space. Administrators keep a vendor alias table that maps known variants to one name.

Package ecosystems are OSV's: npm, PyPI, Maven, Go, crates.io, NuGet, RubyGems, Packagist, Pub, Hex, SwiftURL, GitHub Actions, WordPress:Plugin, WordPress:Theme, WordPress:Core, for Drupal Packagist:https://packages.drupal.org/8 with names such as drupal/webform, and from OSV.dev Linux distribution ecosystems such as Debian:12, Ubuntu:22.04:LTS, Alpine:v3.20, AlmaLinux:9 and Rocky Linux:9. Matching is case-insensitive. A purl matches on type, namespace and name; qualifiers and subpaths are not accepted.

Versions

A package with a version matches only records whose affected entry for that package covers the version, by its ranges (introduced, fixed, last_affected, limit) or its listed versions, as the OSV schema defines them. The version is written as the ecosystem writes it, with the epoch for Debian and RPM packages, for example 1:8.9p1-3ubuntu0.7.

Versions are ordered by each ecosystem's own rules:

Ecosystems Ordering
npm, crates.io, Go, Hex, Pub, Packagist (including Drupal), and any SEMVER range SemVer 2.0.0
PyPI PEP 440
Debian, Ubuntu Debian Policy 5.6.12
AlmaLinux, Rocky Linux, Red Hat rpm's rpmvercmp

A record is left out only when it shows the version is unaffected. It still matches when the version cannot be decided: the ecosystem is not in the table (Maven, NuGet, RubyGems, WordPress, Alpine and others), a range is a GIT range, a version does not parse under the ecosystem's rules, or the record has no ranges or versions for the package, as with CVE records that name only a vendor and product. A delivery body carries the ranges, so a receiver can check those cases itself.

Versions apply to packages only. vendors and products match at any version.

When a filter notifies

An endpoint is notified when the filter matches the record now and either:

So a CVE published without a score reaches a min_cvss: 7 filter on the updated event that adds the score, even if the filter listens only for published. That delivery's body still says updated. A published event has no earlier state, so its type must be listed.

Broad filters and terms

A tracked package is one vendor, product or package name in any of the account's filters; a vendor or product counts as one, the same as a package. Plans limit tracked packages. A filter with no vendor, product or package is broad: it is evaluated against every event, and plans limit how many an account may have. See Plans.

Examples

All high-severity npm advisories for two packages:

{ "conditions": { "packages": [{ "ecosystem": "npm", "name": "next" }, { "ecosystem": "npm", "name": "react-dom" }], "min_cvss": 7 } }

Every KEV addition (a broad filter):

{ "conditions": { "event_types": ["kev_added"] } }

Drupal contrib projects at Critical risk:

{ "conditions": { "packages": [{ "ecosystem": "Packagist:https://packages.drupal.org/8", "name": "drupal/webform" }], "drupal_risk": ["Critical"] } }

A WordPress plugin:

{ "conditions": { "packages": [{ "ecosystem": "WordPress:Plugin", "name": "woocommerce" }] } }

The versions a project runs, from its lockfile:

{ "conditions": { "packages": [{ "purl": "pkg:npm/next@14.2.3" }, { "ecosystem": "PyPI", "name": "django", "version": "4.2.11" }] } }

OpenSSH as installed on an Ubuntu 22.04 server:

{ "conditions": { "packages": [{ "ecosystem": "Ubuntu:22.04:LTS", "name": "openssh", "version": "1:8.9p1-3ubuntu0.10" }] } }

Managing filters as code

PUT /v1/endpoints/{id}/filters replaces an endpoint's whole filter set:

{ "filters": [ { "conditions": { "packages": [{ "purl": "pkg:npm/next" }] } }, { "conditions": { "kev_only": true, "vendors": ["microsoft"] } } ] }

POST /v1/filters/preview lists retained events that given conditions would have matched, so a change can be checked before it is applied.

Known limits