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,150 @@
+---
+title: Monitoring YAML
+summary: The purpose and format of monitoring.yml
+---
+
+# `monitoring.yml`
+
+:::important
+
+A `monitoring.yml` file 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 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` file 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
+```
+
+
+
+## "releases" fields
+
+- 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
+
+- Not a required field
+- Contains regular expressions for version strings we choose to ignore
+- The regular expression should be enclosed in quotes
+- For example, we are keeping Solus on the `252.x` releases of `systemd`, so later versions can be ignored, and the regular expression becomes: `253.*`
+- Include a comment explaining the reason for every regular expression
+
+### rss
+
+- This field is optional but strongly encouraged
+- 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
+
+## "security" fields
+
+- 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 a given project 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
+
+- Not a required field
+- 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`, regular expressions should not be used.

docs/packaging/monitoring2.yml.md

@@ -0,0 +1,139 @@
+---
+title: Monitoring YAML
+summary: The purpose and format of monitoring.yml
+---
+
+# `monitoring.yml`
+
+:::important
+
+A `monitoring.yml` file 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 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` file 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
+```
+
+## "releases" fields
+
+| Field    | Type                        | Required ?              | Description                                                                                                                    |
+| -------- | --------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `id`     | integer                     | Yes                     | Anitya ID from [release-monitoring.org](https://release-monitoring.org/)                                                       |
+| `ignore` | list of regular expressions | No                      | List of regular expression matching versions to ignore. Include a comment explaining the ignored versions. Enclose in quotes   |
+| `rss`    | URL                         | No, strongly encouraged | 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 |
+
+- Fields used to monitor for new versions
+
+### Finding the Anitya ID
+
+You can find the Anitya 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` in the `id field`
+
+## "security" fields
+
+| Field    | Type            | Required ? | Description                                                                         |
+| -------- | --------------- | ---------- | ----------------------------------------------------------------------------------- |
+| `cpe`    | list            | Yes        | List of `vendor:product` pairs from a full CPE name. CVEs for a given project may be published under more than one CPE; include more than one if that is likely.                            |
+| `ignore` | list of strings | No         | List of specific CVE identifiers which can be ignored. Todo: do we include reasons? |
+
+### What is a CPE Name?
+
+A [CPE Name](https://en.wikipedia.org/wiki/Common_Platform_Enumeration) is a structured naming scheme for information technology systems, primarily used to search for CVEs. 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 the CPE for the _vendor_ `systemd_project`, and the _product_ `systemd`
+
+### Finding 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 .
+```
+
+If you have our [helper functions](/docs/packaging/prepare-for-packaging#set-up-monorepo-helper-functions-optional) installed, you can use the following command:
+
+```bash
+cpesearch systemd
+```
+
+
+:::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: ~
+```