Update fix docs

docs/howtoguides.rst

@@ -92,3 +92,11 @@ Create a ``pro`` Golden Image
    :maxdepth: 1
 
    Create a customised Cloud Ubuntu Pro image <howtoguides/create_pro_golden_image.md>
+
+Fixing multiple CVEs
+==================================================
+
+.. toctree::
+   :maxdepth: 1
+
+   Better visualise results when fixing multiple CVEs <howtoguides/how_to_better_visualise_fixing_multiple_cves.rst>

docs/howtoguides/how_to_better_visualise_fixing_multiple_cves.rst

@@ -0,0 +1,59 @@
+.. _how_to_better_visualise_fixing_multiple_cves:
+
+How to better visualise the result when fixing multiple CVEs
+*************************************************************
+
+To fix multiple CVEs, you need to use the `u.pro.security.fix.cve.execute.v1` endpoint,
+as the CLI `pro fix` command doesn't support multiple CVEs. However, as can be seen :ref:`in the endpoint documentation <cve-execute-api-v1>`,
+this command will output a JSON blob containing the results of the fix operation for each CVE.
+
+This doesn't allow for a quick visualisation of the fix status of each requested CVE.
+To address that, we can use a `jq` filter. The `jq` command is mainly used to parse JSON data directly in
+the terminal. To know more about it, please refer to `the jq manpage <https://manpages.ubuntu.com/manpages/xenial/man1/jq.1.html>`_
+
+Before proceeding, we need to guarantee that `jq` is installed in your machine. This can be achieved
+by running the following command:
+
+.. code-block:: bash
+
+    $ apt update & apt install jq -y
+
+Now that `jq` is installed, we can properly parse the JSON data delivered from the execute API.
+As an example, let's assume we want to fix these three CVEs: **CVE-2020-28196, CVE-2020-15180**
+and **CVE-2017-9233**.
+
+We can achieve that by running the following command:
+
+.. code-block:: bash
+
+    pro api u.pro.security.fix.cve.execute.v1 --data '{"cves": ["CVE-2020-28196", "CVE-2020-15180", "CVE-2017-9233"]}' \
+      | jq -r '.data.attributes.cves_data.cves[] | "\(.title) (\(.description)) - \(.status)"'
+
+We can see that the command output will be something that follows this structure here:
+
+.. code-block:: bash
+
+    CVE-2020-28196 (Kerberos vulnerability) - fixed
+    CVE-2020-15180 (MariaDB vulnerabilities) - not-affected
+    CVE-2017-9233 (Coin3D vulnerability) - fixed
+
+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 status of the CVE which can be one of: **fixed, still-affected, not-affected**
+  and **affected-until-reboot**.
+
+If you want to change the output format, you can tweak the `jq` filter. For example, to only show
+the CVE title and status, you can change the `jq` filter to:
+
+.. code-block:: bash
+
+    jq -r '.data.attributes.cves_data.cves[] | "\(.title) - \(.status)"'
+
+Finally, if you want to have the same visualisation when fixing USNs, just change the `jq` filter
+to:
+
+.. code-block:: bash
+
+    jq -r '.data.attributes.usns_data.usns[] | "\(.title) (\(.description)) - \(.status)"'

docs/howtoguides/how_to_run_fix_in_dry_run_mode.md

@@ -10,20 +10,38 @@ WARNING: The option --dry-run is being used.
 No packages will be installed when running this command.
 USN-5079-2: curl vulnerabilities
 Associated CVEs:
-https://ubuntu.com/security/CVE-2021-22946
-https://ubuntu.com/security/CVE-2021-22947
+ - https://ubuntu.com/security/CVE-2021-22946
+ - https://ubuntu.com/security/CVE-2021-22947
+
+Fixing requested USN-5079-2
 1 affected source package is installed: curl
 (1/1) curl:
 A fix is available in Ubuntu Pro: ESM Infra.
+
 The machine is not attached to an Ubuntu Pro subscription.
 To proceed with the fix, a prompt would ask for a valid Ubuntu Pro token.
 { pro attach TOKEN }
+
 Ubuntu Pro service: esm-infra is not enabled.
 To proceed with the fix, a prompt would ask permission to automatically enable
 this service.
 { pro enable esm-infra }
 { apt update && apt install --only-upgrade -y curl libcurl3-gnutls }
+
 ✔ USN-5079-2 is resolved.
+
+Found related USNs:
+- USN-5079-1
+
+Fixing related USNs:
+- USN-5079-1
+No affected source packages are installed.
+
+✔ USN-5079-1 does not affect your system.
+
+Summary:
+✔ USN-5079-2 [requested] is resolved.
+✔ USN-5079-1 [related] does not affect your system.
 ```
 
 You can see that using `--dry-run` will also indicate which actions would need

docs/references/api.rst

@@ -631,6 +631,8 @@ like ``systemctl start ubuntu-advantage.service``.
         - This endpoint currently has no CLI support. Only the Python-based
           version is available.
 
+.. _cve-execute-api-v1:
+
 u.pro.security.fix.cve.execute.v1
 ===================================
 

docs/tutorials/fix_scenarios.md

@@ -80,7 +80,7 @@ You should see an output like this:
 
 ```
 CVE-2020-15180: MariaDB vulnerabilities
-https://ubuntu.com/security/CVE-2020-15180
+ - https://ubuntu.com/security/CVE-2020-15180
 
 No affected source packages are installed.
 
@@ -111,7 +111,7 @@ You will then see the following output:
 
 ```
 CVE-2020-25686: Dnsmasq vulnerabilities
-https://ubuntu.com/security/CVE-2020-25686
+ - https://ubuntu.com/security/CVE-2020-25686
 
 1 affected package is installed: dnsmasq
 (1/1) dnsmasq:
@@ -140,7 +140,7 @@ run the `pro fix` command again, and we should now see the following:
 
 ```
 CVE-2020-25686: Dnsmasq vulnerabilities
-https://ubuntu.com/security/CVE-2020-25686
+ - https://ubuntu.com/security/CVE-2020-25686
 
 1 affected package is installed: dnsmasq
 (1/1) dnsmasq:
@@ -170,7 +170,7 @@ You will see the following output:
 
 ```
 CVE-2017-9233: Coin3D vulnerability
-  - https://ubuntu.com/security/CVE-2017-9233
+ - https://ubuntu.com/security/CVE-2017-9233
 
 3 affected source packages are installed: expat, matanza, swish-e
 (1/3, 2/3) matanza, swish-e:
@@ -201,8 +201,8 @@ The command will prompt you for a response, like this:
 ```
 USN-5079-2: curl vulnerabilities
 Associated CVEs:
-https://ubuntu.com/security/CVE-2021-22946
-https://ubuntu.com/security/CVE-2021-22947
+ - https://ubuntu.com/security/CVE-2021-22946
+ - https://ubuntu.com/security/CVE-2021-22947
 
 Fixing requested USN-5079-2
 1 affected package is installed: curl
@@ -232,8 +232,8 @@ token you should now see the following output:
 ```
 USN-5079-2: curl vulnerabilities
 Associated CVEs:
-https://ubuntu.com/security/CVE-2021-22946
-https://ubuntu.com/security/CVE-2021-22947
+ - https://ubuntu.com/security/CVE-2021-22946
+ - https://ubuntu.com/security/CVE-2021-22947
 
 1 affected package is installed: curl
 (1/1) curl:
@@ -242,34 +242,21 @@ The update is not installed because this system is not attached to a
 subscription.
 
 Choose: [S]ubscribe at ubuntu.com [A]ttach existing token [C]ancel
->S
-Open a browser to: https://ubuntu.com/pro
-Hit [Enter] when subscription is complete.
+>A
 Enter your token (from https://ubuntu.com/pro) to attach this system:
 > TOKEN
 { pro attach TOKEN }
+Updating Ubuntu Pro: ESM Apps package lists
+Ubuntu Pro: ESM Apps enabled
 Enabling default service esm-infra
-Updating package lists
+Updating Ubuntu Pro: ESM Infra package lists
 Ubuntu Pro: ESM Infra enabled
-This machine is now attached to 'SUBSCRIPTION'
-
-SERVICE       ENTITLED  STATUS    DESCRIPTION
-cis           yes       disabled  Center for Internet Security Audit Tools
-esm-infra     yes       enabled   Expanded Security Maintenance for Infrastructure
-fips          yes       n/a       NIST-certified core packages
-fips-updates  yes       n/a       NIST-certified core packages with priority security updates
-livepatch     yes       n/a       Canonical Livepatch service
-
-NOTICES
-Operation in progress: pro attach
-
-Enable services with: pro enable <service>
-
-                Account: Ubuntu Pro Client Test
-           Subscription: SUBSCRIPTION
-            Valid until: 9999-12-31 00:00:00+00:00
-Technical support level: essential
+Enabling default service livepatch
+Installing snapd snap
+Installing canonical-livepatch snap
+Canonical Livepatch enabled
 { apt update && apt install --only-upgrade -y curl libcurl3-gnutls }
+
 ✔ USN-5079-2 is resolved.
 
 Found related USNs:
@@ -283,7 +270,7 @@ No affected source packages are installed.
 
 Summary:
 ✔ USN-5079-2 [requested] is resolved.
-✔ USN-5079-1 [related] does not affect your system.
+✔ USN-5079-1 [related] does not affect your system
 ```
 
 We can see that this command also fixed related USN **USN-5079-1**.
@@ -297,15 +284,29 @@ observe that the USN is indeed fixed, which you can confirm by running the
 ```
 USN-5079-2: curl vulnerabilities
 Associated CVEs:
-https://ubuntu.com/security/CVE-2021-22946
-https://ubuntu.com/security/CVE-2021-22947
+ - https://ubuntu.com/security/CVE-2021-22946
+ - https://ubuntu.com/security/CVE-2021-22947
 
-1 affected package is installed: curl
+Fixing requested USN-5079-2
+1 affected source package is installed: curl
 (1/1) curl:
 A fix is available in Ubuntu Pro: ESM Infra.
 The update is already installed.
 
 ✔ USN-5079-2 is resolved.
+
+Found related USNs:
+- USN-5079-1
+
+Fixing related USNs:
+- USN-5079-1
+No affected source packages are installed.
+
+✔ USN-5079-1 does not affect your system.
+
+Summary:
+✔ USN-5079-2 [requested] is resolved.
+✔ USN-5079-1 [related] does not affect your system.
 ```
 
 ```{note}
@@ -330,17 +331,17 @@ $ sudo pro disable esm-infra
 Now, you can run the following command:
 
 ```console
-$ sudo pro fix CVE-2021-44731
+$ sudo pro fix CVE-2023-1523
 ```
 
 And you should see the following output (if you type `E` when
 prompted):
 
 ```
-CVE-2021-44731: snapd vulnerabilities
-https://ubuntu.com/security/CVE-2021-44731
+CVE-2023-1523: snapd vulnerability
+ - https://ubuntu.com/security/CVE-2023-1523
 
-1 affected package is installed: snapd
+1 affected source package is installed: snapd
 (1/1) snapd:
 A fix is available in Ubuntu Pro: ESM Infra.
 The update is not installed because this system does not have
@@ -349,12 +350,11 @@ esm-infra enabled.
 Choose: [E]nable esm-infra [C]ancel
 > E
 { pro enable esm-infra }
-One moment, checking your subscription first
-Updating package lists
+Updating Ubuntu Pro: ESM Infra package lists
 Ubuntu Pro: ESM Infra enabled
-{ apt update && apt install --only-upgrade -y ubuntu-core-launcher snapd }
+{ apt update && apt install --only-upgrade -y snapd ubuntu-core-launcher }
 
-✔ CVE-2021-44731 is resolved.
+✔ CVE-2023-1523 is resolved.
 ```
 
 You can observe that the required service was enabled and `pro fix` was able to
@@ -369,37 +369,37 @@ will inform you about it.
 You can confirm this by running the following fix command:
 
 ```console
-$ sudo pro fix CVE-2022-0778
+$ sudo pro fix CVE-2023-3817
 ```
 
 Then you will see the following output:
 
 ```
-CVE-2022-0778: OpenSSL vulnerability
-https://ubuntu.com/security/CVE-2022-0778
+CVE-2023-3817: OpenSSL vulnerabilities
+ - https://ubuntu.com/security/CVE-2023-3817
 
-1 affected package is installed: openssl
+1 affected source package is installed: openssl
 (1/1) openssl:
 A fix is available in Ubuntu Pro: ESM Infra.
 { apt update && apt install --only-upgrade -y libssl1.0.0 openssl }
-A reboot is required to complete fix operation.
 
-✘ CVE-2022-0778 is not resolved.
+A reboot is required to complete fix operation.
+✘ CVE-2023-3817 is not resolved
 ```
 
 If we reboot the machine and run the command again, you will see that it is
 indeed fixed:
 
 ```
-CVE-2022-0778: OpenSSL vulnerability
-https://ubuntu.com/security/CVE-2022-0778
+CVE-2023-3817: OpenSSL vulnerabilities
+ - https://ubuntu.com/security/CVE-2023-3817
 
-1 affected package is installed: openssl
+1 affected source package is installed: openssl
 (1/1) openssl:
 A fix is available in Ubuntu Pro: ESM Infra.
 The update is already installed.
 
-✔ CVE-2022-0778 is resolved.
+✔ CVE-2023-3817 is resolved.
 ```
 
 ## Partially resolved CVE/USN
@@ -426,16 +426,16 @@ And you will see the following output:
 
 ```
 CVE-2017-9233: Expat vulnerability
-https://ubuntu.com/security/CVE-2017-9233
+ - https://ubuntu.com/security/CVE-2017-9233
 
-3 affected packages are installed: expat, matanza, swish-e
+3 affected source packages are installed: expat, matanza, swish-e
 (1/3, 2/3) matanza, swish-e:
-Sorry, no fix is available.
+Ubuntu security engineers are investigating this issue.
 (3/3) expat:
 A fix is available in Ubuntu standard updates.
 { apt update && apt install --only-upgrade -y expat }
-2 packages are still affected: matanza, swish-e
 
+2 packages are still affected: matanza, swish-e
 ✘ CVE-2017-9233 is not resolved.
 ```
 

wordlist.txt

@@ -13,11 +13,13 @@ Furo
 Grafana
 IAM
 installable
+jq
 JSON
 Juju
 Kubernetes
 Kubeflow
 Makefile
+manpage
 MyST
 namespace
 namespaces