From 0f7292fc22f6257bb1be5edce8e090f2af59f740 Mon Sep 17 00:00:00 2001 From: Dheyay Date: Thu, 28 Mar 2024 12:37:28 -0700 Subject: [PATCH] docs: Added CVE docs --- docs/howtoguides.rst | 9 ++ .../how_to_know_if_system_affected_by_cve.rst | 101 ++++++++++++++++++ docs/howtoguides/how_to_resolve_given_cve.rst | 60 +++++++++++ 3 files changed, 170 insertions(+) create mode 100644 docs/howtoguides/how_to_know_if_system_affected_by_cve.rst create mode 100644 docs/howtoguides/how_to_resolve_given_cve.rst diff --git a/docs/howtoguides.rst b/docs/howtoguides.rst index 0e9da07ae4..72c1197070 100644 --- a/docs/howtoguides.rst +++ b/docs/howtoguides.rst @@ -104,6 +104,15 @@ Ubuntu Pro Client for Clouds Create a customised Cloud Ubuntu Pro image Cloud Ubuntu Pro images with FIPS updates +CVE/USN resolution +================== + +.. toctree:: + :maxdepth: 1 + + How to know if a system is affected by a CVE/USN + Resolving a given CVE/USN + Fixing multiple CVEs ==================== diff --git a/docs/howtoguides/how_to_know_if_system_affected_by_cve.rst b/docs/howtoguides/how_to_know_if_system_affected_by_cve.rst new file mode 100644 index 0000000000..6c9909b659 --- /dev/null +++ b/docs/howtoguides/how_to_know_if_system_affected_by_cve.rst @@ -0,0 +1,101 @@ +.. _pro-fix-check-cve: + +How to Determine if Your System is Affected by a CVE/USN? +******************************************************* + +.. include:: ../includes/pro-fix-intro.txt + + +If you've come across a Common Vulnerabilities and Exposure (CVE) or a Ubuntu Security Notification (USN) and want to check if your Ubuntu system is vulnerable, you can easily check using the `pro fix` command. In this guide we'll show you how to determine if your system is affected by a specific CVE: + +..note:: + The `pro fix` command is part of the `pro` package, which is a security tool for Ubuntu systems. If you don't have it installed, you can install it by following the instructions in the `pro` package documentation. + +Performing a Dry Run +==================== + +A dry run allows you to simulate the execution of the ``pro fix`` command without actually making any changes to your system. This is useful for checking if a CVE affects your system and if a fix is available. + +Let's see what happens when we perform a dry run with the ``pro fix`` command. + +Every ``pro fix`` output has a similar output structure. It: + +* describes the CVE/USN; +* displays the affected packages; +* fixes the affected packages; and +* at the end, shows if the CVE/USN is fully fixed in the machine. + + +To perform a dry run, use the ``--dry-run`` option with the ``pro fix`` command followed by the CVE identifier: + +.. code-block:: bash + + $ pro fix --dry-run CVE-XXXX-XXXX + +Replace ``CVE-XXXX-XXXX`` with the actual CVE identifier you want to check. + +Output of a Dry Run +=================== + +The output of the dry run will indicate whether your system is affected by the CVE and if a fix is available. Here are some possible scenarios: + +CVE does not affect your system +-------------------------------- + + .. code-block:: text + + CVE-XXXX-XXXX: Some vulnerability + - https://ubuntu.com/security/CVE-XXXX-XXXX + + No affected source packages are installed. + + ✔ CVE-XXXX-XXXX does not affect your system. + +CVE affects your system, and a fix is available +----------------------------------------------- + + .. code-block:: text + + CVE-XXXX-XXXX: Some vulnerability + - https://ubuntu.com/security/CVE-XXXX-XXXX + + 1 affected source package is installed: package-name + (1/1) package-name: + A fix is available in Ubuntu standard updates. + { apt update && apt install --only-upgrade -y package-name } + + ✔ CVE-XXXX-XXXX can be resolved. + +CVE affects your system, but no fix is available +----------------------------------------------- + + .. code-block:: text + + CVE-XXXX-XXXX: Some vulnerability + - https://ubuntu.com/security/CVE-XXXX-XXXX + + 1 affected source package is installed: package-name + Ubuntu security engineers are investigating this issue. + + ✘ CVE-XXXX-XXXX is not resolved. + + +Here we see how performing a dry run with the ``pro fix`` command is a quick and safe way to check if your system is affected by a specific CVE and also see if a fix is available. + +Success! +========== + +We have successfully determined if our system is affected by a specific CVE using the `pro fix` command. If a fix is available, you can proceed to apply the fix by running the command provided in the output. +To learn how to resolve a CVE using the `pro fix` command, refer to the guide on :ref:`How to resolve a CVE/USN? <_pro-fix-resolve-cve>`. + +Additional Resources +-------------------- + +This is not the only scenario where you might want to use ``pro fix``. To find out about the other situations where it can be useful, as well as which options can be used to give you greater control over the command, you can refer to the following guides: + +* In :ref:`Understanding scenarios encountered when using pro fix to solve a CVE/USN ` you can continue learning more about the different scenarios you might encounter and understand the different outputs you will find. +* :ref:`How do I know what the pro fix command would change? ` will show you how to use ``pro fix`` in ``--dry-run`` mode to safely simulate the changes before they're applied. +* :ref:`How to skip fixing related USNs ` will show you how to only fix a single USN, even if other fixes are available. + +.. Instructions for how to connect with us +.. include:: ../includes/contact.txt diff --git a/docs/howtoguides/how_to_resolve_given_cve.rst b/docs/howtoguides/how_to_resolve_given_cve.rst new file mode 100644 index 0000000000..d1eb791ae0 --- /dev/null +++ b/docs/howtoguides/how_to_resolve_given_cve.rst @@ -0,0 +1,60 @@ +.. _pro-fix-resolve-cve: + +How to resolve a given CVE/USN? +*************************** + +In this guide, we will introduce the ``pro fix`` command and go into more details about the different scenarios you may encounter when using ``pro fix`` to resolve CVEs/USNs. + +.. note:: + + If you are looking for a simpler guided tutorial to get started with + ``pro fix``, please refer to the tutorial on + :ref:`Using pro fix to solve a CVE/USN `. + You can use the same VM-based environment created in that tutorial + to recreate the output shown below yourself. If you have already completed the tutorial, you may want to :ref:`skip this section `. + + +Use ``pro fix`` +=============== + +First, let's see what happens to your system when ``pro fix`` runs. +Every ``pro fix`` output has a similar output structure. It: + +* describes the CVE/USN; +* displays the affected packages; +* fixes the affected packages; and +* at the end, shows if the CVE/USN is fully fixed in the machine. + +.. # The basic case is shared between Howto and Tutorial +.. include:: ../includes/pro-fix-simple-case.txt +.. _CVE-no-fix: + + +Success +======= + +Congratulations! You have successfully learned to resolve a CVE/USN on your system. +There might be other cases which you might encounter when using ``pro fix`` to resolve a CVE/USN. You can learn more about these cases in the guide detailing :ref:`Common scenarios encountered when using pro fix to solve a CVE/USN `. + +Additional Resources +-------------------- + +We have successfully encountered and resolved the main scenarios that you might +find when you run ``pro fix`` . + +This is not the only scenario where you might want to use ``pro fix`` . To find out about the other situations where it can be useful, as well as which options can be used to give you greater control over the command, you can refer to the following guides: + +* :ref:`How do I know what the pro fix command would change? ` will show you how to use ``pro fix`` in ``--dry-run`` mode to safely simulate the changes before they're applied. +* :ref:`How to skip fixing related USNs ` will show you how to only fix a single USN, even if other fixes are available. + +.. Instructions for how to connect with us +.. include:: ../includes/contact.txt + +.. LINKS + +.. include:: ../links.txt + +.. _CVE-2020-15180: https://ubuntu.com/security/CVE-2020-15180 +.. _CVE-2020-25686: https://ubuntu.com/security/CVE-2020-25686 +.. _Pro_: https://ubuntu.com/pro +