diff --git a/downstream/assemblies/aap-hardening/assembly-aap-security-enabling.adoc b/downstream/assemblies/aap-hardening/assembly-aap-security-enabling.adoc deleted file mode 100644 index 618334d88..000000000 --- a/downstream/assemblies/aap-hardening/assembly-aap-security-enabling.adoc +++ /dev/null @@ -1,20 +0,0 @@ -ifdef::context[:parent-context: {context}] - -[id="aap-security-enabling"] -= {PlatformNameShort} as a security enabling tool - -:context: aap-security-enabling - -[role="_abstract"] - - - -//// -Consider adding a link to future Builder docs here -[role="_additional-resources"] -.Additional resources -* A bulleted list of links to other material closely related to the contents of the concept module. -* Currently, modules cannot include xrefs, so you cannot include links to other content in your collection. If you need to link to another assembly, add the xref to the assembly that includes this module. -* For more details on writing concept modules, see the link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. -* Use a consistent system for file names, IDs, and titles. For tips, see _Anchor Names and File Names_ in link:https://github.com/redhat-documentation/modular-docs#modular-documentation-reference-guide[Modular Documentation Reference Guide]. -//// \ No newline at end of file diff --git a/downstream/assemblies/aap-hardening/assembly-aap-security-use-cases.adoc b/downstream/assemblies/aap-hardening/assembly-aap-security-use-cases.adoc new file mode 100644 index 000000000..0e6080ea3 --- /dev/null +++ b/downstream/assemblies/aap-hardening/assembly-aap-security-use-cases.adoc @@ -0,0 +1,21 @@ +ifdef::context[:parent-context: {context}] + +[id="aap-security-use-cases"] += {PlatformNameShort} security use cases + +:context: aap-security-use-cases + +[role="_abstract"] + +{PlatformNameShort} provides organizations the opportunity to automate many of the manual tasks required to maintain a strong IT security posture. +Areas where security operations may be automated include security event response and remediation, routine security operations, compliance with security policies and regulations, and security hardening of IT infrastructure. + +include::aap-hardening/con-aap-as-SOC.adoc[leveloffset=+1] +include::aap-hardening/con-aap-patch-automation.adoc[leveloffset=+1] +include::aap-hardening/con-patch-automation.adoc[leveloffset=+2] +include::aap-hardening/ref-patching-examples.adoc[leveloffset=+2] +include::aap-hardening/ref-keeping-everything-up-to-date.adoc[leveloffset=+3] +include::aap-hardening/ref-installing-security-updates-only.adoc[leveloffset=+3] +include::aap-hardening/ref-specifying-package-versions.adoc[leveloffset=+3] +include::aap-hardening/ref-complex-patching-scenarios.adoc[leveloffset=+2] + diff --git a/downstream/assemblies/aap-hardening/assembly-hardening-aap.adoc b/downstream/assemblies/aap-hardening/assembly-hardening-aap.adoc index a2aa73696..68612cf9a 100644 --- a/downstream/assemblies/aap-hardening/assembly-hardening-aap.adoc +++ b/downstream/assemblies/aap-hardening/assembly-hardening-aap.adoc @@ -42,6 +42,7 @@ include::aap-hardening/con-controller-configuration.adoc[leveloffset=+2] include::aap-hardening/proc-configure-centralized-logging.adoc[leveloffset=+3] include::aap-hardening/proc-configure-external-authentication.adoc[leveloffset=+3] include::aap-hardening/con-external-credential-vault.adoc[leveloffset=+3] +// include::aap-hardening/ref-apply-defensive-security-controls.adoc[leveloffset=+2] include::aap-hardening/con-day-two-operations.adoc[leveloffset=+1] include::aap-hardening/con-rbac.adoc[leveloffset=+2] include::aap-hardening/ref-updates-upgrades.adoc[leveloffset=+2] diff --git a/downstream/images/aap-workflow-example.png b/downstream/images/aap-workflow-example.png new file mode 100644 index 000000000..f7d9cf4ae Binary files /dev/null and b/downstream/images/aap-workflow-example.png differ diff --git a/downstream/modules/aap-hardening/con-aap-as-SOC.adoc b/downstream/modules/aap-hardening/con-aap-as-SOC.adoc new file mode 100644 index 000000000..a1c3ed77a --- /dev/null +++ b/downstream/modules/aap-hardening/con-aap-as-SOC.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// downstream/assemblies/assembly-aap-security-use-cases.adoc + +[id="con-aap-as-SOC_{context}"] + += {PlatformName} as part of a Security Operations Center + +[role="_abstract"] + +Protecting your organization is a critical task. +Automating functions of your security operations center (SOC) can help you streamline security operations, response, and remediation activities at scale to reduce the risk and cost of breaches. +{PlatformName} can connect your security teams, tools, and processes for more successful automation adoption and use. +Learn how automation can help you safeguard your business and respond to growing security threats faster. + +link:https://www.redhat.com/en/resources/security-automation-ebook[Simplify your security operations center] provides an overview of the benefits to automating SOC operations, including use cases such as: + +* Investigation enrichment +* Threat hunting +* Incident response diff --git a/downstream/modules/aap-hardening/con-aap-patch-automation.adoc b/downstream/modules/aap-hardening/con-aap-patch-automation.adoc new file mode 100644 index 000000000..90b6444a5 --- /dev/null +++ b/downstream/modules/aap-hardening/con-aap-patch-automation.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// downstream/assemblies/assembly-aap-security-use-cases.adoc + +[id="con-aap-patch-automation_{context}"] + += Patch automation with {PlatformNameShort} + +[role="_abstract"] + +Software patching is a fundamental activity of security and IT operations teams everywhere. +Keeping patches up to date is critical to remediating software vulnerabilities and meeting compliance requirements, but patching systems manually at scale can be time-consuming and error-prone. +Organizations should put thought into patch management strategies that meet their security, compliance, and business objectives, in order to prioritize the types of patches to apply (known exploits, critical or important vulnerabilities, optimizations, routine updates, new features, and so on) against the IT assets available across the enterprise. + +Once you have defined policies and priorities and established a patching plan, you can automate the manual patch management tasks using the {PlatformNameShort}. +Automating the tasks improves patch deployment speed and accuracy, reduces human error, and limits downtime. diff --git a/downstream/modules/aap-hardening/con-patch-automation.adoc b/downstream/modules/aap-hardening/con-patch-automation.adoc new file mode 100644 index 000000000..a2dc3cf72 --- /dev/null +++ b/downstream/modules/aap-hardening/con-patch-automation.adoc @@ -0,0 +1,18 @@ +// Module included in the following assemblies: +// downstream/assemblies/assembly-aap-security-use-cases.adoc + +[id="con-patch-automation_{context}"] + += Benefits of patch automation + +[role="_abstract"] + +Automating the patching process provides a number of benefits: + +* Reduces error-prone manual effort. +* Decreases time to deploy patches at scale. +* Ensures consistency of patches across similar systems. +Manual patching of similar systems could result in human error (forgetting one or more, patching using different versions) that impacts consistency. +* Enables orchestration of complex patching scenarios where an update may require taking a system snapshot before applying a patch, or may require additional configuration changes once the patch is applied. + + diff --git a/downstream/modules/aap-hardening/ref-apply-defensive-security-controls.adoc b/downstream/modules/aap-hardening/ref-apply-defensive-security-controls.adoc new file mode 100644 index 000000000..0193cf8f0 --- /dev/null +++ b/downstream/modules/aap-hardening/ref-apply-defensive-security-controls.adoc @@ -0,0 +1,49 @@ +// Module included in the following assemblies: +// downstream/assemblies/assembly-hardening-aap.adoc + +[id="ref-apply-defensive-security-controls_{context}"] + += Applying defensive security controls + +[role="_abstract"] + +The following set of defensive security controls are recommended to reduce operational risk of {PlatformNameShort} deployed on physical or virtual machines. +These controls apply to all of the {PlatformNameShort} infrastructure nodes: the dedicated installation host, and any servers listed in the installation inventory such as controllers, hubs, EDA controllers, and the database server. +Some of these controls are listed elsewhere in this document, but are repeated here for convenience. + +. Apply the appropriate compliance policy controls for your organization to the {PlatformNameShort} infrastructure nodes, such as CIS, HIPAA, PCI/DSS, or the DISA STIG. +. Limit administrative access to the {PlatformNameShort} infrastructure nodes. +** Only system administrators responsible for these servers and the installation and upgrade of {PlatformNameShort} should have accounts on the infrastructure nodes. +** Each system administrator should log in with an individual account with appropriate sudo privileges. +The root account should only be used for emergency situations such as when external authentication services are not available. +Rotate the root password according to your organizational policies. +. Limit remote SSH access to the {PlatformNameShort} infrastructure nodes. +** Apply firewall or cloud security group rules to prevent remote SSH access to the infrastructure nodes except from the dedicated installation host and a subset of trusted hosts used by the system administrators for day-to-day tasks. +** Disable direct root access over SSH. Root access should only be allowed at the physical or virtual console of the infrastructure servers. +** Optionally, apply Host-based Access Controls (HBAC) rules using an external authentication mechanism such as Red Hat Identity Management (IdM) to allow only select user accounts remote access to the {PlatformNameShort} infrastructure nodes. +For more information, see link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html-single/managing_idm_users_groups_hosts_and_access_control_rules/index#configuring-hbac-rules-in-an-idm-domain-using-the-webui_configuring-host-based-access-control-rules[46.1. Configuring HBAC rules in an IdM domain using the WebUI] +. Optionally, if your organization uses a third-party privileged access management tool it may be used to control access to the credentials needed by {PlatformNameShort} system administrators to access the infrastructure nodes. +. Enable audit rules to monitor and alert on any access or changes to the set of {PlatformNameShort} configuration files. +This enables visibility, traceability and control and ensures no change to the files without triggering an audit event. +See link:https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html/security_hardening/auditing-the-system_security-hardening#defining-persistent-audit-rules_auditing-the-system[12.7 Defining persistent Audit rules] in the Red Hat Enterprise Linux documentation for additional details. +.. In {ControllerName}, create the file `/etc/audit/rules.d/75-automation-controller.rules` with the following content, then run `augenrules --load` to load the new rules: + +----- +-w /etc/tower/ -p warx -k aap-aac-mon-confdir +-w /etc/supervisord.conf -p warx -k aap-aac-mon-supervisord +-w /etc/supervisord.d/ -p warx -k aap-aac-mon-supervisord +-w /etc/nginx/ -p warx -k aap-aac-mon-nginx +-w /etc/receptor/ -p war -k aap-aac-mon-receptor +-w /etc/redis/ -p war -k aap-aac-mon-redis +----- + +. In {HubName}, create the file `/etc/audit/rules.d/75-automation-hub.rules` with the following content, then run `augenrules --load` to load the new rules: + +----- +-w /etc/pulp/ -p warx -k aap-hub-mon-confdir +-w /etc/redis/ -p war -k aap-hub-mon-redis +-w /etc/nginx/ -p warx -k aap-hub-mon-nginx +----- + +[NOTE] +If the audit rules are set to be immutable (that is, `-e 2` is set in `/etc/audit/audit.rules`), a reboot will be required for the new audit rules to take effect. diff --git a/downstream/modules/aap-hardening/ref-complex-patching-scenarios.adoc b/downstream/modules/aap-hardening/ref-complex-patching-scenarios.adoc new file mode 100644 index 000000000..cd0f044d6 --- /dev/null +++ b/downstream/modules/aap-hardening/ref-complex-patching-scenarios.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// downstream/assemblies/assembly-aap-security-use-cases.adoc + +[id="ref-complex-patching-scenarios_{context}"] + += Complex patching scenarios + +[role="_abstract"] + +In {PlatformNameShort}, multiple automation jobs can be chained together into workflows, which can be used to coordinate multiple steps in a complex patching scenario. + +The following example complex patching scenario demonstrates taking virtual machine snapshots, patching the virtual machines, and creating tickets when an error is encountered in the workflow. + +.Procedure + +. Run a project sync to ensure the latest playbooks are available. In parallel, run an inventory sync to make sure the latest list of target hosts is available. +. Take a snapshot of each target host. +.. If the snapshot task fails, submit a ticket with the relevant information. +. Patch each of the target hosts. +.. If the patching task fails, restore the snapshot and submit a ticket with the relevant information. +. Delete each snapshot where the patching task was successful. + +The following workflow visualization describes how the components of the example complex patching scenario are executed: + +image::aap-workflow-example.png[Workflow visualization for example complex patching scenario] + +.Additional resources +For more information on workflows, see link:https://access.redhat.com/documentation/en-us/red_hat_ansible_automation_platform/2.4/html/automation_controller_user_guide/controller-workflows[Workflows in {ControllerName}]. diff --git a/downstream/modules/aap-hardening/ref-installing-security-updates-only.adoc b/downstream/modules/aap-hardening/ref-installing-security-updates-only.adoc new file mode 100644 index 000000000..6f22c2701 --- /dev/null +++ b/downstream/modules/aap-hardening/ref-installing-security-updates-only.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// downstream/assemblies/assembly-aap-security-use-cases.adoc + +[id="ref-installing-security-updates-only_{context}"] + += Installing security updates only + +[role="_abstract"] + +If your organization has a policy requiring that all RPMs including security errata be kept up to date, you can use the following playbook in a regularly scheduled job template. + +----- +--- +- name: Install all security-related RPM updates + hosts: target_hosts + become: true + + tasks: + - name: Install latest RPMs with security errata + ansible.builtin.dnf: + name: '*' + security: true + state: latest +----- \ No newline at end of file diff --git a/downstream/modules/aap-hardening/ref-keeping-everything-up-to-date.adoc b/downstream/modules/aap-hardening/ref-keeping-everything-up-to-date.adoc new file mode 100644 index 000000000..5b7a50d80 --- /dev/null +++ b/downstream/modules/aap-hardening/ref-keeping-everything-up-to-date.adoc @@ -0,0 +1,24 @@ +// Module included in the following assemblies: +// downstream/assemblies/assembly-aap-security-use-cases.adoc + +[id="ref-keeping-everything-up-to-date_{context}"] + += Keeping everything up to date + +[role="_abstract"] + +For some RHEL servers, such as a lab or other non-production systems, administrators might want to install all available patches on a regular cadence. +The following example playbook can be used in a job template that is scheduled to run weekly. It updates the system with all of the latest RPMs. + +----- +--- +- name: Install all available RPM updates + hosts: target_hosts + become: true + + tasks: + - name: Install latest RPMs + ansible.builtin.dnf: + name: '*' + state: latest +----- \ No newline at end of file diff --git a/downstream/modules/aap-hardening/ref-patching-examples.adoc b/downstream/modules/aap-hardening/ref-patching-examples.adoc new file mode 100644 index 000000000..b1bfeb6be --- /dev/null +++ b/downstream/modules/aap-hardening/ref-patching-examples.adoc @@ -0,0 +1,15 @@ +// Module included in the following assemblies: +// downstream/assemblies/assembly-aap-security-use-cases.adoc + +[id="ref-patching-examples_{context}"] + += Patching examples + +[role="_abstract"] + +The following playbooks are provided as patching examples, and should be modified to fit the target environment and tested thoroughly before being used in production. +These examples use the `ansible.builtin.dnf` module for managing packages on RHEL and other operating systems that use the `dnf` package manager. +Modules for patching other Linux operating systems, Microsoft Windows, and many network devices are also available. + + + diff --git a/downstream/modules/aap-hardening/ref-specifying-package-versions.adoc b/downstream/modules/aap-hardening/ref-specifying-package-versions.adoc new file mode 100644 index 000000000..a980297e6 --- /dev/null +++ b/downstream/modules/aap-hardening/ref-specifying-package-versions.adoc @@ -0,0 +1,45 @@ +// Module included in the following assemblies: +// downstream/assemblies/assembly-aap-security-use-cases.adoc + +[id="ref-specifying-package-versions_{context}"] + += Specifying package versions + +[role="_abstract"] + +For production systems, it is a well-established configuration management practice to deploy only known, tested combinations of software to ensure that systems are configured correctly and perform as expected. +This includes deploying only known versions of operating system software and patches to ensure that system updates do not introduce problems with production applications. +The following example playbook installs a specific version of the `httpd` RPM and its dependencies when the target host uses the RHEL 9 operating system. + +[NOTE] +This playbook will not take action if the specified versions are already in place or if a different version of RHEL is installed. + +----- +--- +- name: Install specific RPM versions + hosts: target_hosts + gather_facts: true + become: true + + vars: + httpd_packages_rhel9: + - httpd-2.4.53-11.el9_2.5 + - httpd-core-2.4.53-11.el9_2.5 + - httpd-filesystem-2.4.53-11.el9_2.5 + - httpd-tools-2.4.53-11.el9_2.5 + - mod_http2-1.15.19-4.el9_2.4 + - mod_lua-2.4.53-11.el9_2.5 + + tasks: + - name: Install httpd and dependencies + ansible.builtin.dnf: + name: '{{ httpd_packages_rhel9 }}' + state: present + allow_downgrade: true + when: + - ansible_distribution == "RedHat" + - ansible_distribution_major_version == "9" +----- + +[NOTE] +By setting `allow_downgrade: true`, if a newer version of any defined package is installed on the system, it will be downgraded to the specified version instead. diff --git a/downstream/titles/aap-hardening/master.adoc b/downstream/titles/aap-hardening/master.adoc index ff919aebb..c7acaef04 100644 --- a/downstream/titles/aap-hardening/master.adoc +++ b/downstream/titles/aap-hardening/master.adoc @@ -17,5 +17,5 @@ include::aap-common/providing-direct-documentation-feedback.adoc[leveloffset=+1] include::aap-hardening/assembly-intro-to-aap-hardening.adoc[leveloffset=+1] include::aap-hardening/assembly-hardening-aap.adoc[leveloffset=+1] // include::aap-hardening/assembly-aap-compliance.adoc[leveloffset=+1] -// include::aap-hardening/assembly-aap-security-enabling.adoc[leveloffset=+1] +include::aap-hardening/assembly-aap-security-use-cases.adoc[leveloffset=+1]