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:
- 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 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
- Vendor and product terms match at any version, and a package version is decided only for the ecosystems listed under Versions. Undecided records are delivered.
- 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.