Fix issues reported by asciidoctor-dita-vale (Managing Security Compliance) (#4201)

aneta-petrova · maximiliankolb · web-flow · commit 635956c2ad04 · 2025-09-09T08:28:54.000+02:00
* Convert xrefs
* Fix additional resources
* Turn compliance deployment into an assembly
* Turn listing scap contents into separate modules
* Turn reference to a job template into a note
* Address more complex block titles
* Turn uploading additional scap content into separate modules
* Turn manual compliance policy section into concept

---------

Co-authored-by: Maximilian Kolb &lt;mail@maximilian-kolb.de&gt;
diff --git a/guides/common/assembly_configuring-compliance-policy-deployment-methods.adoc b/guides/common/assembly_configuring-compliance-policy-deployment-methods.adoc
@@ -0,0 +1,9 @@
+:_mod-docs-content-type: ASSEMBLY
+
+include::modules/con_configuring-compliance-policy-deployment-methods.adoc[]
+
+include::modules/proc_configuring-project-for-ansible-compliance-policy-deployment.adoc[leveloffset=+1]
+
+include::modules/proc_configuring-project-for-puppet-compliance-policy-deployment.adoc[leveloffset=+1]
+
+include::modules/con_configuring-project-for-manual-compliance-policy-deployment.adoc[leveloffset=+1]
diff --git a/guides/common/assembly_configuring-scap-contents.adoc b/guides/common/assembly_configuring-scap-contents.adoc
@@ -8,7 +8,9 @@ ifndef::satellite[]
 include::modules/proc_getting-scap-contents-from-upstream.adoc[leveloffset=+1]
 endif::[]
 
-include::modules/proc_uploading-additional-scap-content.adoc[leveloffset=+1]
+include::modules/proc_uploading-additional-scap-content-using-web-ui.adoc[leveloffset=+1]
+
+include::modules/proc_uploading-additional-scap-content-using-cli.adoc[leveloffset=+1]
 
 include::modules/con_tailoring-xccdf-profiles.adoc[leveloffset=+1]
 
diff --git a/guides/common/modules/con_configuring-compliance-policy-deployment-methods.adoc b/guides/common/modules/con_configuring-compliance-policy-deployment-methods.adoc
@@ -0,0 +1,7 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="configuring-compliance-policy-deployment-methods_{context}"]
+= Configuring compliance policy deployment methods
+
+Use one the following procedures to configure {Project} for the method that you have selected to deploy compliance policies.
+You will select one of these methods when you later xref:common/modules/proc_creating-a-compliance-policy.adoc#Creating_a_Compliance_Policy_{context}[create a compliance policy].
diff --git a/guides/common/modules/con_configuring-project-for-manual-compliance-policy-deployment.adoc b/guides/common/modules/con_configuring-project-for-manual-compliance-policy-deployment.adoc
@@ -0,0 +1,11 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="configuring-{project-context}-for-manual-compliance-policy-deployment"]
+= Configuring {Project} for manual compliance policy deployment
+
+For the manual deployment method, no additional {Project} configuration is required.
+
+ifdef::satellite[]
+.Additional resources
+* https://access.redhat.com/solutions/6389101[How to set up OpenSCAP Policies using Manual Deployment option in the _Red{nbsp}Hat Knowledgebase_]
+endif::[]
diff --git a/guides/common/modules/con_scap-content-in-project.adoc b/guides/common/modules/con_scap-content-in-project.adoc
@@ -10,11 +10,3 @@ You can adapt existing XCCDF profiles according to your requirements by using _t
 
 In {Project}, you use an XCCDF profile from SCAP content and, eventually, a tailoring file, to define a _compliance policy_.
 {Project} includes default SCAP contents from SCAP Security Guide provided by the https://www.open-scap.org/[OpenSCAP project].
-
-ifndef::orcharhino[]
-.Additional resources
-* {RHELDocsBaseURL}10/html/security_hardening/[_{RHEL}{nbsp}10 Security hardening_]
-* {RHELDocsBaseURL}9/html/security_hardening/[_{RHEL}{nbsp}9 Security hardening_]
-* {RHELDocsBaseURL}8/html/security_hardening/[_{RHEL}{nbsp}8 Security hardening_]
-* {RHELDocsBaseURL}7/html/security_guide/[_{RHEL}{nbsp}7 Security Guide_]
-endif::[]
diff --git a/guides/common/modules/con_security-content-automation-protocol.adoc b/guides/common/modules/con_security-content-automation-protocol.adoc
@@ -30,4 +30,4 @@ The OpenSCAP scanner tool evaluates system items on a host against the rules and
 |===
 
 .Additional resources
-* For more information about SCAP, see the https://www.open-scap.org/[OpenSCAP project].
+* https://www.open-scap.org/[OpenSCAP project]
diff --git a/guides/common/modules/proc_applying-remote-scap-resources-in-a-disconnected-environment.adoc b/guides/common/modules/proc_applying-remote-scap-resources-in-a-disconnected-environment.adoc
@@ -9,7 +9,7 @@ If your hosts do not have internet access, you must download remote SCAP resourc
 .Prerequisites
 * You have registered your host to {Project} with remote execution enabled.
 * Fetching remote resources must be disabled, which is the default.
-For more information, see xref:inclusion-of-remote-scap-resources_{context}[].
+For more information, see xref:common/modules/ref_inclusion-of-remote-scap-resources.adoc#inclusion-of-remote-scap-resources_{context}[].
 
 .Procedure
 . On your {ProjectServer}, examine the data stream you use in your compliance policy to find out which missing resource you must download:
diff --git a/guides/common/modules/proc_configuring-compliance-policy-deployment-methods.adoc b/guides/common/modules/proc_configuring-compliance-policy-deployment-methods.adoc
diff --git a/guides/common/modules/proc_configuring-project-for-ansible-compliance-policy-deployment.adoc b/guides/common/modules/proc_configuring-project-for-ansible-compliance-policy-deployment.adoc
@@ -0,0 +1,15 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="configuring-{project-context}-for-ansible-compliance-policy-deployment"]
+= Configuring {Project} for Ansible compliance policy deployment
+
+If you want to use Ansible to deploy compliance policies, configure {Project} for Ansible compliance policy deployment.
+
+.Procedure
+. Import the `theforeman.foreman_scap_client` Ansible role.
++
+For more information, see {ManagingConfigurationsAnsibleDocURL}[_{ManagingConfigurationsAnsibleDocTitle}_].
+. Assign the created policy and the `theforeman.foreman_scap_client` Ansible role to a host or host group.
+. To trigger the deployment, run the Ansible role on the host or host group either manually, or set up a recurring job by using remote execution for regular policy updates.
++
+For more information, see {ManagingHostsDocURL}Configuring_and_Setting_Up_Remote_Jobs_managing-hosts[Configuring and Setting Up Remote Jobs] in _{ManagingHostsDocTitle}_.
diff --git a/guides/common/modules/proc_configuring-project-for-puppet-compliance-policy-deployment.adoc b/guides/common/modules/proc_configuring-project-for-puppet-compliance-policy-deployment.adoc
@@ -0,0 +1,17 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="configuring-{project-context}-for-puppet-compliance-policy-deployment"]
+= Configuring {Project} for Puppet compliance policy deployment
+
+If you want to use Puppet to deploy compliance policies, configure {Project} for Puppet compliance policy deployment.
+
+.Procedure
+. Ensure Puppet is enabled.
+. Ensure the Puppet agent is installed on hosts.
+. Import the Puppet environment that contains the `foreman_scap_client` Puppet module.
++
+For more information, see {ManagingConfigurationsPuppetDocURL}[_{ManagingConfigurationsPuppetDocTitle}_].
+. Assign the created policy and the `foreman_scap_client` Puppet class to a host or host group.
++
+Puppet triggers the deployment on the next regular run or you can run Puppet manually.
+Puppet runs every 30 minutes by default.
diff --git a/guides/common/modules/proc_creating-a-compliance-policy.adoc b/guides/common/modules/proc_creating-a-compliance-policy.adoc
@@ -6,10 +6,11 @@
 By creating a compliance policy, you can define and plan your security compliance requirements, and ensure that your hosts remain compliant to your security policies.
 
 .Prerequisites
-* You have configured {Project} for your selected xref:compliance-policy-deployment-options_{context}[compliance policy deployment method].
+* You have configured {Project} for your selected xref:common/modules/ref_compliance-policy-deployment-options.adoc#compliance-policy-deployment-options_{context}[compliance policy deployment method].
 * You have available SCAP contents, and eventually tailoring files, in {Project}.
-** To verify what SCAP contents are available, see xref:listing-available-scap-contents_{context}[].
-** To upload SCAP contents and tailoring files, see xref:Configuring_SCAP_Contents_{context}[].
+** To verify what SCAP contents are available by using {ProjectWebUI}, see xref:common/modules/proc_listing-available-scap-contents-using-web-ui.adoc#listing-available-scap-contents-using-web-ui[].
+** To verify what SCAP contents are available by using CLI, see xref:common/modules/proc_listing-available-scap-contents-using-cli.adoc#listing-available-scap-contents-using-cli[].
+** To upload SCAP contents and tailoring files, see xref:common/modules/con_configuring-scap-contents.adoc#Configuring_SCAP_Contents_{context}[].
 * Your user account has a role assigned that has the `view_policies` and `create_policies` permissions.
 
 .Procedure
diff --git a/guides/common/modules/proc_deploying-a-policy-in-a-host-group-using-ansible.adoc b/guides/common/modules/proc_deploying-a-policy-in-a-host-group-using-ansible.adoc
@@ -6,15 +6,15 @@
 After you deploy a compliance policy in a host group using Ansible, the Ansible role installs the SCAP client and configures OpenSCAP scans on the hosts according to the selected compliance policy.
 
 The SCAP content in the compliance policy might require remote resources.
-For more information, see xref:inclusion-of-remote-scap-resources_{context}[].
+For more information, see xref:common/modules/ref_inclusion-of-remote-scap-resources.adoc#inclusion-of-remote-scap-resources_{context}[].
 
 .Prerequisites
 * You have enabled OpenSCAP on your {SmartProxy}.
-For more information, see xref:enabling-openscap[].
+For more information, see xref:common/modules/proc_enabling-openscap.adoc#enabling-openscap[].
 include::snip_prerequisite-repositories-with-oscap.adoc[]
 include::snip_prerequisite-project-client-repository-enabled.adoc[]
 This repository is required for installing the SCAP client.
-* You have xref:Creating_a_Compliance_Policy_{context}[created a compliance policy] with the Ansible deployment option and assigned the host group.
+* You have xref:common/modules/proc_creating-a-compliance-policy.adoc#Creating_a_Compliance_Policy_{context}[created a compliance policy] with the Ansible deployment option and assigned the host group.
 
 .Procedure
 . In the {ProjectWebUI}, navigate to *Configure* > *Host Groups*.
diff --git a/guides/common/modules/proc_deploying-a-policy-in-a-host-group-using-puppet.adoc b/guides/common/modules/proc_deploying-a-policy-in-a-host-group-using-puppet.adoc
@@ -6,15 +6,15 @@
 After you deploy a compliance policy in a host group using Puppet, the Puppet agent installs the SCAP client and configures OpenSCAP scans on the hosts on the next Puppet run according to the selected compliance policy.
 
 The SCAP content in your compliance policy might require remote resources.
-For more information, see xref:inclusion-of-remote-scap-resources_{context}[].
+For more information, see xref:common/modules/ref_inclusion-of-remote-scap-resources.adoc#inclusion-of-remote-scap-resources_{context}[].
 
 .Prerequisites
 * You have enabled OpenSCAP on your {SmartProxy}.
-For more information, see xref:enabling-openscap[].
+For more information, see xref:common/modules/proc_enabling-openscap.adoc#enabling-openscap[].
 include::snip_prerequisite-repositories-with-oscap.adoc[]
 include::snip_prerequisite-project-client-repository-enabled.adoc[]
 This repository is required for installing the SCAP client.
-* You have xref:Creating_a_Compliance_Policy_{context}[created a compliance policy] with the Puppet deployment option and assigned the host group.
+* You have xref:common/modules/proc_creating-a-compliance-policy.adoc#Creating_a_Compliance_Policy_{context}[created a compliance policy] with the Puppet deployment option and assigned the host group.
 
 .Procedure
 . In the {ProjectWebUI}, navigate to *Configure* > *Host Groups*.
diff --git a/guides/common/modules/proc_deploying-a-policy-on-a-host-using-ansible.adoc b/guides/common/modules/proc_deploying-a-policy-on-a-host-using-ansible.adoc
@@ -6,15 +6,15 @@
 After you deploy a compliance policy on a host using Ansible, the Ansible role installs the SCAP client and configures OpenSCAP scans on the host according to the selected compliance policy.
 
 The SCAP content in the compliance policy might require remote resources.
-For more information, see xref:inclusion-of-remote-scap-resources_{context}[].
+For more information, see xref:common/modules/ref_inclusion-of-remote-scap-resources.adoc#inclusion-of-remote-scap-resources_{context}[].
 
 .Prerequisites
 * You have enabled OpenSCAP on your {SmartProxy}.
-For more information, see xref:enabling-openscap[].
+For more information, see xref:common/modules/proc_enabling-openscap.adoc#enabling-openscap[].
 include::snip_prerequisite-repositories-with-oscap.adoc[]
 include::snip_prerequisite-project-client-repository-enabled.adoc[]
 This repository is required for installing the SCAP client.
-* You have xref:Creating_a_Compliance_Policy_{context}[created a compliance policy] with the Ansible deployment option.
+* You have xref:common/modules/proc_creating-a-compliance-policy.adoc#Creating_a_Compliance_Policy_{context}[created a compliance policy] with the Ansible deployment option.
 
 .Procedure
 . In the {ProjectWebUI}, navigate to *Hosts* > *All Hosts*.
diff --git a/guides/common/modules/proc_deploying-a-policy-on-a-host-using-puppet.adoc b/guides/common/modules/proc_deploying-a-policy-on-a-host-using-puppet.adoc
@@ -6,15 +6,15 @@
 After you deploy a compliance policy on a host using Puppet, the Puppet agent installs the SCAP client and configures OpenSCAP scans on the host on the next Puppet run according to the selected compliance policy.
 
 The SCAP content in your compliance policy might require remote resources.
-For more information, see xref:inclusion-of-remote-scap-resources_{context}[].
+For more information, see xref:common/modules/ref_inclusion-of-remote-scap-resources.adoc#inclusion-of-remote-scap-resources_{context}[].
 
 .Prerequisites
 * You have enabled OpenSCAP on your {SmartProxy}.
-For more information, see xref:enabling-openscap[].
+For more information, see xref:common/modules/proc_enabling-openscap.adoc#enabling-openscap[].
 include::snip_prerequisite-repositories-with-oscap.adoc[]
 include::snip_prerequisite-project-client-repository-enabled.adoc[]
 This repository is required for installing the SCAP client.
-* You have xref:Creating_a_Compliance_Policy_{context}[created a compliance policy] with the Puppet deployment option.
+* You have xref:common/modules/proc_creating-a-compliance-policy.adoc#Creating_a_Compliance_Policy_{context}[created a compliance policy] with the Puppet deployment option.
 
 .Procedure
 . In the {ProjectWebUI}, navigate to *Hosts* > *All Hosts*.
diff --git a/guides/common/modules/proc_getting-supported-scap-contents-for-rhel.adoc b/guides/common/modules/proc_getting-supported-scap-contents-for-rhel.adoc
@@ -21,12 +21,13 @@ $ rpm2cpio scap-security-guide-0.1.69-3.el8_6.noarch.rpm \
 > ssg-rhel-8.6-ds.xml
 ----
 . Upload the data stream to {Project}.
-For more information, see xref:Uploading_Additional_SCAP_Content_{context}[].
+For more information, see the following sections:
 
-[role="_additional-resources"]
-.Additional resources
+* xref:common/modules/proc_uploading-additional-scap-content-using-web-ui.adoc#uploading-additional-scap-content-using-web-ui[]
+* xref:common/modules/proc_uploading-additional-scap-content-using-cli.adoc#uploading-additional-scap-content-using-cli[]
 
-* https://access.redhat.com/articles/6337261[Supported versions of the SCAP Security Guide in RHEL] in the _Red Hat Knowledgebase_
-* {RHELDocsBaseURL}9/html/security_hardening/scanning-the-system-for-configuration-compliance-and-vulnerabilities_security-hardening#scap-security-guide-profiles-supported-in-rhel-9_scanning-the-system-for-configuration-compliance-and-vulnerabilities[SCAP Security Guide profiles supported in RHEL{nbsp}9] in _{RHEL}{nbsp}9 Security hardening_
-* {RHELDocsBaseURL}8/html/security_hardening/scanning-the-system-for-configuration-compliance-and-vulnerabilities_security-hardening#scap-security-guide-profiles-supported-in-rhel_scanning-the-system-for-configuration-compliance-and-vulnerabilities[SCAP Security Guide profiles supported in RHEL{nbsp}8] in _{RHEL}{nbsp}8 Security hardening_
-* {RHELDocsBaseURL}7/html/security_guide/scap-security-guide-profiles-supported-in-rhel-7_scanning-the-system-for-configuration-compliance-and-vulnerabilities[SCAP Security Guide profiles supported in RHEL{nbsp}7] in the _{RHEL}{nbsp}7 Security Guide_
+.Additional resources
+* https://access.redhat.com/articles/6337261[Supported versions of the SCAP Security Guide in RHEL in the _Red Hat Knowledgebase_]
+* https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/security_hardening/scanning-the-system-for-configuration-compliance-and-vulnerabilities_security-hardening#scap-security-guide-profiles-supported-in-rhel-9_scanning-the-system-for-configuration-compliance-and-vulnerabilities[SCAP Security Guide profiles supported in RHEL{nbsp}9 in _{RHEL}{nbsp}9 Security hardening_]
+* https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html/security_hardening/scanning-the-system-for-configuration-compliance-and-vulnerabilities_security-hardening#scap-security-guide-profiles-supported-in-rhel_scanning-the-system-for-configuration-compliance-and-vulnerabilities[SCAP Security Guide profiles supported in RHEL{nbsp}8 in _{RHEL}{nbsp}8 Security hardening_]
+* https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/7/html/security_guide/scap-security-guide-profiles-supported-in-rhel-7_scanning-the-system-for-configuration-compliance-and-vulnerabilities[SCAP Security Guide profiles supported in RHEL{nbsp}7 in the _{RHEL}{nbsp}7 Security Guide_]
diff --git a/guides/common/modules/proc_listing-available-scap-contents-using-cli.adoc b/guides/common/modules/proc_listing-available-scap-contents-using-cli.adoc
@@ -1,19 +1,14 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="listing-available-scap-contents_{context}"]
-= Listing available SCAP contents
+[id="listing-available-scap-contents-using-cli"]
+= Listing available SCAP contents using CLI
 
 Use this procedure to view what SCAP contents are already loaded in {Project}.
-To use the CLI instead of the {ProjectWebUI}, see the xref:cli-listing-available-scap-contents_{context}[CLI procedure].
 
 .Prerequisites
 * Your user account has a role assigned that has the `view_scap_contents` permission.
 
 .Procedure
-* In the {ProjectWebUI}, navigate to *Hosts* > *Compliance* > *SCAP contents*.
-
-[id="cli-listing-available-scap-contents_{context}"]
-.CLI procedure
 * Run the following Hammer command on {ProjectServer}:
 +
 [options="nowrap", subs="+quotes,attributes,verbatim"]
diff --git a/guides/common/modules/proc_listing-available-scap-contents-using-web-ui.adoc b/guides/common/modules/proc_listing-available-scap-contents-using-web-ui.adoc
@@ -0,0 +1,12 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="listing-available-scap-contents-using-web-ui"]
+= Listing available SCAP contents using {ProjectWebUI}
+
+Use this procedure to view what SCAP contents are already loaded in {Project}.
+
+.Prerequisites
+* Your user account has a role assigned that has the `view_scap_contents` permission.
+
+.Procedure
+* In the {ProjectWebUI}, navigate to *Hosts* > *Compliance* > *SCAP contents*.
diff --git a/guides/common/modules/proc_loading-the-default-scap-contents.adoc b/guides/common/modules/proc_loading-the-default-scap-contents.adoc
@@ -9,7 +9,7 @@ SSG is provided by the operating system of {ProjectServer} and installed in `/us
 Note that the available data streams depend on the operating system version on which {Project} runs.
 ifdef::satellite[]
 You can only use this SCAP content to scan hosts that have the same minor RHEL version as your {ProjectServer}.
-For more information, see xref:getting-supported-scap-contents-for-rhel_{context}[].
+For more information, see xref:common/modules/proc_getting-supported-scap-contents-for-rhel.adoc#getting-supported-scap-contents-for-rhel_{context}[].
 endif::[]
 
 ifdef::satellite[]
diff --git a/guides/common/modules/proc_remediating-compliance-failures.adoc b/guides/common/modules/proc_remediating-compliance-failures.adoc
@@ -12,6 +12,12 @@ Always test the recommended remedial actions or scripts in a non-production envi
 Remediation might render the system non-functional.
 ====
 
+[NOTE]
+====
+You can use the *Run OpenSCAP remediation - Ansible Default* and *Run OpenSCAP remediation - Script Default* job templates to apply the remediation snippet.
+For more information about running remote jobs based on templates, see {ManagingHostsDocURL}Configuring_and_Setting_Up_Remote_Jobs_managing-hosts[Configuring and setting up remote jobs] in _{ManagingHostsDocTitle}_.
+====
+
 .Prerequisites
 * Your user account has a role assigned that has the following permissions: `view_arf_reports`, `view_hosts`, `create_job_invocations`
 
@@ -27,7 +33,3 @@ Follow the wizard to remediate the compliance failure.
 ====
 The remediation wizard might not be available for all compliance failures.
 ====
-
-.Additional resources
-* You can apply the remediation snippet by manually configuring a remote job.
-For more information, see {ManagingHostsDocURL}Configuring_and_Setting_Up_Remote_Jobs_managing-hosts[Configuring and setting up remote jobs] in _{ManagingHostsDocTitle}_.
diff --git a/guides/common/modules/proc_running-a-security-compliance-scan-on-demand.adoc b/guides/common/modules/proc_running-a-security-compliance-scan-on-demand.adoc
diff --git a/guides/common/modules/proc_searching-compliance-reports.adoc b/guides/common/modules/proc_searching-compliance-reports.adoc
diff --git a/guides/common/modules/proc_uploading-additional-scap-content-using-cli.adoc b/guides/common/modules/proc_uploading-additional-scap-content-using-cli.adoc
diff --git a/guides/common/modules/proc_uploading-additional-scap-content-using-web-ui.adoc b/guides/common/modules/proc_uploading-additional-scap-content-using-web-ui.adoc
diff --git a/guides/common/modules/ref_inclusion-of-remote-scap-resources.adoc b/guides/common/modules/ref_inclusion-of-remote-scap-resources.adoc
diff --git a/guides/doc-Managing_Security_Compliance/master.adoc b/guides/doc-Managing_Security_Compliance/master.adoc
