From d3a759a66acbbadf6ae8246f3c7acfcdb15222cf Mon Sep 17 00:00:00 2001 From: David Harder Date: Tue, 23 Jan 2024 20:50:43 -0600 Subject: [PATCH] Add monitoring.yml page --- .cspell-allowed-words.txt | 5 ++ docs/packaging/monitoring.yml.md | 148 +++++++++++++++++++++++++++++++ 2 files changed, 153 insertions(+) create mode 100644 docs/packaging/monitoring.yml.md diff --git a/.cspell-allowed-words.txt b/.cspell-allowed-words.txt index cf5cfd56e..dd4390223 100644 --- a/.cspell-allowed-words.txt +++ b/.cspell-allowed-words.txt @@ -1,6 +1,7 @@ abcm ahci alienware +anitya anthy anydesk aosp @@ -92,6 +93,7 @@ flicky flto fluidsynth fpath +freedesktop funroll gamepad gconf @@ -129,6 +131,7 @@ ksgrd ksshaskpass ksysguard ldflags +lennart libc libcmis libcurl @@ -212,6 +215,7 @@ pkgconfigs pkgfiles pkgname plexmediaserver +poettering pomo pomodoneapp portege @@ -238,6 +242,7 @@ readline realtek redditor redistributable +regexes reindex releng relocs diff --git a/docs/packaging/monitoring.yml.md b/docs/packaging/monitoring.yml.md new file mode 100644 index 000000000..9a70af08b --- /dev/null +++ b/docs/packaging/monitoring.yml.md @@ -0,0 +1,148 @@ +--- +title: Monitoring YAML +summary: The purpose and format of monitoring.yml +--- + +# `monitoring.yml` + +:::warning + +A `monitoring.yml` is not yet required for Solus packages. + +::: + +A `monitoring.yml` file is included in the Packages repository directory for every Solus package to enable automatic scanning for new releases and security advisories. + +Checking for new releases is done by mapping the Solus package to an [Anitya](https://github.com/fedora-infra/anitya) ID. _Anitya_ is a Fedora (todo Red Hat?) project, part of [release-monitoring.org](https://release-monitoring.org/) + +Checking for security advisories ([CVEs](https://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures)), is done by mapping the Solus package to a _Common Platform Enumeration Name_ ([CPE](https://nvd.nist.gov/products/cpe)) from the National Vulnerability Database. + +# systemd as an example + +Let's look at the `monitoring.yml` for `systemd` as an example. + +The `systemd` directory in the Packages repository looks like this: + +```text +systemd +├── monitoring.yml +├── package.yml +├── pspec_x86_64.xml +└── *lots of other files we can ignore* +``` + +The `monitoring.yml` looks like this: + +```yaml +releases: + id: 205088 + ignore: + # We only update to the n-1 stable release. So for now we're only interested in 252.x updates + - "253.*" + rss: [todo proper rss link] +security: + cpe: + - vendor: systemd_project + product: systemd + - vendor: freedesktop + product: systemd + ignore: + - CVE-2022-55555 +``` + +## `monitoring.yml` fields + +### `releases` + +- Fields used to monitor for new versions + +#### `id` (Anitya ID) + +- One `id` field per Solus package +- Find the ID by searching [release-monitoring.org](https://release-monitoring.org/) by project name, then taking the ID out of the URL for the correct search result. +- For example, the correct `systemd` search result for us is `systemd-stable` with the URL [https://release-monitoring.org/project/205088/](https://release-monitoring.org/project/205088/), so we use `205088` as the ID + +#### `ignore` + +- Contains regexes for version strings we choose to ignore +- The regex should be enclosed in quotes +- For example, we are keeping Solus on the `252.x` releases of `systemd`, so releases tp later versions can be ignored, and the regex becomes: `253.*` +- Include a comment explaining the reason for every regex + +#### `rss` + +- URL for a releases RSS feed +- If the only RSS feed you can find for a project is a general "news" feed, don't include the field +- This field is optional but strongly encouraged + +## `security` + +- Fields used to monitor for security advisories (CVEs) + +### `cpe` (CPE Name) + +- A full CPE Name contains redundant information we can ignore, we are only interested in `vendor` and `product` +- For example, `cpe:2.3:a:systemd_project:systemd` is a CPE for the _vendor_ `systemd_project`, and the _product_ `systemd` +- CVEs for may be published under more than one CPE, include more than one if that is likely + +#### Determining the CPE Name + +The easiest way to search for CPE Names is with the following command; replacing `systemd` with your search term: + +```bash +curl -s -X POST https://cpe-guesser.cve-search.org/search -d "{\"query\": [\"systemd\"]}" | jq . +``` + +todo: mention the proto helper script once it is merger + +:::tip + +Convert your search term to lower case and try variations on the search term if you get no results. The CPE search is not a "fuzzy" search. + +::: + +The command returns the following: + +```text +[ + [ + 49192, + "cpe:2.3:a:ubuntu_developers:systemd" + ], + [ + 116392, + "cpe:2.3:a:lennart_poettering:systemd" + ], + [ + 120506, + "cpe:2.3:a:freedesktop:systemd" + ], + [ + 120627, + "cpe:2.3:a:systemd_project:systemd" + ] +] +``` + +Ignore the numerical ids, let's walk through the CPEs by vendor: + +- `ubuntu_developers` is for `systemd` patched by Ubuntu; we can ignore it +- `lennart_poettering` is for the main `systemd` developer and is probably a bleeding edge vendor; ignore it +- `freedesktop` is from freedesktop.org and is a good candidate, so we add it +- `systemd_project` is a good candidate, so we add it + +#### No known CPE + +It is possible that an established product has not had a security advisory in the past, and therefore **does not have a CPE**; please ask on Matrix if you are unsure. In that case, include an empty `security` and `cpe` field with a comment in the following format: + +```yaml +# No known CPE, checked 20240123 +security: + cpe: ~ +``` + +#### `ignore` + +- Use this field to list specific CVE identifiers which can be ignored +- todo: explanation of when this should be used, whether list items should include a comment with a reason +- Unlike the `ignore` field under `releases`, regexes should not be used.