# 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](/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" }] } }
```

## 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

- 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_unscored` if a `min_cvss` filter must not skip them.
