Merge pull request #2383 from ziadhany/fedcode-docs

fedcode-next: Documentation on how to use the new curation feature

Author: ziadhany

docs/source/advisory-package-curation.rst

@@ -0,0 +1,40 @@
+.. _advisory-package-curation:
+
+Advisory Package Curation
+=========================
+
+Follow these steps to curate the package versions associated with
+vulnerability advisories:
+
+.. image:: images/advisory-package-curation.png
+
+1. Click the alias you want to curate (for example, **CVE-2024-6221**).
+
+2. Select the appropriate package version status.
+
+   - For each package version, click **Select value** and choose one of the following statuses:
+
+     - **AFFECTED**
+     - **FIXED**
+     - **UNAFFECTED**
+
+   .. image:: images/package_select_value.png
+
+   .. note::
+
+      Click **Select value** multiple times to cycle through the available
+      statuses (**AFFECTED**, **FIXED**, and **UNAFFECTED**).
+
+   - if one of the suggested advisories is correct, click **Pick this** to automatically
+     apply the advisory package versions statuses.
+
+   .. image:: images/package_pick_this.png
+
+3. Click **Next item**. If the button is available, repeat steps 2–3 for each
+remaining package.
+
+   .. image:: images/package_next_item.png
+
+4. After reviewing all packages, click **Submit** to save and complete the package curation.
+
+   .. image:: images/package_submit.png

docs/source/advisory-severity-curation.rst

@@ -0,0 +1,24 @@
+.. _advisory-severity-curation:
+
+Advisory Severity Curation
+==========================
+
+Follow these steps to curate the severity associated with vulnerability advisories:
+
+.. image:: images/advisory-severity-curation.png
+
+1. Click the alias you want to curate (for example, ``GHSA-5rfv-66g4-jr8h``)
+
+2. For each key, select the appropriate vector value from the available options
+
+   .. image:: images/severity_select_value.png
+
+   Alternatively, select the correct advisory severity
+
+   .. image:: images/severity_pick_this.png
+
+3. Click **Next item**, if the button is available, and repeat steps 2–3 for each remaining severity
+
+4. Once you have curated all advisories, click **Submit**
+
+   .. image:: images/severity_submit.png

docs/source/advisory-todos.rst

@@ -0,0 +1,66 @@
+.. _advisory_todos:
+
+Advisory Todos
+==============
+
+Overview
+--------
+
+The Advisory To-Dos queue contains security advisories that require
+manual review to improve the quality and accuracy of VulnerableCode
+data.
+
+Supported Advisory Curation Types
+---------------------------------
+
+Our advisory curation process supports enriching and validating the
+following vulnerability advisory metadata, depending on the information
+available from trusted sources:
+
+* **Package Curation**: See :ref:`advisory-package-curation`.
+
+  - Advisories with conflicting **fixed** package versions.
+  - Advisories with conflicting **affected** package versions.
+  - Advisories with conflicting **affected** and **fixed** package
+    versions.
+
+* **Extra Mitigation Curation**: See :ref:`extra-mitigation-curation`.
+
+  - *(Not currently supported)* Advisories missing affected package
+    versions.
+  - Advisories missing fixed package
+    versions.
+  - *(Not currently supported)* Advisories missing both affected and
+    fixed package versions.
+
+* **Severity Curation**: Advisories with conflicting CVSS vectors
+  (CVSSv3, CVSSv3.1, and CVSSv4). See
+  :ref:`advisory-severity-curation`.
+
+* **Weakness Curation**: Advisories with conflicting Common Weakness
+  Enumeration (CWE) identifiers. See
+  :ref:`advisory-weakness-curation`.
+
+* **Summary Curation**: *(Not currently supported).*
+
+Each curation guide provides detailed instructions for reviewing
+advisories in the corresponding curation queue.
+
+Accessing the Advisory To-Dos Queue
+-----------------------------------
+
+1. Go to `public.vulnerablecode.io
+   <https://public.vulnerablecode.io/>`_.
+
+2. Click **Advisory To-Dos**.
+
+   .. image:: images/advisory-to-dos-click.png
+
+3. Click **Continue**.
+
+   .. image:: images/continue-button.png
+
+4. Search for advisories by **Alias**, or filter the list by
+   **Resolved status** or **Issue type**.
+
+   .. image:: images/advisory-to-do-dashbaord.png

docs/source/advisory-weakness-curation.rst

@@ -0,0 +1,22 @@
+.. _advisory-weakness-curation:
+
+Advisory Weakness Curation
+===========================
+
+Follow these steps to curate the `Common Weakness Enumeration (CWE) <https://cwe.mitre.org/>`_ associated with vulnerability advisories:
+
+.. image:: images/advisory-weakness-curation.png
+
+1. Click the Alias you want to curate, for example, ``CVE-2022-24512``.
+
+2. Select the appropriate CWE status (``APPLICABLE`` or ``NOT APPLICABLE``) for the selected CWE ID.
+
+   .. image:: images/weakness_select_value.png
+
+   OR, you can select the CWE status from an advisory that you trust to provide accurate data.
+
+   .. image:: images/weakness_pick_this.png
+
+3. Click **Submit**.
+
+   .. image:: images/weakness_submit.png

docs/source/extra-mitigation-curation.rst

@@ -0,0 +1,63 @@
+.. _extra-mitigation-curation:
+
+Extra Mitigation Curation
+=========================
+
+Extra mitigation curation is currently supported only for vulnerability
+advisories with missing fixed packages.
+
+.. image:: images/extra_mitigation_curation.png
+
+Follow these steps to provide mitigation information for these advisories.
+
+1. Click the alias you want to curate (for example, **UBUNTU-CVE-2026-7790**).
+
+2. Enter the appropriate mitigation types and mitigation data.
+
+   - For each package, provide the mitigation data and
+     notes for the following mitigation types:
+
+     - **Upgrade to Versions**: Specify the version(s) users
+       should upgrade to in order to remediate the vulnerability.
+       Enter one or more fixed versions separated by commas
+       (e.g., 1.0.1, 2.3.4). Use the note field for any
+       additional upgrade guidance or constraints.
+
+     - **Downgrade to Versions**: Specify the version(s) users
+       should downgrade to if no fixed upgrade is available.
+       Enter one or more non-vulnerable versions separated
+       by commas (e.g., 1.0.1, 2.3.4). Use the note field for
+       any additional guidance or cautions related to the downgrade.
+
+     - **Apply Patch**: Provide a URL to the official
+       patch or hotfix that remediates the vulnerability.
+       Use the note field to include any additional
+       instructions, prerequisites, or known limitations.
+
+     - **Change Config**: Provide the configuration changes
+       that mitigate the vulnerability, such as modifying
+       settings, disabling features, or enabling security controls.
+       Use the note field to include any potential side effects
+       or additional implementation guidance.
+
+     - **Apply Network Restrictions**: Specify the network
+       restrictions required to mitigate the vulnerability,
+       such as blocking or limiting access to specific ports,
+       IP addresses, or network ranges. Use the note field
+       to provide firewall rules, scope details, or additional
+       implementation guidance.
+
+     - **Replace Package**: Specify the Package URL of the
+       replacement package to use instead of the vulnerable
+       package. Use the note field for compatibility
+       details or additional guidance.
+
+3. Click **Next item**. If the button is available,
+   repeat steps 2–3 for each remaining package in the queue.
+
+   .. image:: images/extra_mitigation_next_item.png
+
+4. After reviewing all mitigated packages,
+   click **Submit** to save and complete the mitigation curation.
+
+   .. image:: images/extra_mitigation_submit.png