[WIP][GSOC23] - E - Update CVE Audit documentation

modules/administration/pages/auditing.adoc

@@ -25,18 +25,14 @@ CVE identification numbers use the form ``CVE-YEAR-XXXX``.
 
 In the {productname} {webui}, navigate to menu:Audit[CVE Audit] to see a list of all clients and their current patch status.
 
-By default, the CVE data is updated at 2300 every day.
+By default, the patch data is updated at 23:00 every day.
 We recommend that before you begin a CVE audit you refresh the data to ensure you have the latest patches.
 
-
-
-.Procedure: Updating CVE Data
+.Procedure: Updating Patch Data
 . In the {productname} {webui}, navigate to menu:Admin[Task Schedules] and select the ``cve-server-channels-default`` schedule.
 . Click btn:[cve-server-channels-bunch].
 . Click btn:[Single Run Schedule] to schedule the task.
-    Allow the task to complete before continuing with the CVE audit.
-
-
+Allow the task to complete before continuing with the CVE audit.
 
 .Procedure: Verifying Patch Status
 . In the {productname} {webui}, navigate to menu:Audit[CVE Audit].
@@ -46,17 +42,74 @@ We recommend that before you begin a CVE audit you refresh the data to ensure yo
 
 For more information about the patch status icons used on this page, see xref:reference:audit/audit-cve-audit.adoc[].
 
-
-For each system, the [guimenu]``Next Action`` column provides information about what you need to do to address vulnerabilities.
+For each system, the [guimenu]``Actions`` column provides information about what you need to do to address vulnerabilities.
 If applicable, a list of candidate channels or patches is also given.
 You can also assign systems to a [guimenu]``System Set`` for further batch processing.
 
-
 You can use the {productname} API to verify the patch status of your clients.
 Use the ``audit.listSystemsByPatchStatus`` API method.
 For more information about this method, see the {productname} API Guide.
 
+== OVAL
+The CVE Audit operation relies on two primary data sources: Channels and OVAL.
+These two sources provide us with metadata for conducting CVE audits, each serving a distinct purpose.
+
+1. **Channels:** Channels include the updated software packages, which include patches, and provide insights into the essential patches required to address vulnerabilities.
+
+2. **OVAL:** In contrast, OVAL data supplies information about the vulnerabilities themselves and the packages that render
+a system vulnerable to a CVE.
+
+While it is possible to conduct CVE audits using
+only channels data, synchronizing OVAL data enhances
+the accuracy of the results, particularly in cases involving zero-day vulnerabilities or partially patched
+vulnerabilities.
+
+OVAL data is also much more lightweight than channels data .e.g. OVAL data for openSUSE Leap 15.4 is around ~50 MB.
+Having synced OVAL data only, you can already perform CVE audits and check if your systems are vulnerable or not to a CVE, but you can't apply patches since they come from channels.
+
+By default, OVAL data, is updated at 23:00 every day. We recommend that before you begin a CVE audit you refresh the data to ensure you have the latest vulnerabilities metadata.
+
+.Procedure: Updating OVAL Data
+. In the {productname} {webui}, navigate to menu:Admin[Task Schedules] and select the ``oval-data-sync-default`` schedule.
+. Click btn:[oval-data-sync-bunch].
+. Click btn:[Single Run Schedule] to schedule the task.
+Allow the task to complete before continuing with the CVE audit.
+
+=== Collecting CPE
+
+To be able to accurately identify what vulnerabilities apply to a certain client, we need to identify the operating system product that client uses. To do that, we collect the CPE (Common Platform Enumeration) of the client as a salt grain, then we save it to the database.
+
+The cpe of newly registered clients will be automatically collected and saved to the database. However, for existing clients, it is necessary to execute the ``Update Packages List`` action at least once to
+
+.Procedure: Update Packages List
+. In the {productname} {webui}, navigate to menu:Systems[System List > All] and select a client.
+. Then go to the [guimenu]``Software`` tab and select the [guimenu]``Packages`` sub-tab.
+. Click btn:[Update Packages List] to update packages and collect the CPE of client.
+
+=== OVAL Sources
 
+To ensure the integrity and currency of the OVAL data, {productname} exclusively consumes OVAL data from the official maintainers of every product. Below, you can find the list of OVAL data sources.
+
+[[oval-sources]]
+[cols="1,1", options="header"]
+.OVAL Sources
+|===
+| Product | Source URL
+| openSUSE Leap .5+.^| https://ftp.suse.com/pub/projects/security/oval
+| openSUSE Leap Micro
+| SUSE Linux Enterprise Server
+| SUSE Linux Enterprise Desktop
+| SUSE Linux Enterprise Micro
+| RedHat Enterprise Linux | https://www.redhat.com/security/data/oval/v2
+| Debian | https://www.debian.org/security/oval
+| Ubuntu | https://security-metadata.canonical.com/oval
+|===
+
+
+[NOTE]
+====
+OVAL metadata is used in CVE auditing for only a subset of clients, namely, clients that use openSUSE Leap, SUSE enterprise products, RHEL, Debian or Ubuntu. This is due to the absence of OVAL vulnerability definitions metadata for the other products.
+====
 
 == CVE Status
 

modules/reference/pages/audit/audit-cve-audit.adoc

@@ -15,9 +15,14 @@ Clients are listed with a patch status icon.
 .Patch Status Icons
 |===
 | Icon | Description | Action Required
-| icon:exclamation-circle[role="red"] | Affected, patches are available in channels that are not assigned | The client is affected by a vulnerability and {productname} has patches for it, but the channels offering the patches are not assigned to the client.
-| icon:exclamation-triangle[role="orange"] | Affected, at least one patch is available in an assigned channel | The client is affected by the vulnerability and {productname} has patches available in a channel that is directly assigned to the client.
-| icon:circle[role="green"]| Not affected | There are no available CVE patches for this client.
+| icon:exclamation-circle[role="red"] | Affected, patches are not released for the CVE. | The client is affected by a vulnerability for which a patch has not yet been released.
+| icon:exclamation-circle[role="red"] | Affected, patches were released for the CVE but {productname} can't find them in any of the relevant channels. | The client is affected by a vulnerability that received a patch, but {productname} is unable to locate any of the patches in relevant channels.
+| icon:shield[role="red"] | Affected, only partial patches are available for the CVE. | The client is affected by a vulnerability and {productname} has patches for it, but applying the patches will only fix some of the vulnerable packages.
+
+| icon:exclamation-triangle[role="orange"] | Affected, patches are available in channels that are not assigned | The client is affected by a vulnerability and {productname} has patches for it, but the channels offering the patches are not assigned to the client.
+| icon:exclamation-triangle[role="orange"] | Affected, patches are available in a product migration target | The client is affected by a vulnerability and {productname} has patches for it, but applying the patch requires migrating the product to a newer version.
+| icon:shield[role="orange"] | Affected, at least one patch is available in an assigned channel | The client is affected by the vulnerability and {productname} has patches available in a channel that is directly assigned to the client.
+| icon:circle[role="green"]| Not affected | The client is not affected because none of the CVE vulnerable packages are installed.
 | icon:check-circle[role="green"] | Patched | A patch has been successfully installed on the client.
 |===