From 5463ad02971c541810639bfbb36d576350fdb0fb Mon Sep 17 00:00:00 2001
From: Grant Orndorff <grant.orndorff@canonical.com>
Date: Tue, 22 Oct 2024 11:14:13 -0400
Subject: [PATCH] docs: added howto guide to check if a system is affected by a
 list of CVEs

---
 docs/howtoguides/fix_index.rst                |  2 +
 ...w_if_system_affected_by_a_list_of_cves.rst | 56 +++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 docs/howtoguides/how_to_know_if_system_affected_by_a_list_of_cves.rst

diff --git a/docs/howtoguides/fix_index.rst b/docs/howtoguides/fix_index.rst
index 0330d4e348..160c287e39 100644
--- a/docs/howtoguides/fix_index.rst
+++ b/docs/howtoguides/fix_index.rst
@@ -4,6 +4,7 @@ Fix vulnerabilities
 * :ref:`Is my system affected by this specific CVE? <pro-fix-check-cve>`
 * :ref:`Resolve a single CVE or USN? <pro-fix-resolve-cve>`
 * :ref:`How to know what the fix command would change <pro-fix-dry-run>`
+* :ref:`How to know if a system is affected by a list of CVEs? <pro-check-list-cves>`
 * :ref:`Skip fixing related USNs <pro-fix-skip-related>`
 * :ref:`Better visualise results when fixing multiple CVEs <how_to_better_visualise_fixing_multiple_cves>`
 
@@ -16,5 +17,6 @@ Fix vulnerabilities
    Is my system affected by this specific CVE? <fix_how_to_know_if_system_affected_by_cve>
    Resolve a single CVE or USN <fix_how_to_resolve_given_cve>
    Discover what the `fix` command would change <fix_how_to_know_what_the_fix_command_would_change>
+   How to know if a system is affected by a list of CVEs? <how_to_know_if_system_affected_by_a_list_of_cves>
    Skip fixing related USNs <fix_how_to_not_fix_related_usns>
    Better visualise results when fixing multiple CVEs <fix_how_to_better_visualise_fixing_multiple_cves>
diff --git a/docs/howtoguides/how_to_know_if_system_affected_by_a_list_of_cves.rst b/docs/howtoguides/how_to_know_if_system_affected_by_a_list_of_cves.rst
new file mode 100644
index 0000000000..df850540db
--- /dev/null
+++ b/docs/howtoguides/how_to_know_if_system_affected_by_a_list_of_cves.rst
@@ -0,0 +1,56 @@
+.. _pro-check-list-cves:
+
+Check if a system is affected by a list of CVEs?
+*********************************************************
+
+.. include:: ../includes/pro-fix-intro.txt
+
+If you have a list of `Common Vulnerabilities and Exposure <cve_>`_ (CVEs) and `Ubuntu Security Notice <usn_>`_ (USNs) and want to check if your Ubuntu system is affected by it, you can check using the ``u.pro.security.fix.cve.plan.v1`` API endpoint as we'll show you in this guide.
+
+.. note::
+    The ``u.pro.security.fix.cve.plan`` API is provided as a part of the Ubuntu Pro Client (``pro``), which is a security tool for Ubuntu systems. The Ubuntu Pro Client comes pre-installed on every Ubuntu system. You can run ``pro help`` in your terminal window to see a list of the ``pro`` services and commands available.
+
+Using the ``pro.fix.cve.plan`` API
+----------------------------------
+
+To check if your system is affected by a list of CVEs, you need to use the ``u.pro.security.fix.cve.plan.v1`` API endpoint since the
+``pro fix --dry-run`` CLI command is only used to check individual CVEs. This endpoint will output a JSON blob containing the current status of each CVE, as can be seen :ref:`in the endpoint documentation<references/api:u.pro.security.fix.cve.execute.v1>`.
+
+To better visualise the current status of each CVE from the JSON output we can use a ``jq`` filter.
+The ``jq`` command can parse JSON data directly in the terminal, creating a more readable output.
+To know more about it, please refer to `the jq manpage <https://manpages.ubuntu.com/manpages/xenial/man1/jq.1.html>`_
+
+First, we need to install ``jq`` by running the following command:
+
+.. code-block:: bash
+
+    sudo apt update & sudo apt install jq -y
+
+Once ``jq`` is installed, we can parse the JSON data returned from the plan API.
+
+For example, if we want to see if our system is affected by the following CVEs: **CVE-2020-28196, CVE-2020-15180**
+and **CVE-2017-9233**.
+
+We make use of the plan API by running the following command:
+
+.. code-block:: bash
+
+    pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-2020-28196", "CVE-2020-15180", "CVE-2017-9233"]}' \ 
+        | jq -r '.data.attributes.cves_data.cves[] | "\(.title) (\(.description)) - Current Status: \(.current_status)"'
+
+This command returns output with the following structure:
+
+.. code-block:: bash
+
+    CVE-2020-28196 (Kerberos vulnerability) - Current Status: not-affected
+    CVE-2020-15180 (MariaDB vulnerabilities) - Current Status: not-affected
+    CVE-2017-9233 (Coin3D vulnerability) - Current Status: not-affected
+
+Note that each entry in this output consists of three fields:
+
+* **CVE NAME**: The name of the CVE
+* **CVE DESCRIPTION**: The description of the CVE
+* **CVE STATUS**: The current status of the CVE
+
+.. LINKS
+.. include:: ../links.txt