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
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" } or { "purl" } without a version Match on affected[].package
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 at present)
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, and for Drupal Packagist:https://packages.drupal.org/8 with names such as drupal/webform. Matching is case-insensitive.

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 term is one vendor, product or package value in any of the account's filters. Plans limit tracked terms. 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" }] } }

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