diff --git a/docs/source/advisory-package-curation.rst b/docs/source/advisory-package-curation.rst new file mode 100644 index 000000000..bc9c26942 --- /dev/null +++ b/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 diff --git a/docs/source/advisory-severity-curation.rst b/docs/source/advisory-severity-curation.rst new file mode 100644 index 000000000..990a2c236 --- /dev/null +++ b/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 diff --git a/docs/source/advisory-todos.rst b/docs/source/advisory-todos.rst new file mode 100644 index 000000000..0e7dc2fb8 --- /dev/null +++ b/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 + `_. + +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 diff --git a/docs/source/advisory-weakness-curation.rst b/docs/source/advisory-weakness-curation.rst new file mode 100644 index 000000000..1940d8117 --- /dev/null +++ b/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) `_ 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 diff --git a/docs/source/extra-mitigation-curation.rst b/docs/source/extra-mitigation-curation.rst new file mode 100644 index 000000000..ffc0c3849 --- /dev/null +++ b/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 diff --git a/docs/source/images/advisory-package-curation.png b/docs/source/images/advisory-package-curation.png new file mode 100644 index 000000000..7c8e6b174 Binary files /dev/null and b/docs/source/images/advisory-package-curation.png differ diff --git a/docs/source/images/advisory-severity-curation.png b/docs/source/images/advisory-severity-curation.png new file mode 100644 index 000000000..5241951e9 Binary files /dev/null and b/docs/source/images/advisory-severity-curation.png differ diff --git a/docs/source/images/advisory-to-do-dashbaord.png b/docs/source/images/advisory-to-do-dashbaord.png new file mode 100644 index 000000000..97116abac Binary files /dev/null and b/docs/source/images/advisory-to-do-dashbaord.png differ diff --git a/docs/source/images/advisory-to-dos-click.png b/docs/source/images/advisory-to-dos-click.png new file mode 100644 index 000000000..974fcd352 Binary files /dev/null and b/docs/source/images/advisory-to-dos-click.png differ diff --git a/docs/source/images/advisory-weakness-curation.png b/docs/source/images/advisory-weakness-curation.png new file mode 100644 index 000000000..137e707e9 Binary files /dev/null and b/docs/source/images/advisory-weakness-curation.png differ diff --git a/docs/source/images/continue-button.png b/docs/source/images/continue-button.png new file mode 100644 index 000000000..788bab118 Binary files /dev/null and b/docs/source/images/continue-button.png differ diff --git a/docs/source/images/extra_mitigation_curation.png b/docs/source/images/extra_mitigation_curation.png new file mode 100644 index 000000000..056bcd2bd Binary files /dev/null and b/docs/source/images/extra_mitigation_curation.png differ diff --git a/docs/source/images/extra_mitigation_next_item.png b/docs/source/images/extra_mitigation_next_item.png new file mode 100644 index 000000000..87995395e Binary files /dev/null and b/docs/source/images/extra_mitigation_next_item.png differ diff --git a/docs/source/images/extra_mitigation_submit.png b/docs/source/images/extra_mitigation_submit.png new file mode 100644 index 000000000..c187cca70 Binary files /dev/null and b/docs/source/images/extra_mitigation_submit.png differ diff --git a/docs/source/images/package_next_item.png b/docs/source/images/package_next_item.png new file mode 100644 index 000000000..1645df7b9 Binary files /dev/null and b/docs/source/images/package_next_item.png differ diff --git a/docs/source/images/package_pick_this.png b/docs/source/images/package_pick_this.png new file mode 100644 index 000000000..e8680f704 Binary files /dev/null and b/docs/source/images/package_pick_this.png differ diff --git a/docs/source/images/package_select_value.png b/docs/source/images/package_select_value.png new file mode 100644 index 000000000..0c7537f58 Binary files /dev/null and b/docs/source/images/package_select_value.png differ diff --git a/docs/source/images/package_submit.png b/docs/source/images/package_submit.png new file mode 100644 index 000000000..75410097f Binary files /dev/null and b/docs/source/images/package_submit.png differ diff --git a/docs/source/images/severity_pick_this.png b/docs/source/images/severity_pick_this.png new file mode 100644 index 000000000..15e6cb837 Binary files /dev/null and b/docs/source/images/severity_pick_this.png differ diff --git a/docs/source/images/severity_select_value.png b/docs/source/images/severity_select_value.png new file mode 100644 index 000000000..48d5049b0 Binary files /dev/null and b/docs/source/images/severity_select_value.png differ diff --git a/docs/source/images/severity_submit.png b/docs/source/images/severity_submit.png new file mode 100644 index 000000000..1e0229e1e Binary files /dev/null and b/docs/source/images/severity_submit.png differ diff --git a/docs/source/images/weakness_pick_this.png b/docs/source/images/weakness_pick_this.png new file mode 100644 index 000000000..0718a385c Binary files /dev/null and b/docs/source/images/weakness_pick_this.png differ diff --git a/docs/source/images/weakness_select_value.png b/docs/source/images/weakness_select_value.png new file mode 100644 index 000000000..1c4289d81 Binary files /dev/null and b/docs/source/images/weakness_select_value.png differ diff --git a/docs/source/images/weakness_submit.png b/docs/source/images/weakness_submit.png new file mode 100644 index 000000000..10422fbe4 Binary files /dev/null and b/docs/source/images/weakness_submit.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index dbfb61c49..30831c4bf 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -31,6 +31,17 @@ importers_link PIPELINES-AVID +.. toctree:: + :hidden: + :maxdepth: 1 + :caption: Advisory Curation + + advisory-todos + advisory-package-curation + advisory-severity-curation + advisory-weakness-curation + extra-mitigation-curation + .. toctree:: :hidden: :maxdepth: 1 @@ -49,7 +60,7 @@ vulnerabilities with comprehensive information from upstream and downstream publ sources including packages affected by a vulnerability advisories and packages that fix a vulnerability advisory. -There is a `public vulnerableCode database `_ +There is a `Public VulnerableCode Database `_ and the project also provides the tools to build your own instance of the database. Documentation overview @@ -109,6 +120,13 @@ Consult the reference to understand VulnerableCode concepts. .. rst-class:: row clearfix +Advisory Curation +~~~~~~~~~~~~~~~~~ + +Learn how to review and curate vulnerability advisories. + +- :ref:`advisory_todos` + Misc ~~~~~~~~~~~~~~~ diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 00b5d7fc3..70606aba7 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -93,8 +93,8 @@ a CPE. This makes answers to questions such as "Is package *foo* vulnerable to vulnerability *bar*?" more accurate and easier to interpret. The primary access to VulnerableCode data is through a REST API, but there -is also a Web UI for searching and browsing vulnerabilities by package -or by vulnerability. For the initial releases both access modes are +is also a Web UI for searching and browsing vulnerability advisories by package. +For the initial releases both access modes are read-only, but our longer-term goal is to enable community curation of the data including addition of new packages and vulnerabilities, and reviewing and updating their relationships.