From 46ebc2eaee9fb4c06ab46925ce30b420b2fa7c9b Mon Sep 17 00:00:00 2001 From: Lucas Moura Date: Fri, 8 Nov 2024 18:12:56 -0300 Subject: [PATCH] docs: apply feedback to vulnerability docs --- docs/explanations.rst | 12 ++-- ...ty_list.rst => pro_vulnerability_list.rst} | 56 +++++++++---------- ...ty_show.rst => pro_vulnerability_show.rst} | 46 +++++++-------- .../what_is_a_fixable_vulnerability.rst | 7 --- docs/howtoguides.rst | 2 +- ...se_manifest_file_for_pro_vulnerability.rst | 21 +++---- 6 files changed, 71 insertions(+), 73 deletions(-) rename docs/explanations/{how_to_interpret_output_of_pro_vulnerability_list.rst => pro_vulnerability_list.rst} (55%) rename docs/explanations/{how_to_interpret_output_of_pro_vulnerability_show.rst => pro_vulnerability_show.rst} (75%) delete mode 100644 docs/explanations/what_is_a_fixable_vulnerability.rst diff --git a/docs/explanations.rst b/docs/explanations.rst index 9eb77127ba..ce8c7e2afb 100644 --- a/docs/explanations.rst +++ b/docs/explanations.rst @@ -34,17 +34,21 @@ selection of some of the commands -- what they do, and how they work. explanations/what_refresh_does.md explanations/purging_services.md -Vulnerability Commands +Vulnerability commands ====================== Here we'll show you the information related to ``pro vulnerability`` commands. +On any ``pro vulnerability`` command, we consider a vulnerability (CVE or USN) as **fixable**, +if and only if, at least **one** affected installed package associated with it can +be fixed. That means that a vulnerability is unfixable if no affected installed packages +related to the vulnerability can be fixed at the moment. + .. toctree:: :maxdepth: 1 - explanations/how_to_interpret_output_of_pro_vulnerability_list.md - explanations/how_to_interpret_output_of_pro_vulnerability_show.md - explanations/what_is_a_fixable_vulnerability.md + explanations/pro_vulnerability_list.md + explanations/pro_vulnerability_show.md Public Cloud Ubuntu Pro ======================= diff --git a/docs/explanations/how_to_interpret_output_of_pro_vulnerability_list.rst b/docs/explanations/pro_vulnerability_list.rst similarity index 55% rename from docs/explanations/how_to_interpret_output_of_pro_vulnerability_list.rst rename to docs/explanations/pro_vulnerability_list.rst index 9bd2004b23..bed9adee80 100644 --- a/docs/explanations/how_to_interpret_output_of_pro_vulnerability_list.rst +++ b/docs/explanations/pro_vulnerability_list.rst @@ -1,11 +1,11 @@ .. _pro-vulnerability-list: -How to interpret the output of pro vulnerability list +The pro vulnerability list command ******************************************************** In the Pro Client version 35, we introduce the ``pro vulnerability list`` command. -This commands will display by default all the CVEs that are currently affecting the -system. Let's take a look on an example when running this command: +This command displays all the CVEs currently affecting the +system. Let's take a look at an example when running this command: .. code-block:: text @@ -29,7 +29,7 @@ system. Let's take a look on an example when running this command: 8 fixable via Ubuntu Pro (1 critical, 1 high, 4 medium, 1 low, 1 negligible) 2 fixable via Ubuntu Security (1 high, 1 low) -We can see that the command has three distinct sections. Let's analyze each of them: +We can see that the command has three distinct sections. Let's analyse each of them: .. code-block:: text @@ -49,20 +49,20 @@ We can see that the command has three distinct sections. Let's analyze each of t The first part of the output is a table showing all **fixable** CVEs in the system. The table contains these four distinct columns: -* **VULNERABILITY**: The name of the CVE -* **PRIORITY**: The ubuntu priority for the CVE -* **FIX AVAILABLE FROM**: The ubuntu pocket where the fix can be found: - * **esm-infra**: Fix is availabe on the esm-infra pocket. This means that user must have esm-infra service enabled through Pro in the machine to access it - * **esm-apps**: Fix is availabe on the esm-apps pocket. This means that user must have esm-apps service enabled through Pro in the machine to access it - * **fips**: Fix is availabe on the fips pocket. This means that user must have fips service enabled through Pro in the machine to access it - * **fips-updates**: Fix is availabe on the fips-updates pocket. This means that user must have fips-updates service enabled through Pro in the machine to access it - * **security**: The ubuntu security pocket - * **updates**: The ubuntu updates pocket - * **no-fix**: No fix is yet available for this CVE -* **AFFECTED INSTALLED PACKAGES**: The affected installed packages related to the CVE +* **VULNERABILITY**: The name of the CVE. +* **PRIORITY**: The Ubuntu priority for the CVE. +* **FIX AVAILABLE FROM**: The Ubuntu pocket where the fix can be found: + * ``esm-infra``: Fix is availabe from the ``esm-infra`` pocket. The user must have the ``esm-infra`` service enabled through Pro on the machine to access it. + * ``esm-apps``: Fix is availabe from the ``esm-apps`` pocket. The user must have the ``esm-apps`` service enabled through Pro on the machine to access it. + * ``fips``: Fix is availabe from the ``fips`` pocket. The user must have the ``fips`` service enabled through Pro on the machine to access it. + * ``fips-updates``: Fix is availabe from the ``fips-updates`` pocket. The user must have the ``fips-updates`` service enabled through Pro on the machine to access it. + * ``security``: The Ubuntu ``security`` pocket. + * ``updates``: The Ubuntu ``updates`` pocket. + * ``no-fix``: No fix is available yet for this CVE. +* **AFFECTED INSTALLED PACKAGES**: The installed packages affected by the CVE. Finally, note that the table is ordered by **PRIORITY**. This means that CVEs with higher -priority will appear first on the table. +priority will appear first in the table. Now, let's look at the next section: @@ -73,11 +73,11 @@ Now, let's look at the next section: This section details the CVEs that already have fixes applied for them. For example, suppose we have a CVE named **CVE-2021-12345** and this -CVE affects two packages, pkg1 and pkg2. If the we detect that pkg1 is already fixed -in the machine even if pkg2 is still affected, we will count this CVE here. +CVE affects two packages, ``pkg1`` and ``pkg2``. If the we detect that ``pkg1`` is already fixed +on the machine, then even if ``pkg2`` is still affected, we include this CVE here. Therefore, this section presents a summary of all CVEs that have at least **one** fix already -applied for it. Addionally, note that we also display the count by ubuntu priority as well. +applied for it. Note that we also order the count by Ubuntu priority as well. Finally, let's look at the last section: @@ -87,13 +87,13 @@ Finally, let's look at the last section: 8 fixable via Ubuntu Pro (1 critical, 1 high, 4 medium, 1 low, 1 negligible) 2 fixable via Ubuntu Security (1 high, 1 low) -While the previous section show CVEs with fixes already applied, this section show CVE with fixes -available, but not yet applied. This means that the user can actively fix those issues by upgrading -the affected packages. However, note that we also split by the type of service. If the fix is -available by a service that requires Pro, it will go under **Ubuntu Pro**. If that is not the case, -we will classify the CVE as **Ubuntu Security** instead. This means that some fixes will only be available -if the user is attached to a Pro subscription and have the necessary service enabled (i.e. esm-infra). +While the previous section showed CVEs with fixes already applied, this section shows CVEs with fixes +available, but not yet applied. The user can actively fix those CVEs by upgrading +the affected packages. However, note that we also split the vulnerability according to the source of +the fix. If the fix is +available from a service that requires Pro, it will fall under **Ubuntu Pro**. Otherwise, +we will classify the CVE as falling under **Ubuntu Security** instead. This means that some fixes will only be available +if the user is attached to a Pro subscription and has the necessary service enabled (i.e. ``esm-infra``). -Finally, note that we also group the count by ubuntu priority here as well. If the table is too long, -breaking the count by priority allows user to better visualize the overal risk of the CVEs without the -need to look at the whole table to access that information. +Note that we group the count by Ubuntu priority here as well. If the table is long, +breaking the count by priority provides better visualisation of the overall risk of the CVEs. diff --git a/docs/explanations/how_to_interpret_output_of_pro_vulnerability_show.rst b/docs/explanations/pro_vulnerability_show.rst similarity index 75% rename from docs/explanations/how_to_interpret_output_of_pro_vulnerability_show.rst rename to docs/explanations/pro_vulnerability_show.rst index b1f4d4e7dc..417719d28a 100644 --- a/docs/explanations/how_to_interpret_output_of_pro_vulnerability_show.rst +++ b/docs/explanations/pro_vulnerability_show.rst @@ -1,9 +1,11 @@ -How to interpret the output of pro vulnerability show +.. _pro-vulnerability-show: + +The pro vulnerability show command ***************************************************** -If you suspect that a CVE affects your system and wants to verify -if that is true, you can use the ``pro vulnerability show`` command for this. -This command will show you all the related information to a CVE **if** it affects +If you suspect that a CVE affects your system and want to verify +that, you can use the ``pro vulnerability show`` command. +This command shows you all the relevant information about a CVE **if** it affects your system. For example, let's assume that ``CVE-2022-2286`` affects your system and you run: @@ -39,38 +41,36 @@ You will see an output similar to this one: VULNERABILITY TITLE AFFECTED INSTALLED PACKAGES USN-6270-1 Vim vulnerabilities vim -Let's break it down the output of this command. We start by telling you some basic information for +Let's break down the output of this command. It starts with some basic information for the CVE: -* **Public URL**: The ubuntu security page for this CVE +* **Public URL**: The Ubuntu Security page for this CVE * **Published at**: The published date for the CVE -* **Ubunut vulnerability data published at**: The published for the vulnerability data we consume to - generate this output +* **Ubunut vulnerability data published at**: The published date for the vulnerability data we consume to generate this output * **APT package information updated at**: The last time the APT state was updated in the system - (i.e. running an apt install operation) -* **Ubuntu priority**: The ubuntu priority for this CVE + (i.e. running an ``apt install`` operation) +* **Ubuntu priority**: The Ubuntu priority for this CVE * **CVSS score**: The CVSS score of the CVE * **CVESS severity**: The CVSS severity of the CVE After that, we display the CVE description and related notes (if the CVE has notes). -The next block is now displaying which installed packages in the machine are affected by the CVE. -Whe are using table to display those affected packages where: +The next block shows which packages installed on the machine are affected by the CVE. +We use a table to display the affected packages with the following columns: * **NAME**: The package name * **STATUS**: The CVE status for this package * **CURRENT VERSION**: The current installed version of the package -* **FIXED BY**: The version of that package that fix the CVE issue -* **FIX AVAILABLE FROM**: The pocket where the fix version can be found on +* **FIXED BY**: The version of the package that fixes the CVE issue +* **FIX AVAILABLE FROM**: The pocket where the fix version can be found -Finally, we also display the related USNs to the CVE, in case you want to take a look on them as -well. +Finally, we also display any USNs related to the CVE. What if the CVE doesn't affect my system ? ========================================== -If the CVE doesn't affect your system, running the ``pro vulnerability show`` will show -you the an output like this: +If the CVE doesn't affect your system, running ``pro vulnerability show`` will show +you an output like this: .. code-block:: text @@ -99,13 +99,13 @@ fixed: python3.5 vulnerable 3.5.2-2ubuntu0~16.04.13 - no-fix python3.5-minimal vulnerable 3.5.2-2ubuntu0~16.04.13 - no-fix -Note that the package status show that it is **vulnerabable** and that the **FIXED BY** and -**FIX AVAILABLE FROM** column will tell you that no fix is available for the package. +The status column shows the package is **vulnerabable**, but the **FIXED BY** and +**FIX AVAILABLE FROM** column tell you that no fix is available for the package. What if I want to see a USN instead ? ===================================== -To see information about a USN, you just need to provide a USN name instead. For example, +To see information about a USN, you can provide a USN name instead. For example, to see information about USN-4976-2 you can run: .. code-block:: bash @@ -144,8 +144,8 @@ Assuming you are affected by the USN, you might see an output like this: CVE-2021-3448 low dnsmasq -Note that the information presented here is similar to the one display for the CVE. -However, we are not displaying information that is only tied to a CVE, such as +The information presented here is similar to the output displayed for CVEs. +However, we do not display information that is only relevant to a CVE, such as CVSS score and Ubuntu priority. Finally, note that the last table is called Related CVEs instead, since we are now diff --git a/docs/explanations/what_is_a_fixable_vulnerability.rst b/docs/explanations/what_is_a_fixable_vulnerability.rst deleted file mode 100644 index 17b69ee2d2..0000000000 --- a/docs/explanations/what_is_a_fixable_vulnerability.rst +++ /dev/null @@ -1,7 +0,0 @@ -What is a fixable vulnerability ? -********************************* - -On any ``pro vulnerability``, we consider a vulnerability (CVE or USN) as **fixable**, -if and only if, at least **one** affected installed package associated with it can -be fixed. That means that a vulnerability is unfixable if no affected installed packages -related to the vulnerability can be fixed at the moment. diff --git a/docs/howtoguides.rst b/docs/howtoguides.rst index d53f1c9b3c..1b761ae7cf 100644 --- a/docs/howtoguides.rst +++ b/docs/howtoguides.rst @@ -55,7 +55,7 @@ Vulnerability commands .. toctree:: :maxdepth: 1 - Display USNs that affectt the system... + Display USNs that affect the system... Provide manifest file to commands... Update vulnerability data... diff --git a/docs/howtoguides/how_to_use_manifest_file_for_pro_vulnerability.rst b/docs/howtoguides/how_to_use_manifest_file_for_pro_vulnerability.rst index c958b1f64d..0d4adb4889 100644 --- a/docs/howtoguides/how_to_use_manifest_file_for_pro_vulnerability.rst +++ b/docs/howtoguides/how_to_use_manifest_file_for_pro_vulnerability.rst @@ -1,25 +1,26 @@ How to provide a manifest file to pro vulnerability commands ************************************************************ -If you want to provide a manifest file to either ``pro vulnerability show`` or -``pro vulnerability list``, you can use the flag ``--manifest-file``. For example: +Let's assume that you want to verify the vulnerability situation of a different +machine than the one you are using. You can achieve that by providing a **manifest file** +to either ``pro vulnerability show`` or ``pro vulnerability list`` by providing the flag ``--manifest-file``. For example: .. code-block:: bash pro vulnerability list --manifest-file=MANIFEST_FILE_PATH -Now, be aware that when providing a manifest file to either of the commands, we will -interpret that the manifest file was generated for the **same** ubuntu release the -the machine is running on. For example, if you are running on the command on Xenial -machine and provides a manifest for the command, the command will believe that the -manifest also represents a Xenial machine. If that is not the case, you **need** to -provide the ``--series`` parameter to the command as well, to provide the command -with the ubuntu release the manifest was generated on, for example: +When providing a manifest file to either of the commands, it is assumed +that the manifest file was generated for the **same** Ubuntu series the +the machine is running on. For example, if you run the command on a Xenial +machine, and provide a manifest file for the command, the command will assume that the +manifest also represents a Xenial machine. If that is not the case, you must +provide the ``--series`` parameter to the command as well, to provide the Ubuntu series the +manifest was generated on, for example: .. code-block:: bash pro vulnerability list --manifest-file=MANIFEST_FILE_PATH --series=focal -Finally, today we only support the manifest file generated by the Pro client. This +Currently, we only support manifest files generated by the Pro Client. This manifest file can be generated by using the :ref:`package_manifest` API endpoint.