Add monitoring.yml page

.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

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.