Asciidoc conversion of hardening guide changes (#3782)

ianf77 · web-flow · commit 261a0093784d · 2025-07-23T03:45:59.000-04:00
* Asciidoc conversion of hardening guide changes Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749 * Asciidoc conversion of hardening guide changes New assembly/files Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749 * Asciidoc conversion of hardening guide changes Correction Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749 * Asciidoc conversion of hardening guide changes Corrected three updated modules Asciidoc conversion of new and revised content for hardening guide v4 https://issues.redhat.com/browse/AAP-48749 * Asciidoc conversion of hardening guide changes Corrections Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749 * Asciidoc conversion of hardening guide changes Correction Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749 * Asciidoc conversion of hardening guide changes Corrections Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749 * Asciidoc conversion of hardening guide changes. Corrections Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749 * Asciidoc conversion of hardening guide changes Added one module and made corrections Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749 Please enter the commit message for your changes. Lines starting * Asciidoc conversion of hardening guide changes Corrections Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749 * Asciidoc conversion of hardening guide changes Correction Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749 * Asciidoc conversion of hardening guide changes Edited and renamed modules Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749 * Asciidoc conversion of hardening guide changes Added variables, renamed module Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749 * Asciidoc conversion of hardening guide changes Corrections Asciidoc conversion of new and revised content for hardening guide v4. https://issues.redhat.com/browse/AAP-48749
diff --git a/downstream/assemblies/aap-hardening/assembly-hardening-aap.adoc b/downstream/assemblies/aap-hardening/assembly-hardening-aap.adoc
@@ -57,7 +57,11 @@ include::aap-hardening/ref-security-variables-install-inventory.adoc[leveloffset
 
 include::aap-hardening/proc-install-user-pki.adoc[leveloffset=+2]
 
-include::aap-hardening/ref-sensitive-variables-install-inventory.adoc[leveloffset=+2]
+include::aap-hardening/proc-sensitive-variables-install-inventory.adoc[leveloffset=+2]
+
+include::aap-hardening/proc-install-rpm-deployment.adoc[leveloffset=+3]
+
+include::aap-hardening/proc-install-containerized-deployment.adoc[leveloffset=+3]
 
 //include::aap-hardening/con-controller-stig-considerations.adoc[leveloffset=+2]
 
@@ -104,5 +108,13 @@ include::aap-hardening/ref-updates-upgrades.adoc[leveloffset=+2]
 
 include::aap-hardening/proc-disaster-recovery-operations.adoc[leveloffset=+3]
 
+include::aap-hardening/con-hashicorp-vault-external-secrets.adoc[leveloffset=+2]
+
+include::aap-hardening/proc-configure-hashicorp-vault.adoc[leveloffset=+3]
+
+include::aap-hardening/proc-configure-hashicorp-credentials.adoc[leveloffset=+3]
+
+include::aap-hardening/proc-configure-ssh-private-key.adoc[leveloffset=+3]
+
 
 
diff --git a/downstream/assemblies/aap-hardening/assembly-managed-node-configuration.adoc b/downstream/assemblies/aap-hardening/assembly-managed-node-configuration.adoc
@@ -0,0 +1,29 @@
+[id="assembly-managed-node-configuration"]
+
+= Managed Node Configuration
+
+{PlatformNameShort} is an agentless technology that relies on making a remote connection to the devices it manages, called managed nodes, to run automation tasks. 
+
+This chapter provides recommendations on improving the security posture of the managed nodes automated by {PlatformNameShort}, including the remote connections between {PlatformNameShort} and the managed nodes.  
+
+Note that managed node configuration can vary significantly based on factors such as operating system, compliance profiles, configuration, and organizational policies. 
+
+Any recommendations on managed node configuration presented here must be thoroughly tested and reviewed before implementation to ensure that they meet organizational policies and requirements.
+
+include::aap-hardening/con-rhel-node-configuration.adoc[leveloffset=+1]
+
+include::aap-hardening/con-create-dedicated-service-account.adoc[leveloffset=+2]
+
+include::aap-hardening/proc-configure-sudo-for-service-account.adoc[leveloffset=+3]
+
+include::aap-hardening/proc-ssh-auth-for-service-account.adoc[leveloffset=+3]
+
+include::aap-hardening/proc-pam-access-for-service-accounts.adoc[leveloffset=+3]
+
+include::aap-hardening/con-more_compliance-profile-considerations.adoc[leveloffset=+2]
+
+include::aap-hardening/ref-fapolicyd-on-rhel.adoc[leveloffset=+3]
+
+include::aap-hardening/proc-fapolicyd-permissive-mode.adoc[leveloffset=+3]
+
+include::aap-hardening/proc-create-fapolicyd-rules.adoc[leveloffset=+3]
diff --git a/downstream/images/cont-b-env-a.png b/downstream/images/cont-b-env-a.png
diff --git a/downstream/modules/aap-hardening/con-create-dedicated-service-account.adoc b/downstream/modules/aap-hardening/con-create-dedicated-service-account.adoc
@@ -0,0 +1,30 @@
+[id="con-create-dedicated-service-account"]
+
+= Create a dedicated service account with access limits
+
+{PlatformNameShort} can be configured to use various users or accounts for connecting to managed nodes. 
+
+This guide recommends creating a single, dedicated service account for this purpose. 
+This service account must be a local account on each managed node to ensure automation jobs continue to run, even if an external authentication mechanism experiences an outage. 
+This recommendation applies unless organizational policy mandates centrally managed service accounts. The service account must be clearly named to indicate its purpose, for instance, `ansible` or `aapsvc`. 
+
+The remainder of this section uses "ansible" as the assumed name for a local service account in its examples.
+
+The local service account is configured in the following manner:
+
+* It is granted sufficient privileges to run any automation job required.
+* It is limited to SSH key authentication only. No password authentication is allowed.
+* Access is only granted to connections made from the {PlatformNameShort} {ControllerNames}s and execution nodes.
++
+[NOTE] 
+====
+To execute tasks in an Ansible playbook or job template as a user other than the service account, use the `become` and `become_user` keywords. Connecting to the managed node as a different user is not necessary.
+====
+
+* The `useradd` command can be used to create a local service account. For example:
+
+----
+sudo useradd ansible \
+    --system --create-home \
+    --comment "Ansible Automation Platform service account"
+----
diff --git a/downstream/modules/aap-hardening/con-hashicorp-vault-external-secrets.adoc b/downstream/modules/aap-hardening/con-hashicorp-vault-external-secrets.adoc
@@ -0,0 +1,5 @@
+[id="con-hashicorp-vault-external-secrets"]
+
+= Using HashiCorp vault for external secrets management
+
+You can integrate HashiCorp Vault with {PlatformNameShort} to manage and retrieve sensitive data.
diff --git a/downstream/modules/aap-hardening/con-more_compliance-profile-considerations.adoc b/downstream/modules/aap-hardening/con-more_compliance-profile-considerations.adoc
@@ -0,0 +1,6 @@
+[id="con-more_compliance-profile-considerations"]
+
+= Compliance profile considerations
+
+In many environments, you can use {PlatformNameShort} to manage systems where security controls have been applied to managed RHEL nodes to meet the requirements of a compliance profile such as CIS, PCI/DSS, the DISA STIG, or similar. 
+The following sections detail the specific set of security controls that must be modified for {PlatformNameShort} to manage the RHEL nodes properly in such environments.
diff --git a/downstream/modules/aap-hardening/con-rhel-node-configuration.adoc b/downstream/modules/aap-hardening/con-rhel-node-configuration.adoc
@@ -0,0 +1,8 @@
+[id="con-rhel-node-configuration"]
+
+= {RHEL} managed node configuration
+
+The following section provides guidance for _{RHEL}_ (RHEL) managed nodes, but the concepts may be applicable to other Linux distributions as well.
+
+Examples are provided for manual configuration of RHEL managed nodes. 
+These steps can also be automated with {PlatformNameShort}, or they can be added to a _Standard Operating Environment_ (SOE) or "golden image" created with a tool such as the Red Hat Insights image builder. 
diff --git a/downstream/modules/aap-hardening/proc-configure-hashicorp-credentials.adoc b/downstream/modules/aap-hardening/proc-configure-hashicorp-credentials.adoc
@@ -0,0 +1,15 @@
+[id="proc-configure-hashicorp-credentials"]
+
+= Using HashiCorp Vault credentials within {PlatformNameShort}
+
+To use HashiCorp vault credentials within {PlatformNmaeShort}, create a new credential with the type *Machine Credential*. 
+Enter relevant information such as an identifiable credential name and an organization. 
+
+To configure the use of HashiCorp Vault credentials, use the following procedure: 
+
+.Procedure 
+
+. To configure the *Username*, click the image:leftkey.png[Key,15,15] icon. 
+. Select the HashiCorp Vault credentials that were created in step 1. 
+. Populate *Path to Secret* and the *Key Name*. 
+. Optionally, click btn:[Test]. Otherwise, click btn:[Finish].
diff --git a/downstream/modules/aap-hardening/proc-configure-hashicorp-vault.adoc b/downstream/modules/aap-hardening/proc-configure-hashicorp-vault.adoc
@@ -0,0 +1,27 @@
+[id="proc-configure-hashicorp-vault"]
+
+= Configuring {PlatformNameShort} to communicate with HashiCorp vault
+
+In an enterprise environment, having externally managed secrets is a convenient way to manage sensitive data across multiple services. 
+One of the most common and recommended authentication methods for the HashiCorp vault is to use AppRoles with policies and login requirements that must be satisfied before a token is issued.
+To configure {PlatformNameShort} to use secrets stored in HashiCorp vault, set up a new credential with the type of HashiCorp Vault Secret Lookup. 
+For information on how to do this, see link:{URLControllerAdminGuide}/assembly-controller-secret-management#ref-hashicorp-vault-lookup[Hashicorp vault secret lookup]. 
+
+Enter relevant information such as an identifiable credential name, organization, and the URL of the vault server, for example, https://vault.domain.com:8200.
+
+Populate the necessary fields with your information such as Token, AppRole role_id, and AppRole secret_id, then select v2 for the API version.
+
+To test the credential to test for functionally and operation, use the following procedure: 
+
+.Procedure
+. Before clicking on *Create Credential*, click btn:[Test]. 
+. In the pop-up box, enter the *Path to Secret* and the *Key Name*. 
++
+[NOTE]
+====
+The *Path to Secret* will be prefixed by `kv` if storing a key-value pair, for example, `kv/key_name`.
+==== 
+
+. Click btn:[Run]. 
+. When the test is successful, click btn:[Create Credential]. 
+. When complete, {PlatformNameShort} is properly configured to use HashiCorp Vault as an external secret source.
diff --git a/downstream/modules/aap-hardening/proc-configure-ssh-private-key.adoc b/downstream/modules/aap-hardening/proc-configure-ssh-private-key.adoc
@@ -0,0 +1,12 @@
+[id="proc-configure-ssh-private-key"]
+
+= Configuring the machine credential’s SSH private key
+
+Use the following procedure: 
+
+.Procedure
+. To configure the *Username*, click the image:leftkey.png[Key,15,15] icon.
+. Select the HashiCorp Vault credentials that you created. 
+. Populate the *Path to Secret* and the *Key Name*. 
+. Select the name of the private key as the *Key Name*.
+. Optionally, click btn:[Test]. Otherwise, click btn:[Finish].
diff --git a/downstream/modules/aap-hardening/proc-configure-sudo-for-service-account.adoc b/downstream/modules/aap-hardening/proc-configure-sudo-for-service-account.adoc
@@ -0,0 +1,24 @@
+[id="proc-configure-sudo-for-service-account"]
+
+= Configure sudo privileges for service account 
+
+The service account requires sufficient privileges to run any current or future automation job on the managed node. This section describes the use of `sudo`, though other priviledge escalation methods are available.
+
+Since {PlatformNameShort} defaults to using the `ansible.builtin.sudo` link:https://docs.ansible.com/ansible/latest/plugins/become.html[become plugin] on Linux-based managed nodes, the service account must be permitted to run any command on the RHEL managed node using the sudo command. 
+
+To configure this, use the following procedure:
+
+.Procedure
+. Create the file `/etc/sudoers.d/ansible`, and include the following content:
++
+----
+# Rules for the ansible service account
+ansible ALL=(ALL) NOPASSWD: ALL
+----
+. Set restrictive permissions on the file:
++
+`sudo chmod 600 /etc/sudoers.d/ansible``
+
+. Verify the file uses the proper syntax:
++
+`sudo visudo -cf /etc/sudoers.d/ansible`
diff --git a/downstream/modules/aap-hardening/proc-create-fapolicyd-rules.adoc b/downstream/modules/aap-hardening/proc-create-fapolicyd-rules.adoc
@@ -0,0 +1,17 @@
+[id="proc-create-fapolicyd-rules"]
+
+= Option 2: Create custom fapolicyd rules
+
+Where the `fapolicyd` service must enforce its rules, consider crafting a custom set of rules to permit {PlatformNameShort} to execute its Python code.  
+
+The following example procedure treats the "ansible" service account as a trusted entity and enables it to execute content in the local Ansible temporary directory (by default, `$HOME/.ansible/tmp`).
+
+.Procedure
+. Create the file `/etc/fapolicy/rules.d/50-ansible.rules` with the following content:
++
+`allow perm=any uid=ansible trust=1 : dir=/home/ansible/.ansible/tmp/`
+. Restart the fapolicyd service:
++
+`sudo systemctl restart fapolicyd.service`
+
+This example rule might require modification to work with any other `fapolicyd` rules that exist on the managed RHEL nodes, and must be thoroughly tested and approved by your security auditor before being put into production.
diff --git a/downstream/modules/aap-hardening/proc-fapolicyd-permissive-mode.adoc b/downstream/modules/aap-hardening/proc-fapolicyd-permissive-mode.adoc
@@ -0,0 +1,13 @@
+[id="proc-fapolicyd-permissive-mode"]
+
+= Option 1: Set the fapolicyd service to permissive mode
+
+The fapolicyd service can be set to "permissive" mode, meaning that it only logs fapolicyd rule violations, rather than enforcing them. 
+
+To configure permissive mode for fapolicyd, use the following procedure: 
+
+.Procedure
+. Edit the file `/etc/fapolicyd/fapolicyd.conf`, and set "permissive = 1".  
+. Restart the `fapolicy` service by running `systemctl restart fapolicyd.service`.
+
+In environments where this configuration might not meet a required compliance profile or local policy, discuss waiving the relevant security control with your security auditor.
diff --git a/downstream/modules/aap-hardening/proc-install-containerized-deployment.adoc b/downstream/modules/aap-hardening/proc-install-containerized-deployment.adoc
@@ -0,0 +1,31 @@
+[id="proc-install-containerized-deployment"]
+
+= Using an external vault file with a containerized installation
+
+For containerized installations of {PlatformNameShort}, use the provided automation execution playbook with the external vault file.
+
+Add the following sensitive variables to the vault file:
+----
+postgresql_admin_password:  <secure_password>
+gateway_admin_password:  <secure_password>
+gateway_pg_password:  <secure_password>
+controller_admin_password:  <secure_password>
+controller_pg_password:  <secure_password>
+hub_admin_password:  <secure_password>c
+hub_pg_password:  <secure_password>
+eda_admin_password:  <secure_password>
+eda_pg_password: <secure_password>
+
+*In the case of a connected installation:
+
+registry_password: <secure_cdn_password>
+----
+To use the new Ansible vault with the {Installer}, use the following procedure:
+
+.Procedure
+. Ensure your vault file, for example, `vault.yml`, contains all required sensitive variables.
+. Run the container installer using the following command: 
++
+`ansible-playbook ansible.containerized_installer.install -e @vault.yml –ask-become-pass`.
+
+Ensure that the vault file is located in the working directory, or provide the full path. Do not duplicate the encrypted variables in the `plaintext` inventory file.
diff --git a/downstream/modules/aap-hardening/proc-install-rpm-deployment.adoc b/downstream/modules/aap-hardening/proc-install-rpm-deployment.adoc
@@ -0,0 +1,34 @@
+[id="proc-install-rpm-deployment"]
+
+= Using an external vault file with an RPM-based {PlatformNameShort} deployment
+
+For RPM-based installations, you can provide the Ansible vault at runtime when executing the setup script.
+
+Add the following sensitive variables to the vault file:
+
+----
+admin_password: <secure_password>
+pg_password: <secure_password>
+automationgateway_admin_password: <secure_password>
+automationgateway_pg_password: <secure_password>
+automationhub_admin_password: <secure_password>
+automationhub_pg_password: <secure_password>
+automationedacontroller_admin_password: <secure_password>
+automationedacontroller_pg_password: <secure_password>
+
+*In the case of a connected installation:
+
+registry_password: <secure_cdn_password>
+----
+
+To use the vault during installation, use the following procedure:
+
+.Procedure
+
+. Ensure the vault file, for example, `vault.yml`, contains all required sensitive variables.
+. Run the installation using the following command: 
++
+`./setup.sh -e @vault.yml –ask-vault-pass`
+
+Using this procedure ensures that the installer reads encrypted variables from the vault and prompts for the vault password.
+
diff --git a/downstream/modules/aap-hardening/proc-pam-access-for-service-accounts.adoc b/downstream/modules/aap-hardening/proc-pam-access-for-service-accounts.adoc
@@ -0,0 +1,19 @@
+[id="proc-pam-access-for-service-accounts"]
+
+= Enable and configure pam_access controls for service accounts
+
+To restrict remote login access to connections originating from the {PlatformNameShort} {ControllerName} and execution nodes and ensure the service account is exclusively used by {PlatformNameShort}, use the following procedure: 
+
+.Procedure
+. Use the FQDNs of your {ControllerName} and execution nodes to add the following content to the `/etc/security/access.conf` file, using the FQDNs of your controller nodes and execution nodes:
++
+----
+# allow the ansible service account to log in from local sources and
+# the hybrid controller or execution nodes, and deny all other sources
++:ansible:LOCAL controller1.example.com controller2.example.com en1.example.com
+-:ansible:ALL
+----
+. Enable the `with-pamaccess` feature in the current authselect profile.  
+All authselect profiles included by default with RHEL have this feature.
++
+`sudo authselect enable-feature with-pamaccess`
diff --git a/downstream/modules/aap-hardening/proc-sensitive-variables-install-inventory.adoc b/downstream/modules/aap-hardening/proc-sensitive-variables-install-inventory.adoc
@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+// downstream/assemblies/assembly-hardening-aap.adoc
+
+[id="proc-sensitive-variables-install-inventory_{context}"]
+
+= Securing sensitive variables with ansible vault
+
+The installation inventory file for {PlatformNameShort} contains a number of sensitive variables, such as default administrative and database passwords. 
+By default, these are stored in plain text. 
+By securing sensitive values with Ansible Vault, both RPM-based and containerized {PlatformNameShort} installations benefit from improved security, password hygiene, and maintainability. 
+
+To create an Ansible vault file, use the following procedure: 
+
+.Procedure
+
+. Navigate to the install directory by using the following command:
++
+`cd /path/to/ansible-automation-platform-setup-bundle-2.5-<version>`
+. Create a vault file by using the following command:
++
+`ansible-vault create vault.yml`
+. When prompted, enter a vault password
+This password is required to access or modify the vault and is required for day-two operations such as backups and reconfigurations. 
++
+[IMPORTANT]
+====
+Passwords with special characters must be in double quotes.
+====
+. Store the vault password securely, in accordance with your organizations security policy, for example, using a password manager or vault service.
+. Add your sensitive variables to the vault and ensure they are not also defined in the inventory file.
+
+To edit your vault file use:
+
+`ansible-vault edit <file>`
+
+
diff --git a/downstream/modules/aap-hardening/proc-ssh-auth-for-service-account.adoc b/downstream/modules/aap-hardening/proc-ssh-auth-for-service-account.adoc
@@ -0,0 +1,31 @@
+[id="proc-ssh-auth-for-service-account"]
+
+= Require SSH key authentication for service account
+
+The service account must not be permitted to use password authentication with SSH connections to the managed node. 
+
+Use the following procedure to configure the SSH daemon: 
+
+.Procedure
+. Create the file `/etc/sshd/sshd_config.d/60-ansible.conf`, and include the following content:
++
+----
+# sshd config applied to the ansible service account
+Match User ansible
+	PasswordAuthentication no
+Match all
+----
+. Verify that the file uses the proper syntax:
++
+`sudo sshd -t`
+. Restart the SSH daemon
++
+`sudo systemctl restart sshd.service`
+
+Given that password authentication is prohibited, at least one SSH public key must be appended to the service account’s authorized_keys file (typically located at `/home/ansible/.ssh/authorized_keys`). 
+
+These public keys must correspond with the private keys used to establish Machine credentials in {PlatformNameShort}, as these credentials facilitate connections to the RHEL managed nodes.
+
+This guide advocates for a single service account for connections to managed RHEL nodes, but this does not mean using a single SSH key across all nodes is required. 
+In larger organizations, individual teams managing RHEL servers can generate their own machine credentials within {PlatformNameShort}. 
+Teams can then add the corresponding keys to the authorized keys file on their specific RHEL servers. This approach ensures consistent access to managed nodes organization-wide by using a common service account, while enabling each team to independently manage the credentials for their assigned nodes.
diff --git a/downstream/modules/aap-hardening/ref-architecture.adoc b/downstream/modules/aap-hardening/ref-architecture.adoc
@@ -15,12 +15,10 @@ The reference architecture chosen will include planning information such as an a
 
 It is possible to install {PlatformNameShort} on different infrastructure reference architectures and with different environment configurations. Red Hat does not fully test architectures outside of published reference architectures. Red Hat recommends using a tested reference architecture for all new deployments and provides commercially reasonable support for deployments that meet minimum requirements. 
 
-//This diagram might need to be updated.
+//This diagram might need updating.
 The following diagram is a tested container enterprise architecture:
 
 .Reference architecture overview
 image::cont-b-env-a.png[Infrastructure reference architecture that Red Hat has tested that customers can use when self-managing {PlatformNameShort}]
 
-//{EDAName} is a new feature of {PlatformNameShort} {PlatformVers} that was not available when the reference architecture detailed in Figure 1: Reference architecture overview was originally written. Currently, the supported configuration is a single {ControllerName}, single {HubName}, and single {EDAController} node with external (installer managed) database. For an organization interested in {EDAName}, the recommendation is to install according to the configuration documented in the link:{BaseURL}/red_hat_ansible_automation_platform/{PlatformVers}/html/red_hat_ansible_automation_platform_installation_guide/assembly-platform-install-scenario#ref-single-controller-hub-eda-with-managed-db[{PlatformNameShort} Installation Guide]. This document provides additional clarifications when {EDAName} specific hardening configuration is required.
 
-//For smaller production deployments where the full reference architecture may not be needed, this guide recommends deploying {PlatformNameShort} with a dedicated PostgreSQL database server whether managed by the installer or provided externally.
diff --git a/downstream/modules/aap-hardening/ref-fapolicyd-on-rhel.adoc b/downstream/modules/aap-hardening/ref-fapolicyd-on-rhel.adoc
diff --git a/downstream/modules/aap-hardening/ref-sensitive-variables-install-inventory.adoc b/downstream/modules/aap-hardening/ref-sensitive-variables-install-inventory.adoc
diff --git a/downstream/titles/aap-hardening/master.adoc b/downstream/titles/aap-hardening/master.adoc
