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:
- the event type is in
event_types, or - the filter did not match the record before this change.
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
- Filters match a product or package at any version.
- Vendor and product names are free text written by CVE Numbering Authorities, so exact matching misses some variants. Package and CPE terms do not have this problem.
- Many CVEs carry only a CNA score or none. Use
include_unscoredif amin_cvssfilter must not skip them.