# CVE rules

Watches are about software you run. A rule is about the whole stream of new CVEs, also for software Ladon does not know. Ladon reads every CVE from the CVE List, and a CVE that meets the conditions of a rule goes once to the channels you choose. A rule belongs to a project and sends to channels of that project. For example: critical, and not about routers, to your Discord server.

## Where the CVEs come from

- **The CVE List** of the CVE Program, the source of every CVE. Ladon checks it every two minutes, so a new CVE usually reaches you within minutes of its publication.
- **Scores from CISA.** Many CVEs come without a score from the party that publishes them. CISA adds a CVSS 3.1 score and weaknesses to many of them, and Ladon uses that when there is no other score.
- **Scores from NVD.** When neither the publisher nor CISA gives a score, Ladon uses the CVSS score of the National Vulnerability Database, checked every hour. That way fewer CVEs stay without a severity.
- **The CISA KEV list** of vulnerabilities that are exploited in the wild, checked every hour.
- **EPSS**, the chance that a CVE gets exploited in the next 30 days, updated daily.

Every CVE has its own page in Ladon with the description, score, weaknesses, whether it is on the KEV list, its EPSS score, references and a link to cve.org. The CVE number on a vulnerability page opens it too. These pages are public, so anyone who gets an alert can open them. Signed-in members also see their own rules.

## Add a rule

Open the **CVE Monitor** tab of a project, or choose **Add** and then **CVE rule** in a project. Give the rule a name, build the conditions, choose the channels and save. While you build, the preview shows how many CVEs of the last 30 days would have matched, with the newest five and why they match. That way you see right away whether a word filters out what you mean.

Start from an example if you like: critical but not about routers, attacks over the network without logging in, new on the KEV list, or WordPress with a score from 7.

## Conditions

A rule matches **all** or **any** of its conditions. A condition can also be a group with its own all or any, for example: critical, and the title mentions `wordpress` or `woocommerce`.

| Field                               | Operators                                          | Example                                               |
| ----------------------------------- | -------------------------------------------------- | ----------------------------------------------------- |
| Severity                            | is one of, is none of                              | Critical, High. **No score yet** is a choice too      |
| CVSS score                          | is at least, is at most                            | at least 9.0                                          |
| CVSS version                        | is one of, is none of                              | 4.0, 3.1                                              |
| CVSS vector                         | is one of, is none of, per part                    | Attack vector is Network, Privileges required is None |
| Title, or title or description      | contains one of, contains all of, contains none of | contains none of `router`                             |
| Vendor, product                     | contains one of, contains none of                  | product contains `wordpress`                          |
| Weakness (CWE)                      | is one of, is none of                              | CWE-79, CWE-89                                        |
| Assigned by (CNA)                   | is one of, is none of                              | `GitHub_M`                                            |
| On the CISA KEV list                | yes, no                                            | yes                                                   |
| Has an exploit or a patch reference | yes, no                                            | yes                                                   |
| EPSS chance, EPSS percentile        | is at least, is at most                            | percentile at least 95%                               |
| Days since publication              | is at most                                         | 7 days                                                |

- **Words** match whole words and phrases, and capitals do not matter. `router` does not match `routers`, so add both when you mean both. Regular expressions are not supported.
- **Missing data never matches.** A CVE without a score does not meet "score at least 7", and also not "score at most 7". Use **No score yet** under severity to catch those on purpose.
- **CVSS 4.0** names confidentiality, integrity and availability of the system itself `VC`, `VI` and `VA`. A condition on `C`, `I` or `A` also reads those.
- A rule can have up to 50 conditions, and a list up to 25 words or values.

## When a rule sends an alert

A rule reports a CVE once, at the moment the CVE starts to meet the conditions. Usually that is when the CVE is published. It can also be later, for example when CISA adds a score, or when the CVE lands on the KEV list. Changes after that do not send it again.

A CVE that already met the rule before it changed stays quiet. A new rule for critical CVEs therefore does not alert about every old critical CVE that gets a new reference. Matched CVEs are listed on the page of the rule, also when it has no channels.

Every matched CVE is its own message, also when one update of the CVE List matches many CVEs at once. The channel sends them one after the other at the pace the chat app allows. When an update matches unusually many CVEs for all teams together, for example after a mass rescoring, HackIndex checks it before anything is sent.

## Channels

A rule sends to the channels you tick, of any kind, from the channels of its project. To send the same CVEs to several projects, add a rule in each of them. The event types, severity filter and tag filter of a channel do not apply to rules: the rule itself decides what goes out. A paused rule matches nothing until you switch it on again, and it does not send the CVEs it missed in the meantime.

On the Free plan Discord channels only receive CVE rule alerts, never the software watches of your project. They run on every plan, so a CVE rule is the way to run a free feed of critical vulnerabilities in a Discord server.

## Plans

Each active rule counts towards the rules of your plan, see [Plans and limits](https://ladon.hackindex.io/docs/plans-and-limits.md). A paused rule takes no place, and neither do the rules Ladon makes for the [common software](https://ladon.hackindex.io/docs/projects.md#common) of a project. Removing a project removes its rules.

## Webhooks and the API

The alert of a rule has the type `cve.matched`, see [Events and payloads](https://ladon.hackindex.io/docs/events.md#cve-matched). With the [API](https://ladon.hackindex.io/docs/api.md) you manage rules with the scopes `rules:read` and `rules:write`, and read and search CVEs with `cves:read`. The conditions in the API are the same tree the app builds:

```json
{
    "name": "Critical without routers",
    "conditions": {
        "match": "all",
        "conditions": [
            { "field": "severity", "op": "in", "value": ["critical"] },
            { "field": "text", "op": "contains_none", "value": ["router"] }
        ]
    },
    "channels": ["we_01JB0C3E5G7J9L2N4Q6S8U0W1Y"]
}
```

The fields are `severity`, `score`, `cvss_version`, `metric.AV` and the other parts of the vector, `text`, `title`, `vendor`, `product`, `cwe`, `assigner`, `kev`, `exploit`, `patch`, `epss`, `epss_percentile` and `age_days`. EPSS values go from 0 to 1. Send `project` with the public id of a project, such as `prj_01JB8Z7R4M2N6P8Q0S2U4W6Y8A`, to add the rule there. Leave it out and the rule goes to the default project of the team. The channels have to belong to that project. `GET /rules?project=` lists the rules of one project. `POST /rules/preview` with the same `conditions` answers what they would have matched in the last 30 days, without saving a rule.

## Data and licenses

The CVE List is © The MITRE Corporation and used under the CVE Terms of Use. Scores from CISA and the KEV list are in the public domain, EPSS comes from FIRST. Every alert carries the link to the record on cve.org and these notices. All licenses are on the [licenses page](https://ladon.hackindex.io/licenties).
