documentation: Add content about Vulnerability roundups

Signed-off-by: Pamplemousse <xav.maso@gmail.com>

3 files changed, 56 insertions, 9 deletions

diff --git a/doc/contributing/submitting-changes.chapter.md b/doc/contributing/submitting-changes.chapter.md
index 44e981f12a5..13f15b929cf 100644
--- a/doc/contributing/submitting-changes.chapter.md
+++ b/doc/contributing/submitting-changes.chapter.md
@@ -68,15 +68,16 @@
 
 Security fixes are submitted in the same way as other changes and thus the same guidelines apply.
 
-If the security fix comes in the form of a patch and a CVE is available, then the name of the patch should be the CVE identifier, so e.g. `CVE-2019-13636.patch` in the case of a patch that is included in the Nixpkgs tree. If a patch is fetched the name needs to be set as well, e.g.:
-
-```nix
-(fetchpatch {
-  name = "CVE-2019-11068.patch";
-  url = "https://gitlab.gnome.org/GNOME/libxslt/commit/e03553605b45c88f0b4b2980adfbbb8f6fca2fd6.patch";
-  sha256 = "0pkpb4837km15zgg6h57bncp66d5lwrlvkr73h0lanywq7zrwhj8";
-})
-```
+- If a new version fixing the vulnerability has been released, update the package;
+- If the security fix comes in the form of a patch and a CVE is available, then add the patch to the Nixpkgs tree, and apply it to the package.
+  The name of the patch should be the CVE identifier, so e.g. `CVE-2019-13636.patch`; If a patch is fetched the name needs to be set as well, e.g.:
+  ```nix
+  (fetchpatch {
+    name = "CVE-2019-11068.patch";
+    url = "https://gitlab.gnome.org/GNOME/libxslt/commit/e03553605b45c88f0b4b2980adfbbb8f6fca2fd6.patch";
+    sha256 = "0pkpb4837km15zgg6h57bncp66d5lwrlvkr73h0lanywq7zrwhj8";
+  })
+  ```
 
 If a security fix applies to both master and a stable release then, similar to regular changes, they are preferably delivered via master first and cherry-picked to the release branch.
 
diff --git a/doc/contributing/vulnerability-roundup.chapter.md b/doc/contributing/vulnerability-roundup.chapter.md
new file mode 100644
index 00000000000..d451420f981
--- /dev/null
+++ b/doc/contributing/vulnerability-roundup.chapter.md
@@ -0,0 +1,45 @@
+# Vulnerability Roundup {#chap-vulnerability-roundup}
+
+## Issues {#vulnerability-roundup-issues}
+
+Vulnerable packages in Nixpkgs are managed using issues.
+Currently opened ones can be found using the following:
+
+[github.com/NixOS/nixpkgs/issues?q=is:issue+is:open+"Vulnerability+roundup"](https://github.com/NixOS/nixpkgs/issues?q=is%3Aissue+is%3Aopen+%22Vulnerability+roundup%22)
+
+Each issue correspond to a vulnerable version of a package; As a consequence:
+
+- One issue can contain several CVEs;
+- One CVE can be shared across several issues;
+- A single package can be concerned by several issues.
+
+
+A "Vulnerability roundup" issue usually respects the following format:
+
+```txt
+<link to relevant package search on search.nix.gsc.io>, <link to relevant files in Nixpkgs on GitHub>
+
+<list of related CVEs, their CVSS score, and the impacted NixOS version>
+
+<list of the scanned Nixpkgs versions>
+
+<list of relevant contributors>
+```
+
+Note that there can be an extra comment containing links to previously reported (and still open) issues for the same package.
+
+
+## Triaging and Fixing {#vulnerability-roundup-triaging-and-fixing}
+
+**Note**: An issue can be a "false positive" (i.e. automatically opened, but without the package it refers to being actually vulnerable).
+If you find such a "false positive", comment on the issue an explanation of why it falls into this category, linking as much information as the necessary to help maintainers double check.
+
+If you are investigating a "true positive":
+
+- Find the earliest patched version or a code patch in the CVE details;
+- Is the issue already patched (version up-to-date or patch applied manually) in Nixpkgs's `master` branch?
+  - **No**:
+    - [Submit a security fix](#submitting-changes-submitting-security-fixes);
+    - Once the fix is merged into `master`, [submit the change to the vulnerable release branch(es)](https://nixos.org/manual/nixpkgs/stable/#submitting-changes-stable-release-branches);
+  - **Yes**: [Backport the change to the vulnerable release branch(es)](https://nixos.org/manual/nixpkgs/stable/#submitting-changes-stable-release-branches).
+- When the patch has made it into all the relevant branches (`master`, and the vulnerable releases), close the relevant issue(s).
diff --git a/doc/manual.xml b/doc/manual.xml
index b0490ec74ae..dd1434fce02 100644
--- a/doc/manual.xml
+++ b/doc/manual.xml
@@ -35,6 +35,7 @@
   <xi:include href="contributing/quick-start.xml" />
   <xi:include href="contributing/coding-conventions.xml" />
   <xi:include href="contributing/submitting-changes.chapter.xml" />
+  <xi:include href="contributing/vulnerability-roundup.chapter.xml" />
   <xi:include href="contributing/reviewing-contributions.xml" />
   <xi:include href="contributing/contributing-to-documentation.xml" />
  </part>