Skip to content

Commit eddbc9e

Browse files
ianf77ianf77
authored
Convert draft Hardening Guide to asciidoc (#3271) (#3335)
* Convert draft Hardening Guide to asciidoc Update and add new sections to existing content Complete asciidoc conversion of v3 Hardening Guide https://issues.redhat.com/browse/AAP-43908 * Convert draft Hardening Guide to asciidoc. Added two new parts. Not sure if required yet. Complete asciidoc conversion of v3 Hardening Guide https://issues.redhat.com/browse/AAP-43908 * Convert draft Hardening Guide to asciidoc Removed admonition Complete asciidoc conversion of v3 Hardening Guide https://issues.redhat.com/browse/AAP-43908 * Convert Hardening Guide to asciidoc Added hub variables and removed section 3. Complete asciidoc conversion of v3 Hardening Guide https://issues.redhat.com/browse/AAP-43908 * Convert draft Hardening Guide to asciidoc Corrections Complete asciidoc conversion of v3 Hardening Guide https://issues.redhat.com/browse/AAP-43908 * Convert draft Hardening Guide to asciidoc Removed section 3 Complete asciidoc conversion of v3 Hardening Guide https://issues.redhat.com/browse/AAP-43908 * Convert draft Hardening Guide to asciidoc Correction Complete asciidoc conversion of v3 Hardening Guide https://issues.redhat.com/browse/AAP-43908 * Convert draft hardening guide to asciidoc Correction to level Complete asciidoc conversion of v3 Hardening Guide https://issues.redhat.com/browse/AAP-43908 * Convert draft Hardening Guide to asciidoc Added new attribute Complete asciidoc conversion of v3 Hardening Guide https://issues.redhat.com/browse/AAP-43908
1 parent b2f7efe commit eddbc9e

20 files changed

+113
-51
lines changed

‎downstream/assemblies/aap-hardening/assembly-hardening-aap.adoc‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,20 +17,22 @@ include::aap-hardening/con-dns-ntp-service-planning.adoc[leveloffset=+2]
1717
include::aap-hardening/ref-dns.adoc[leveloffset=+3]
1818
include::aap-hardening/ref-dns-load-balancing.adoc[leveloffset=+3]
1919
include::aap-hardening/ref-ntp.adoc[leveloffset=+3]
20-
//include::aap-hardening/con-user-authentication-planning.adoc[leveloffset=+2]
21-
include::aap-hardening/ref-aap-authentication.adoc[leveloffset=+3]
20+
//include::aap-hardening/ref-aap-authentication.adoc[leveloffset=+3]
2221
//include::aap-hardening/ref-private-automation-hub-authentication.adoc[leveloffset=+3]
2322
include::aap-hardening/con-credential-management-planning.adoc[leveloffset=+2]
2423
include::aap-hardening/ref-aap-operational-secrets.adoc[leveloffset=+3]
2524
include::aap-hardening/con-automation-use-secrets.adoc[leveloffset=+3]
2625
include::aap-hardening/con-protect-sensitive-data-no-log.adoc[leveloffset=+3]
26+
include::aap-hardening/con-user-authentication-planning.adoc[leveloffset=+2]
27+
include::aap-hardening/ref-infrastructure-server-account-planning.adoc[leveloffset=+3]
28+
include::aap-hardening/ref-aap-account-planning.adoc[leveloffset=+3]
2729
include::aap-hardening/con-logging-log-capture.adoc[leveloffset=+2]
2830
include::aap-hardening/ref-auditing-incident-detection.adoc[leveloffset=+2]
2931
include::aap-hardening/con-rhel-host-planning.adoc[leveloffset=+2]
3032
include::aap-hardening/con-aap-additional-software.adoc[leveloffset=+3]
3133
include::aap-hardening/con-installation.adoc[leveloffset=+1]
3234
include::aap-hardening/con-install-secure-host.adoc[leveloffset=+2]
33-
//include::aap-hardening/ref-security-variables-install-inventory.adoc[leveloffset=+2]
35+
include::aap-hardening/ref-security-variables-install-inventory.adoc[leveloffset=+2]
3436
include::aap-hardening/proc-install-user-pki.adoc[leveloffset=+2]
3537
include::aap-hardening/ref-sensitive-variables-install-inventory.adoc[leveloffset=+2]
3638
//include::aap-hardening/con-controller-stig-considerations.adoc[leveloffset=+2]
@@ -43,7 +45,7 @@ include::aap-hardening/ref-sudo-nopasswd.adoc[leveloffset=+3]
4345
include::aap-hardening/ref-initial-configuration.adoc[leveloffset=+1]
4446
include::aap-hardening/ref-infrastructure-as-code.adoc[leveloffset=+2]
4547
//include::aap-hardening/con-controller-configuration.adoc[leveloffset=+2]
46-
include::aap-hardening/proc-configure-centralized-logging.adoc[leveloffset=+3]
48+
include::aap-hardening/proc-configure-centralized-logging.adoc[leveloffset=+2]
4749
//include::aap-hardening/proc-configure-external-authentication.adoc[leveloffset=+3]
4850
include::aap-hardening/con-external-credential-vault.adoc[leveloffset=+2]
4951
include::aap-hardening/con-day-two-operations.adoc[leveloffset=+1]

‎downstream/modules/aap-hardening/con-aap-additional-software.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,5 @@ When installing the {PlatformNameShort} components on {RHEL} servers, the {RHEL}
1111
Additional server capabilities must not be installed in addition to {PlatformNameShort}, as this is an unsupported configuration and might affect the security and performance of the {PlatformNameShort} software.
1212

1313
Similarly, when {PlatformNameShort} is deployed on a {RHEL} host, it installs software like the nginx web server, the Pulp software repository, and the PostgreSQL database server (unless a user-provided external database is used).
14-
This software should not be modified or used in a more generic fashion (for example, do not use nginx to serve additional website content or PostgreSQL to host additional databases) as this is an unsupported configuration and may affect the security and performance of {PlatformNameShort}.
15-
The configuration of this software is managed by the {PlatformNameShort} installer, and any manual changes might be undone when performing upgrades.
14+
This software should not be modified or used in a more generic fashion (for example, do not use nginx to serve additional website content or PostgreSQL to host additional databases) as this is an unsupported configuration and might affect the security and performance of {PlatformNameShort}.
15+
The configuration of this software is managed by the {PlatformNameShort} {Installer}, and any manual changes might be undone when performing upgrades.

‎downstream/modules/aap-hardening/con-credential-management-planning.adoc‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,9 @@
77

88
[role="_abstract"]
99

10-
{PlatformName} uses credentials to authenticate requests to jobs against machines, synchronize with inventory sources, and import project content from a version control system. {ControllerNameStart} manages three sets of secrets:
10+
{PlatformName} uses credentials to authenticate requests to jobs against machines, synchronize with inventory sources, and import project content from a version control system.
11+
12+
{ControllerNameStart} manages three sets of secrets:
1113

1214
* User passwords for *local {PlatformNameShort} users*.
1315
//See the xref:con-user-authentication-planning_{context}[User Authentication Planning] section of this guide for additional details.

‎downstream/modules/aap-hardening/con-deployment-methods.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ There are three different installation methods for {PlatformNameShort}:
99
* Operator-based on {OCP}
1010

1111
This document offers guidance on hardening {PlatformNameShort} when installed using either of the first two installation methods (RPM-based or container-based).
12-
This document further recommends using the container-based installation method for new deployments, as the RPM-based installer will be deprecated in a future release.
12+
This document further recommends using the container-based installation method for new deployments, as the RPM-based {Installer} will be deprecated in a future release.
1313

1414
For further information, see link:{URLReleaseNotes}/aap-2.5-deprecated-features#aap-2.5-deprecated-features[Deprecated features].
1515

‎downstream/modules/aap-hardening/con-install-secure-host.adoc‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,16 @@
77

88
[role="_abstract"]
99

10-
The {PlatformNameShort} installer can be run from one of the infrastructure servers, such as an {ControllerName}, or from an external system that has SSH access to the {PlatformNameShort} infrastructure servers.
11-
The {PlatformNameShort} installer is also used not just for installation, but for subsequent day-two operations, such as backup and restore, as well as upgrades.
10+
The {PlatformNameShort} {Installer} can be run from one of the infrastructure servers, such as an {ControllerName}, or from an external system that has SSH access to the {PlatformNameShort} infrastructure servers.
11+
The {PlatformNameShort} {Installer} is also used not just for installation, but for subsequent day-two operations, such as backup and restore, as well as upgrades.
1212
This guide recommends performing installation and day-two operations from a dedicated external server, hereafter referred to as the installation host.
13-
Doing so eliminates the need to log in to one of the infrastructure servers to run these functions. The installation host must only be used for management of {PlatformNameShort} and must not run any other services or software.
13+
Doing so eliminates the need to log in to one of the infrastructure servers to run these functions.
14+
The installation host must only be used for management of {PlatformNameShort} and must not run any other services or software.
1415

1516
The installation host must be a {RHEL} server that has been installed and configured in accordance with link:{BaseURL}/red_hat_enterprise_linux/9/html/security_hardening/index[Security hardening for Red Hat Enterprise Linux] and any security profile requirements relevant to your organization (CIS, STIG, and so on).
1617
Obtain the {PlatformNameShort} installer as described in the link:{URLPlanningGuide}/choosing_and_obtaining_a_red_hat_ansible_automation_platform_installer[Planning your installation], and create the installer inventory file as described in the link:{URLInstallationGuide}/assembly-platform-install-scenario#proc-editing-installer-inventory-file_platform-install-scenario[Editing the Red Hat Ansible Automation Platform installer inventory file].
17-
This inventory file is used for upgrades, adding infrastructure components, and day-two operations by the installer, so preserve the file after installation for future operational use.
18+
This inventory file is used for upgrades, adding infrastructure components, and day-two operations by the {Installer}, so preserve the file after installation for future operational use.
1819

1920
Access to the installation host must be restricted only to those personnel who are responsible for managing the {PlatformNameShort} infrastructure.
20-
Over time, it will contain sensitive information, such as the installer inventory (which contains the initial login credentials for {PlatformNameShort}), copies of user-provided PKI keys and certificates, backup files, and so on. The installation host must also be used for logging in to the {PlatformNameShort} infrastructure servers through SSH when necessary for infrastructure management and maintenance.
21+
Over time, it will contain sensitive information, such as the installation inventory (which contains the initial login credentials for {PlatformNameShort}), copies of user-provided PKI keys and certificates, backup files, and so on.
22+
The installation host must also be used for logging in to the {PlatformNameShort} infrastructure servers through SSH when necessary for infrastructure management and maintenance.

‎downstream/modules/aap-hardening/con-user-authentication-planning.adoc‎

Lines changed: 4 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,10 @@
55

66
= User authentication planning
77

8-
[role="_abstract"]
8+
There are two types of user accounts to consider in an {PlatformNameShort} environment:
9+
10+
* Infrastructure accounts: user accounts on the RHEL servers that run the {PlatformNameShort} services.
11+
* Application accounts: user accounts for the {PlatformNameShort} web UI and API.
912

10-
When planning for access to the {PlatformNameShort} user interface or API, be aware that user accounts can either be local or mapped to an external authentication source such as LDAP.
11-
This guide recommends that where possible, all primary user accounts should be mapped to an external authentication source.
12-
Using external account sources eliminates a source of error when working with permissions in this context and minimizes the amount of time devoted to maintaining a full set of users exclusively within {PlatformNameShort}. This includes accounts assigned to individual persons as well as for non-person entities such as service accounts used for external application integration.
13-
Reserve any local administrator accounts such as the default "admin" account for emergency access or "break glass" scenarios where the external authentication mechanism is not available.
1413

15-
For user accounts on the {RHEL} servers that run the {PlatformNameShort} services, follow your organizational policies to determine if individual user accounts should be local or from an external authentication source.
16-
Only users who have a valid need to perform maintenance tasks on the {PlatformNameShort} components themselves should be granted access to the underlying {RHEL} servers, as the servers will have configuration files that contain sensitive information such as encryption keys and service passwords.
17-
Because these individuals must have privileged access to maintain {PlatformNameShort} services, minimizing the access to the underlying {RHEL} servers is critical. Do not grant sudo access to the root account or local {PlatformNameShort} service accounts (awx, pulp, postgres) to untrusted users.
1814

19-
[NOTE]
20-
====
21-
The local {PlatformNameShort} service accounts such as awx, pulp, and postgres are created and managed by the {PlatformNameShort} installer. These particular accounts on the underlying {RHEL} hosts cannot come from an external authentication source.
22-
====

‎downstream/modules/aap-hardening/proc-configure-centralized-logging.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ When availability is an overriding concern, other approved actions in response t
9898
. If log records are sent to a centralized collection server and communication with this server is lost or the server fails, the application must queue log records locally until communication is restored or until the log records are retrieved manually.
9999
Upon restoration of the connection to the centralized collection server, action must be taken to synchronize the local log data with the collection server.
100100
+
101-
The following steps implment the security control:
101+
The following steps implement the security control:
102102

103103
.. Open a web browser and navigate to the logging API, `/api/v2/settings/logging/`
104104
+
@@ -110,7 +110,7 @@ Ensure that you are authenticated as an {ControllerName} administrator.
110110
..Click btn:[PUT].
111111

112112
{ControllerNameStart} must generate the appropriate log records.
113-
{ControllerNameStarts}'s web server must log all details related to user sessions in support of troubleshooting, debugging, and forensic analysis.
113+
{ControllerNameStart}'s web server must log all details related to user sessions in support of troubleshooting, debugging, and forensic analysis.
114114
Without a data logging feature, the organization loses an important auditing and analysis tool for event investigations.
115115

116116
To implement the security control as a System Administrator, for each {ControllerName} host:

‎downstream/modules/aap-hardening/proc-disaster-recovery-operations.adoc‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
[role="_abstract"]
99

10-
Taking regular backups of {PlatformNameShort} is a critical part of disaster recovery planning. Both backups and restores are performed using the installer, so these actions should be performed from the dedicated installation host described earlier in this document. Refer to the link:https://docs.ansible.com/automation-controller/latest/html/administration/backup_restore.html[Backing Up and Restoring] section of the {ControllerName} documentation for further details on how to perform these operations.
10+
Taking regular backups of {PlatformNameShort} is a critical part of disaster recovery planning. Both backups and restores are performed using the {Installer}, so these actions should be performed from the dedicated installation host described earlier in this document. Refer to the link:https://docs.ansible.com/automation-controller/latest/html/administration/backup_restore.html[Backing Up and Restoring] section of the {ControllerName} documentation for further details on how to perform these operations.
1111

1212
An important aspect of backups is that they contain a copy of the database as well as the secret key used to decrypt credentials stored in the database, so the backup files should be stored in a secure encrypted location. This means that access to endpoint credentials are protected properly. Access to backups should be limited only to {PlatformNameShort} administrators who have root shell access to {ControllerName} and the dedicated installation host.
1313

@@ -18,7 +18,7 @@ The two main reasons an {PlatformNameShort} administrator needs to back up their
1818

1919
In all cases, the recommended and safest process is to always use the same versions of PostgreSQL and {PlatformNameShort} to back up and restore the environment.
2020

21-
Using some redundancy on the system is highly recommended. If the secrets system is down, the {ControllerName} cannot fetch the information and can fail in a way that would be recoverable once the service is restored. If you believe the SECRET_KEY {ControllerName} generated for you has been compromised and has to be regenerated, you can run a tool from the installer that behaves much like the {ControllerName} backup and restore tool.
21+
Using some redundancy on the system is highly recommended. If the secrets system is down, the {ControllerName} cannot fetch the information and can fail in a way that would be recoverable once the service is restored. If you believe the SECRET_KEY {ControllerName} generated for you has been compromised and has to be regenerated, you can run a tool from the {Installer} that behaves much like the {ControllerName} backup and restore tool.
2222

2323
To generate a new secret key, perform the following steps:
2424

‎downstream/modules/aap-hardening/proc-file-systems-mounted-noexec.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
[role="_abstract"]
99

10-
A compliance profile might require that certain file systems are mounted with the `noexec` option to prevent execution of binaries located in these file systems. The {PlatformNameShort} RPM-based installer runs a preflight check that fails if any of the following file systems are mounted with the `noexec` option:
10+
A compliance profile might require that certain file systems are mounted with the `noexec` option to prevent execution of binaries located in these file systems. The {PlatformNameShort} RPM-based installation program runs a preflight check that fails if any of the following file systems are mounted with the `noexec` option:
1111

1212
* `/tmp`
1313
* `/var`

‎downstream/modules/aap-hardening/ref-aap-account-planning.adoc‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
[id="ref-aap-account-planning"]
2+
3+
= {PlatformNameShort} account planning
4+
5+
{PlatformNameShort} user accounts for accessing the user interface or API can either be local (stored in the {PlatformNameShort} database) or mapped to an external authentication source, such as a _Lightweight Directory Access Protocol_ (LDAP) server.
6+
This guide recommends that where possible, all primary user accounts should be mapped to an external authentication source.
7+
Using external account sources eliminates a source of error when working with permissions in this context and minimizes the amount of time devoted to maintaining a full set of users exclusively within {PlatformNameShort}.
8+
This includes accounts assigned to individual persons as well as for non-person entities, such as service accounts used for external application integration.
9+
Reserve any local accounts, such as the default “admin” account, for emergency access or “break glass” scenarios where the external authentication mechanism isn't available.
10+
11+
* LDAP
12+
* SAML
13+
* TACACS+
14+
* Radius
15+
* Azure Active Directory
16+
* Google OAuth
17+
* Generic OIDC
18+
* Keycloak
19+
* GitHub
20+
* GitHub Organization
21+
* GitHub team
22+
* GitHub enterprise
23+
* GitHub enterprise organization
24+
* GitHub enterprise team
25+
26+
Choose an authentication mechanism that adheres to your organization's authentication policies and refer to link:{LinkCentralAuth} to understand the prerequisites for the relevant authentication mechanism.
27+
The authentication mechanism used must ensure that the authentication-related traffic between {PlatformNameShort} and the authentication back-end is encrypted when the traffic occurs on a public or non-secure network (for example, LDAPS or LDAP over TLS, HTTPS for OAuth2 and SAML providers, etc.).
28+
29+
In the {PlatformNameShort} UI, any “system administrator” account can edit, change, and update any inventory or automation definition. Restrict these account privileges to the minimum set of users possible for low-level automation controller configuration and disaster recovery.
30+
31+
[NOTE]
32+
====
33+
{platformNameShort} {PlatformVers} introduces a new central authentication mechanism used by all of the platform components:
34+
35+
* {ControllerNameStart}
36+
* {PrivateHubNameStart}
37+
* {EDAcontroller}
38+
39+
Before {PlatformVers}, each of these components had their own authentication configuration.
40+
====

0 commit comments

Comments
 (0)