From a1bb08510aaec25852c6713249b470e7e83fcf01 Mon Sep 17 00:00:00 2001 From: David Harder Date: Tue, 23 Jan 2024 20:50:43 -0600 Subject: [PATCH 1/8] 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..86b8cddc1 --- /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 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` + +- 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. From 6a4c95e1d8d1f91ca1cb9e9fef9fa90f90a24dd6 Mon Sep 17 00:00:00 2001 From: David Harder Date: Thu, 1 Feb 2024 22:10:40 -0600 Subject: [PATCH 2/8] Address deoxys review, Add monitoring2 with possible re-org --- docs/packaging/monitoring.yml.md | 40 +++++---- docs/packaging/monitoring2.yml.md | 139 ++++++++++++++++++++++++++++++ 2 files changed, 160 insertions(+), 19 deletions(-) create mode 100644 docs/packaging/monitoring2.yml.md diff --git a/docs/packaging/monitoring.yml.md b/docs/packaging/monitoring.yml.md index 86b8cddc1..937cac86d 100644 --- a/docs/packaging/monitoring.yml.md +++ b/docs/packaging/monitoring.yml.md @@ -5,21 +5,21 @@ summary: The purpose and format of monitoring.yml # `monitoring.yml` -:::warning +:::important -A `monitoring.yml` is not yet required for Solus packages. +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 Fedora (todo Red Hat?) project, part of [release-monitoring.org](https://release-monitoring.org/) +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 +## systemd as an example -Let's look at the `monitoring.yml` for `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: @@ -50,36 +50,37 @@ security: - CVE-2022-55555 ``` -## `monitoring.yml` fields -### `releases` + +## "releases" fields - Fields used to monitor for new versions -#### `id` (Anitya ID) +### 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` +### 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 +- 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` +### 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 -- This field is optional but strongly encouraged -## `security` +## "security" fields - Fields used to monitor for security advisories (CVEs) -### `cpe` (CPE Name) +### 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` @@ -141,8 +142,9 @@ security: cpe: ~ ``` -#### `ignore` +### 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`, regexes should not be used. +- Unlike the `ignore` field under `releases`, regular expressions should not be used. diff --git a/docs/packaging/monitoring2.yml.md b/docs/packaging/monitoring2.yml.md new file mode 100644 index 000000000..0bdbd295c --- /dev/null +++ b/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: ~ +``` From 5cec528143f00f7dcc642d7007ee167ae66df663 Mon Sep 17 00:00:00 2001 From: David Harder Date: Sun, 4 Feb 2024 09:17:56 -0600 Subject: [PATCH 3/8] Update docs/packaging/monitoring2.yml.md Co-authored-by: Aldair --- docs/packaging/monitoring2.yml.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/packaging/monitoring2.yml.md b/docs/packaging/monitoring2.yml.md index 0bdbd295c..354643a06 100644 --- a/docs/packaging/monitoring2.yml.md +++ b/docs/packaging/monitoring2.yml.md @@ -130,7 +130,9 @@ Ignore the numerical ids, let's walk through the CPEs by vendor: ### 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: +If an established product hasn't had a security advisory in the past, it might not have a CPE. + +In that case, include an empty `security` and `cpe` field with a comment in the following format: ```yaml # No known CPE, checked 20240123 From e43ced80e5e4f312dc4f75ea6486d72dd9e00968 Mon Sep 17 00:00:00 2001 From: David Harder Date: Sun, 4 Feb 2024 09:18:16 -0600 Subject: [PATCH 4/8] Update docs/packaging/monitoring2.yml.md Co-authored-by: Aldair --- docs/packaging/monitoring2.yml.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/packaging/monitoring2.yml.md b/docs/packaging/monitoring2.yml.md index 354643a06..b473462ff 100644 --- a/docs/packaging/monitoring2.yml.md +++ b/docs/packaging/monitoring2.yml.md @@ -75,7 +75,7 @@ You can find the Anitya ID by searching [release-monitoring.org](https://release 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` +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 From ec71060dafd429ee895d5dc6fdeb981c94f2e65d Mon Sep 17 00:00:00 2001 From: David Harder Date: Sun, 4 Feb 2024 09:19:20 -0600 Subject: [PATCH 5/8] Update docs/packaging/monitoring2.yml.md Co-authored-by: Aldair --- docs/packaging/monitoring2.yml.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/packaging/monitoring2.yml.md b/docs/packaging/monitoring2.yml.md index b473462ff..715788307 100644 --- a/docs/packaging/monitoring2.yml.md +++ b/docs/packaging/monitoring2.yml.md @@ -55,7 +55,7 @@ security: | 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 | +| `ignore` | list of regular expressions | No | List of regular expressions enclosed in quotes matching versions to ignore. Include a comment explaining the ignored versions. | | `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 From d4a25a8fb87b61f9737ccbdcb6ba9ea9887ac35c Mon Sep 17 00:00:00 2001 From: David Harder Date: Sun, 4 Feb 2024 09:20:20 -0600 Subject: [PATCH 6/8] Update docs/packaging/monitoring2.yml.md Co-authored-by: Aldair --- docs/packaging/monitoring2.yml.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/packaging/monitoring2.yml.md b/docs/packaging/monitoring2.yml.md index 715788307..688eb5aeb 100644 --- a/docs/packaging/monitoring2.yml.md +++ b/docs/packaging/monitoring2.yml.md @@ -62,7 +62,9 @@ security: ### 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` +To find the Anitya ID, search [release-monitoring.org](https://release-monitoring.org/) by project name, then take 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 From 184de551048474638cabe0a5473565c6db31af18 Mon Sep 17 00:00:00 2001 From: David Harder Date: Sun, 4 Feb 2024 15:16:06 -0600 Subject: [PATCH 7/8] Update docs/packaging/monitoring2.yml.md Co-authored-by: Aldair --- docs/packaging/monitoring2.yml.md | 31 ++++++++++++++++++++++++------- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/packaging/monitoring2.yml.md b/docs/packaging/monitoring2.yml.md index 688eb5aeb..94264d86e 100644 --- a/docs/packaging/monitoring2.yml.md +++ b/docs/packaging/monitoring2.yml.md @@ -39,7 +39,7 @@ releases: 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] + rss: https://github.com/systemd/systemd-stable/tags.atom security: cpe: - vendor: systemd_project @@ -47,18 +47,19 @@ security: - vendor: freedesktop product: systemd ignore: + # A non-existent CVE added here as an example - CVE-2022-55555 ``` ## "releases" fields +Fields used to monitor for new versions. + | 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 expressions enclosed in quotes matching versions to ignore. Include a comment explaining the ignored versions. | -| `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 +| `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. For GitHub projects, You can use the "tags" or "releases" feed: `https://github.com/USER/REPOSITORY/tagsORreleases.atom` | ### Finding the Anitya ID @@ -68,14 +69,18 @@ For example, the correct `systemd` search result for us is `systemd-stable` with ## "security" fields +Fields used to monitor for security advisories (CVEs) + | 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? | +| `ignore` | list of strings | No | List of specific CVE identifiers which can be ignored, including a comment explaining why each CVE was ignored. Please discuss your reasons for ignoring a CVE with Solus Staff. | ### 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` +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. + +CPE names contain redundant information we can ignore, we are only interested in the vendor and the product. For example, `cpe:2.3:a:systemd_project:systemd` is the CPE for the _vendor_ `systemd_project`, and the _product_ `systemd`. @@ -87,7 +92,13 @@ The easiest way to search for CPE Names is with the following command; replacing 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: +Note this command uses the `jq` tool, which you may not have installed: + +```bash +sudo eopkg it jq +``` + +If you have our [helper functions](/docs/packaging/prepare-for-packaging#set-up-repository-helper-functions-optional) installed, you can use the following command: ```bash cpesearch systemd @@ -141,3 +152,9 @@ In that case, include an empty `security` and `cpe` field with a comment in the security: cpe: ~ ``` + +:::tip + +If you are unsure of what to do in this case, feel free to ask in the Solus Packaging Matrix room. + +::: \ No newline at end of file From 7810f5b139ae5dd215417e0403abe5e40259d7a2 Mon Sep 17 00:00:00 2001 From: David Harder Date: Sun, 4 Feb 2024 16:12:52 -0600 Subject: [PATCH 8/8] Move to table layout. --- docs/packaging/monitoring.yml.md | 75 ++++++++------ docs/packaging/monitoring2.yml.md | 160 ------------------------------ 2 files changed, 42 insertions(+), 193 deletions(-) delete mode 100644 docs/packaging/monitoring2.yml.md diff --git a/docs/packaging/monitoring.yml.md b/docs/packaging/monitoring.yml.md index 937cac86d..d58d6cf27 100644 --- a/docs/packaging/monitoring.yml.md +++ b/docs/packaging/monitoring.yml.md @@ -39,7 +39,7 @@ releases: 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] + rss: https://github.com/systemd/systemd-stable/tags.atom security: cpe: - vendor: systemd_project @@ -47,46 +47,44 @@ security: - vendor: freedesktop product: systemd ignore: + # A non-existent CVE added here as an example - CVE-2022-55555 ``` - - ## "releases" fields -- Fields used to monitor for new versions +Fields used to monitor for new versions. -### id (Anitya ID) +| 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 expressions enclosed in quotes matching versions to ignore. Include a comment explaining the ignored versions. | +| `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. For GitHub projects, You can use the "tags" or "releases" feed: `https://github.com/USER/REPOSITORY/tagsORreleases.atom` | -- 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 +### Finding the Anitya ID -### ignore +To find the Anitya ID, search [release-monitoring.org](https://release-monitoring.org/) by project name, then take the ID out of the URL for the correct search result. -- 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 +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 -### rss +## "security" fields -- 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 +Fields used to monitor for security advisories (CVEs) -## "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, including a comment explaining why each CVE was ignored. As an example, a CVE can be ignored if the Solus package includes a patch fixing the CVE. | -- Fields used to monitor for security advisories (CVEs) +### What is a CPE Name? -### cpe (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 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 +CPE names contain redundant information we can ignore, we are only interested in the vendor and the product. -#### Determining the CPE Name +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: @@ -94,7 +92,17 @@ The easiest way to search for CPE Names is with the following command; replacing 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 +Note this command uses the `jq` tool, which you may not have installed: + +```bash +sudo eopkg it jq +``` + +If you have our [helper functions](/docs/packaging/prepare-for-packaging#set-up-repository-helper-functions-optional) installed, you can use the following command: + +```bash +cpesearch systemd +``` :::tip @@ -132,9 +140,11 @@ Ignore the numerical ids, let's walk through the CPEs by vendor: - `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 +### 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: +If an established product hasn't had a security advisory in the past, it might not have a CPE. + +In that case, include an empty `security` and `cpe` field with a comment in the following format: ```yaml # No known CPE, checked 20240123 @@ -142,9 +152,8 @@ security: cpe: ~ ``` -### ignore +:::tip + +If you are unsure of what to do in this case, feel free to ask in the Solus Packaging Matrix room. -- 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. +::: diff --git a/docs/packaging/monitoring2.yml.md b/docs/packaging/monitoring2.yml.md deleted file mode 100644 index 94264d86e..000000000 --- a/docs/packaging/monitoring2.yml.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -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: https://github.com/systemd/systemd-stable/tags.atom -security: - cpe: - - vendor: systemd_project - product: systemd - - vendor: freedesktop - product: systemd - ignore: - # A non-existent CVE added here as an example - - CVE-2022-55555 -``` - -## "releases" fields - -Fields used to monitor for new versions. - -| 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 expressions enclosed in quotes matching versions to ignore. Include a comment explaining the ignored versions. | -| `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. For GitHub projects, You can use the "tags" or "releases" feed: `https://github.com/USER/REPOSITORY/tagsORreleases.atom` | - -### Finding the Anitya ID - -To find the Anitya ID, search [release-monitoring.org](https://release-monitoring.org/) by project name, then take 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 - -Fields used to monitor for security advisories (CVEs) - -| 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, including a comment explaining why each CVE was ignored. Please discuss your reasons for ignoring a CVE with Solus Staff. | - -### 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. - -CPE names contain redundant information we can ignore, we are only interested in the vendor and the 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 . -``` - -Note this command uses the `jq` tool, which you may not have installed: - -```bash -sudo eopkg it jq -``` - -If you have our [helper functions](/docs/packaging/prepare-for-packaging#set-up-repository-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 - -If an established product hasn't had a security advisory in the past, it might not have a CPE. - -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: ~ -``` - -:::tip - -If you are unsure of what to do in this case, feel free to ask in the Solus Packaging Matrix room. - -::: \ No newline at end of file