# 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](#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](https://ossf.github.io/osv-schema/#affectedranges-field) 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](https://semver.org/#spec-item-11) |
| `PyPI` | [PEP 440](https://peps.python.org/pep-0440/) |
| `Debian`, `Ubuntu` | [Debian Policy 5.6.12](https://www.debian.org/doc/debian-policy/ch-controlfields.html#version) |
| `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](/docs/plans/).

## Examples

All high-severity npm advisories for two packages:

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

Every KEV addition (a broad filter):

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

Drupal contrib projects at Critical risk:

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

A WordPress plugin:

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

The versions a project runs, from its lockfile:

```json
{ "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:

```json
{ "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:

```json
{ "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](#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_unscored` if a `min_cvss` filter must not skip them.
