Merge pull request #3856 from uyuni-project/5.0.4-document-configration-for-oval-data-consumption-NEW

5.0 4 - Mark the OVAL data consumption as tech preview

Author: 0rnela

Diff for: CHANGELOG.md

@@ -1,3 +1,4 @@
+- Marked OVAL data consumption as Technology Preview
 - Enhanced CVE auditing feature in Administration Guide
 - Restructured Server and Proxy Installation to better distinguish
   between SUSE Linux Enterprise Micro and SUSE Linux Enterprise

Diff for: modules/administration/pages/auditing.adoc

@@ -8,12 +8,10 @@ In the {productname} {webui}, navigate to [guimenu]``Audit`` to perform auditing
 
 
 
-// This probably needs to be broken into sub-sections. --LKB 20200205
-
 
 == CVE Audits
 
-A CVE (common vulnerabilities and exposures) is a fix for a publicly known security vulnerability.
+A CVE (Common Vulnerabilities and Exposures) is a fix for a publicly known security vulnerability.
 
 [IMPORTANT]
 ====
@@ -32,7 +30,7 @@ We recommend that before you begin a CVE audit you refresh the data to ensure yo
 . 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].
@@ -50,24 +48,83 @@ 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 (Open Vulnerability and Assessment Language).
-These two sources provide us with metadata for conducting CVE audits, each serving a distinct purpose.
+
+[IMPORTANT]
+====
+In addition to retrieving CVE information from channel data, {productname} now includes an experimental feature that fetches CVE details from OVAL files.
+This functionality is currently considered a *Technology Preview*.
+
+Users are encouraged to experiment with this feature and share feedback.
+However, it is not yet recommended for production use without thorough testing in a test environment.
+====
+
+
+The CVE Audit operation relies on two primary data sources: channels and OVAL (Open Vulnerability and Assessment Language).
+These two sources provide the metadata for conducting CVE audits, each serving a distinct purpose.
 
 Channels::
-Channels include the updated software packages, which include patches, and provide insights into the essential patches required to address vulnerabilities.
+Channels include the updated software packages, including the patches, and provide insights into the essential patches required to address vulnerabilities.
 
-OVAL::
-In contrast, OVAL data supplies information about the vulnerabilities themselves and the packages that render a system vulnerable to a CVE.
+OVAL (Technology Preview)::
+In contrast, OVAL data supply the information about vulnerabilities themselves, and 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.
+OVAL data is much more lightweight than channels data.
 For example, OVAL data for {opensuse} Leap 15.4 is around 50{nbsp}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.
+
+[NOTE]
+====
+Key characteristics of the OVAL feature include: 
+
+* *Disabled by default*: The feature is turned off by default and must be explicitly enabled by the user by updating the configuration file [litaral]``rhn.conf`` and restarting relevant services.
+* *Reversible*: If any issues arise, users can revert back to the standard channel-based CVE audit.
+* *Performance considerations*: While initial testing has been conducted, there are still concerns regarding performance, and further optimizations may be needed.
+
+* OVAL data is updated at 23:00 every day by default.
+  We recommend that before you begin a CVE audit you refresh the data to ensure you have the latest vulnerabilities metadata.
+====
+
+
+.Procedure: Enabling OVAL Data Support
+
+. Add or modify the following setting in [literal]``rhn.conf``:  
+
++
+----
+java.cve_audit.enable_oval_metadata=true
+----
++
+. Restart the Tomcat and Taskomatic services:
+
++
+----
+systemctl restart tomcat taskomatic
+----
+
+If you encounter issues and need to revert to the default behavior, disable the feature by setting:
+
+
+.Procedure: Disabling OVAL Data Support
+
+. Add or modify the following setting in [literal]``rhn.conf``:
++
+----
+java.cve_audit.enable_oval_metadata=false
+----
++
+. Restart the Tomcat and Taskomatic services:
+
++
+----
+systemctl restart tomcat taskomatic
+----
+
 
 .Procedure: Updating OVAL Data
 . In the {productname} {webui}, navigate to menu:Admin[Task Schedules] and select the ``oval-data-sync-default`` schedule.
@@ -76,7 +133,8 @@ We recommend that before you begin a CVE audit you refresh the data to ensure yo
 
 Allow the task to complete before continuing with the CVE audit.
 
-=== Collecting CPE
+
+=== Collect 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.
 
@@ -88,6 +146,7 @@ However, for existing clients, it is necessary to execute the ``Update Packages
 . 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.
@@ -113,6 +172,7 @@ To ensure the integrity and currency of the OVAL data, {productname} exclusively
 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
 
 The CVE status of clients is usually either ``affected``, ``not affected``, or ``patched``.
@@ -135,6 +195,7 @@ A patch known by {productname} in a relevant channel.
 Relevant channel::
 A channel managed by {productname}, which is either assigned to the system, the original of a cloned channel which is assigned to the system, a channel linked to a product which is installed on the system or a past or future service pack channel for the system.
 
+
 [NOTE]
 ====
 Because of the definitions used within {productname}, CVE audit results might be incorrect in some circumstances.