diff --git a/ansible-role-requirements.yml b/ansible-role-requirements.yml deleted file mode 100644 index 61c96f34..00000000 --- a/ansible-role-requirements.yml +++ /dev/null @@ -1,4 +0,0 @@ -- name: plugins - scm: git - src: https://git.openstack.org/openstack/openstack-ansible-plugins - version: master diff --git a/defaults/main.yml b/defaults/main.yml index 60a696b2..7168d6b0 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -14,12 +14,10 @@ # limitations under the License. ## STIG version selection -# During the Ocata development cycle, the role will begin adding the RHEL 7 -# STIG content. By default, all operating systems will use the RHEL 6 STIG -# until the work has completed. -# -# This variable should only be adjusted for testing purposes. -stig_version: rhel6 +# The RHEL 7 STIG content was first added in the Ocata release. +# The RHEL 6 STIG content is deprecated in the Ocata release. +# Valid options: rhel7, rhel6 +stig_version: rhel7 ## APT Cache Options # This variable is used across multiple OpenStack-Ansible roles to handle the diff --git a/doc/source/benefits.rst b/doc/source/benefits.rst deleted file mode 100644 index 11f4b663..00000000 --- a/doc/source/benefits.rst +++ /dev/null @@ -1,47 +0,0 @@ -Security benefits FAQ -===================== - -The openstack-ansible-security role provides hardened security configurations -for the host operating system as well as many common system services. - -Why should this role be applied to a system? --------------------------------------------- - -First and foremost, this role should be applied to production systems in -environments where security is a priority. If an OpenStack environment is -exposed to the internet or to large internal corporate networks, applying -this role will reduce the risk of compromised OpenStack infrastructure. The -changes made by the role should also reduce the impact of potential -compromises as well. - -Some deployers may be subject to industry compliance programs, such as -PCI-DSS, ISO 27001/27002, or NIST 800-53. Many of these programs require -hardening standards to be applied to critical systems, such as OpenStack -infrastructure components. - -Which systems are covered? --------------------------------------------------------- - -The openstack-ansible-security role provides security hardening for physical -servers running the following Linux distributions: - -* Ubuntu 14.04 -* Ubuntu 16.04 -* CentOS 7 -* Red Hat Enterprise Linux 7 - -The OpenStack gating system tests the role against each of these distributions -regularly except for Red Hat Enterprise Linux 7, since it is a non-free -Linux distribution. CentOS 7 is very similar to Red Hat Enterprise Linux 7 and -the existing test coverage for CentOS is very thorough. - -Which systems are not covered? ------------------------------- - -The containers that run various OpenStack services on physical servers in -OpenStack-Ansible deployments are currently out of scope and are not changed -by the role. - -Virtual machines that are created within the OpenStack environment are also -not affected by this role, although this role could be applied within those -VM's if a deployer chooses to do so. diff --git a/doc/source/controls-rhel7.rst b/doc/source/controls-rhel7.rst index 1f6e42da..90d27178 100644 --- a/doc/source/controls-rhel7.rst +++ b/doc/source/controls-rhel7.rst @@ -59,16 +59,6 @@ CentOS 7 systems. In addition, almost all of the controls are easily translated for Ubuntu 16.04. Any deviations during translation are noted within the documentation below. -.. note:: - - The RHEL 7 STIG content is still under development and is disabled by - default. Deployers can test the tasks on non-production systems by setting - the ``stig_version`` variable on the Ansible command line: - - .. code-block:: console - - ansible-playbook -i hosts playbook.yml -e stig_version=rhel7 - .. toctree:: :maxdepth: 2 diff --git a/doc/source/controls.rst b/doc/source/controls.rst index 04af6c02..ee114f6d 100644 --- a/doc/source/controls.rst +++ b/doc/source/controls.rst @@ -1,5 +1,5 @@ -Security hardening controls in detail -===================================== +Security hardening controls in detail (RHEL 6 STIG) +=================================================== The Security Technical Implementation Guide (STIG) for Red Hat Enterprise Linux 6 contains over 200 security controls. The links below will allow you to review @@ -27,6 +27,16 @@ Controls are divided into groups based on certain properties: You can also review the STIG controls in one very large page. This can be helpful when you need to search using your web browser. +.. note:: + + The RHEL 6 STIG content is deprecated in the Ocata release and will be + removed in a future release. Deployers can choose to deploy the RHEL 6 + STIG content by setting the ``stig_version`` Ansible variable: + + .. code-block:: console + + ansible-playbook -i hosts playbook.yml -e stig_version=rhel7 + .. toctree:: :maxdepth: 2 diff --git a/doc/source/developer-guide.rst b/doc/source/developer-guide.rst index 4f4888d7..ec327aed 100644 --- a/doc/source/developer-guide.rst +++ b/doc/source/developer-guide.rst @@ -34,10 +34,10 @@ exists as `YAML frontmatter `_ for each STIG configuration. The frontmatter is followed by the text of the deployer note itself. -All of the notes are found within ``doc/metadata/rhel6``. Here is an example -of V-38497: +All of the notes are found within ``doc/metadata/rhel7``. Here is an example +of RHEL-07-020210: -.. literalinclude:: ../metadata/rhel6/V-38497.rst +.. literalinclude:: ../metadata/rhel7/RHEL-07-020210.rst :language: yaml The block after the first three dashes (``---``) is the metadata. The metadata diff --git a/doc/source/faq.rst b/doc/source/faq.rst new file mode 100644 index 00000000..c6dbaa4f --- /dev/null +++ b/doc/source/faq.rst @@ -0,0 +1,65 @@ +Frequently Asked Questions +========================== + +Does this role work only with OpenStack environments? +----------------------------------------------------- + +No -- it works on almost any Linux host! + +The openstack-ansible-security role first began as a component of the +OpenStack-Ansible project and it was designed to deploy into an existing +OpenStack environment without causing disruptions. However, the role now works +well in OpenStack and non-OpenStack environments. + +See *Which systems are covered?* below for more details. + +Why should this role be applied to a system? +-------------------------------------------- + +There are three main reasons to apply this role to production Linux systems: + +Improve security posture + The configurations from the STIG add security and rigor around multiple + components of a Linux system, including user authentication, service + configurations, and package management. All of these configurations add up + to an environment that is more difficult for an attacker to penetrate and use + for lateral movement. + +Meet compliance requirements + Some deployers may be subject to industry compliance programs, such as + PCI-DSS, ISO 27001/27002, or NIST 800-53. Many of these programs require + hardening standards to be applied to critical systems, such as OpenStack + infrastructure components. + +Deployment without disruption + Security is often at odds with usability. The role provides the greatest + security benefit without disrupting production systems. Deployers have the + option to opt out or opt in for most configurations depending on how their + environments are configured. + +Which systems are covered? +-------------------------------------------------------- + +The openstack-ansible-security role provides security hardening for physical +servers running the following Linux distributions: + +* Ubuntu 14.04 +* Ubuntu 16.04 +* CentOS 7 +* Red Hat Enterprise Linux 7 + +The OpenStack gating system tests the role against each of these distributions +regularly except for Red Hat Enterprise Linux 7, since it is a non-free +Linux distribution. CentOS 7 is very similar to Red Hat Enterprise Linux 7 and +the existing test coverage for CentOS is very thorough. + +Which systems are not covered? +------------------------------ + +The containers that run various OpenStack services on physical servers in +OpenStack-Ansible deployments are currently out of scope and are not changed +by the role. + +Virtual machines that are created within the OpenStack environment are also +not affected by this role, although this role could be applied within those +VM's if a deployer chooses to do so. diff --git a/doc/source/getting-started.rst b/doc/source/getting-started.rst index 13ad7467..d888595a 100644 --- a/doc/source/getting-started.rst +++ b/doc/source/getting-started.rst @@ -28,21 +28,9 @@ The role will be installed into Initial configuration --------------------- -Some of the security configurations need initial configuration or they may -require you to opt-in for a change to be applied. Start by reviewing the list -of STIG controls that -:ref:`require initial configuration ` -or :ref:`require opt-in `. - -An example of a STIG requiring initial configuration is -:ref:`V-38446 `, which requires an email address for a person -who can receive email sent to ``root``. - -Many of the STIG configurations are in an *opt-in* status because they can be -helpful for some systems and harmful to others. A good example of this is -:ref`V-38481 `, which requires that automatic package updates are -configured on a host. In some environments, this isn't a problem, but this -could cause disruptions in environments with low tolerance for changes. +The role's default configuration is suitable for most Linux hosts. Deployers +should review the :ref:`special_notes` section to learn more about how to +provide custom configuration for the Ansible tasks in the role. Using as a standalone role -------------------------- @@ -67,8 +55,8 @@ Using with OpenStack-Ansible ---------------------------- The openstack-ansible-security role is automatically enabled and applied in the -Newton release of OpenStack-Ansible. In the Liberty and Mitaka releases, the -role is easily enabled by adjusting the following Ansible variable: +Newton release of OpenStack-Ansible. Set the following Ansible variable to +enable the role in the Mitaka release of OpenStack-Ansible: .. code-block:: yaml diff --git a/doc/source/index.rst b/doc/source/index.rst index 83d1dd58..6d36c09a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,99 +1,115 @@ -========================================== -OpenStack-Ansible: Host security hardening -========================================== +============================================ +Automated security hardening for Linux hosts +============================================ -Abstract -~~~~~~~~ +The openstack-ansible-security Ansible role uses industry-standard security +hardening guides to secure Linux hosts. Although the role is designed to work +well in OpenStack environments that are deployed with OpenStack-Ansible, it can +be used with almost any Linux system. -The openstack-ansible-security role provides security hardening for -`OpenStack`_ environments deployed with `openstack-ansible`_. The role has -multiple goals: +What does the role do? +---------------------- -* Provide additional security in a highly configurable, integrated way without - disrupting a production OpenStack environment. -* Make it easier for organizations to meet the requirements of compliance - programs, such as `Payment Card Industry Data Security Standard (PCI-DSS)`_. -* Document all changes to allow deployers to make educated decisions on which - security configuration changes to apply. +It all starts with the `Security Technical Implementation Guide (STIG)`_ from +the `Defense Information Systems Agency (DISA)`_, part of the United States +Department of Defense. The guide is released with a public domain license and +it is commonly used to secure systems at public and private organizations +around the world. -At this time, the role follows the requirements of the US Government's -`Security Technical Implementation Guide (STIG)`_ for Red Hat Enterprise Linux -6. +Each configuration from the STIG is analyzed to determine what impact it could +have on a live production environment and how to implement it in Ansible. Tasks +are added to the role that configure a host to meet the configuration +requirement. Each task is documented to explain what was changed, why it was +changed, and what deployers need to understand about the change. -The easiest method for reviewing the STIG configurations and the relevant -metadata is through the `STIG Viewer`_ service provided by `UCF`_. +Deployers have the option to pick and choose which configurations are applied +using Ansible variables and tags. Some tasks allow deployers to provide custom +configurations to tighten down or relax certain requirements. -.. _OpenStack: http://www.openstack.org/ -.. _openstack-ansible: http://docs.openstack.org/developer/openstack-ansible/ -.. _Payment Card Industry Data Security Standard (PCI-DSS): https://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard -.. _Security Technical Implementation Guide (STIG): https://en.wikipedia.org/wiki/Security_Technical_Implementation_Guide -.. _STIG Viewer: https://www.stigviewer.com/stig/red_hat_enterprise_linux_6/ -.. _UCF: http://www.unifiedcompliance.com/ +For more details, review the *Documentation* section below. -Ocata: Development -~~~~~~~~~~~~~~~~~~ +.. _Security Technical Implementation Guide (STIG): http://iase.disa.mil/stigs/Pages/index.aspx +.. _Defense Information Systems Agency (DISA): http://www.disa.mil/ -The openstack-ansible-security role is currently under development for the -Ocata release. +Documentation +------------- + +The following documentation applies to the Ocata release. Documentation from +previous releases are available in the *Releases* section below. .. toctree:: :maxdepth: 2 - benefits.rst + faq.rst getting-started.rst special-notes.rst - controls.rst + controls-rhel7.rst developer-guide.rst -Development is underway for adding the Red Hat Enterprise Linux 7 STIG content -to the openstack-ansible-security role. The documentation for this work is -available in this section: +The RHEL 7 STIG content was first added in the Ocata release. The original RHEL +6 STIG content is deprecated in the Ocata release and will be removed in the +next OpenStack release (Pike). The documentation for the RHEL 6 STIG content is +still available: .. toctree:: :maxdepth: 2 - controls-rhel7.rst + controls.rst -Newton: Latest stable release -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Releases +-------- -The openstack-ansible-security role was first released with the 14.0.0 tag -on October 20th, 2016. Refer to the `Newton release notes -`_ -for more details on the improvements and fixes. +Deployers should use the latest stable release for all production deployments. -The Newton release supports Ubuntu 14.04, Ubuntu 16.04, CentOS 7, and Red Hat -Enterprise Linux 7 `(partial automated test coverage)`. +Ocata +~~~~~ -* `openstack-ansible-security Newton Documentation`_ +* **Status:** Development *(anticipated release: February 2017)* + +* **Supported Operating Systems:** + + * Ubuntu 14.04 Trusty *(Deprecated)* + * Ubuntu 16.04 Xenial + * CentOS 7 + * Red Hat Enterprise Linux 7 *(partial automated test coverage)* + +* **Documentation:** + + * `openstack-ansible-security Ocata Release Notes`_ + +.. _openstack-ansible-security Ocata Release Notes: http://docs.openstack.org/releasenotes/openstack-ansible-security/unreleased.html + +Newton +~~~~~~ + +* **Status:** Latest stable release *(released 2016-10-20)* + +* **Supported Operating Systems:** + + * Ubuntu 14.04 Trusty + * Ubuntu 16.04 Xenial + * CentOS 7 + * Red Hat Enterprise Linux 7 *(partial automated test coverage)* + +* **Documentation:** + + * `openstack-ansible-security Newton Documentation`_ + * `openstack-ansible-security Newton Release Notes`_ .. _openstack-ansible-security Newton Documentation: http://docs.openstack.org/developer/openstack-ansible-security/newton/ +.. _openstack-ansible-security Newton Release Notes: http://docs.openstack.org/releasenotes/openstack-ansible-security/newton.html Mitaka ~~~~~~ -The Mitaka release of the openstack-ansible-security role was first released -with the 13.0.0 tag on April 1st, 2016. Refer to the `Mitaka release notes -`_ -for more details on the improvements and fixes. +* **Status:** Stable release *(released 2016-04-01)* -Ubuntu 14.04 is supported in the Mitaka release. +* **Supported Operating Systems:** Ubuntu 14.04 Trusty -* `openstack-ansible-security Mitaka Documentation`_ +* **Documentation:** + + * `openstack-ansible-security Mitaka Documentation`_ + * `openstack-ansible-security Mitaka Release Notes`_ .. _openstack-ansible-security Mitaka Documentation: http://docs.openstack.org/developer/openstack-ansible-security/mitaka/ - -Liberty -~~~~~~~ - -Refer to the `Liberty release notes -`_ -for more details on the improvements and fixes. The Liberty release will reach -EOL on November 17th, 2016. - -Ubuntu 14.04 is supported in the Liberty release. - -* `openstack-ansible-security Liberty Documentation`_ - -.. _openstack-ansible-security Liberty Documentation: http://docs.openstack.org/developer/openstack-ansible-security/liberty/ - +.. _openstack-ansible-security Mitaka Release Notes: http://docs.openstack.org/releasenotes/openstack-ansible-security/mitaka.html diff --git a/doc/source/special-notes.rst b/doc/source/special-notes.rst index 4132c071..7f4ed437 100644 --- a/doc/source/special-notes.rst +++ b/doc/source/special-notes.rst @@ -1,3 +1,5 @@ +.. _special_notes: + Deviations & Special Notes ========================== @@ -69,7 +71,7 @@ must set the following Ansible variable to initialize the database: .. code-block:: yaml - security_initialize_aide: true + security_rhel7_initialize_aide: true auditd ------ @@ -80,20 +82,20 @@ syscalls on a Linux system and logs alerts based on sets of auditing rules. Rules for auditd Each set of rules is controlled by Ansible variables that begin with - ``security_audit_``. To omit a set of rules on a host, set the variable to - ``no``. To include a set of rules on a host, set the variable to ``yes``. + ``security_audit__rhel7``. To omit a set of rules on a host, set the variable + to ``no``. To include a set of rules on a host, set the variable to ``yes``. - For example, setting ``security_audit_filesystem_mounts`` to ``yes`` will + For example, setting ``security_rhel7_audit_mount`` to ``yes`` will ensure that the rules for auditing filesystem mounts are included on each - host. Setting ``security_audit_filesystem_mounts`` to ``no`` will omit that + host. Setting ``security_rhel7_audit_mount`` to ``no`` will omit that group of rules on each host. To review the full list of rules and variables, refer to - ``templates/osas-auditd.j2``. + ``templates/osas-auditd-rhel7.j2``. Handling audit emergencies There are several configurations for auditd which are critical for deployers - to review in detail. The options beneath the ``## Auditd configuration`` + to review in detail. The options beneath the ``## Audit daemon (auditd)`` comment will change how auditd handles log files and what it should do in case of emergencies. @@ -101,54 +103,8 @@ Handling audit emergencies Some of these configuration options can cause serious issues on production systems, ranging from a reduction in security to servers going - offline unexpectedly. There is extensive documentation in the developer notes - for each STIG requirement. - -Authentication --------------- - -The STIG sets requirements for various authentication-related security -controls, including password complexity, password aging/locking, and -simultaneous logins. All of these can cause issues on production systems. - -Handling multiple failed login attempts - The fail2ban service is installed to meet some requirements around failed - login attempts. The STIG requires ``pam_faillock``, but that module isn't - available in the Linux distributions supported by this role. - - To opt-in for the fail2ban service to be installed, set - ``security_install_fail2ban`` to ``yes`` and set an appropriate time for bans - with ``security_fail2ban_bantime``. See the notes for - :ref:`V-38501 ` for more details. - - Note that fail2ban will not take action on failed logins via physical - consoles or consoles exposed to out of band interfaces, such as DRAC, IPMI, - or iLO. This will be fixed in a future release. - -Deployers are urged to review each item in the ``## PAM and Authentication`` -section in ``defaults/main.yml`` as well as the developer notes for each -requirement. The notes explain the potential pitfalls from each configuration -item and they provide alternatives when a configuration isn't directly -available. - -Kernel modules --------------- - -Certain kernel modules are restricted by the STIG because they can become a -security threat to a server. The Ansible tasks will disable most of these -variables in accordance with the STIG. These changes are controlled by Ansible -variables matching the pattern ``security_disable_module_MODULENAME``. Refer to -``defaults/main.yml`` for a full list of these variables. - -A setting of ``yes`` means that the module will be disabled on the next boot -and a setting of ``no`` means that the state of the module will not be changed. - -All of the defaults are set in accordance with the STIG's requirements with -the exception of the ``usb_storage`` kernel module. This module is used -frequently with external hard drives, USB sticks, and with some IPMI -implementations. Deployers who wish to follow the STIG guidelines will need -to set ``usb_storage`` to ``yes`` so that the ``usb_storage`` module is -disabled on the next boot. + offline unexpectedly. There is extensive documentation in the developer + notes for each STIG requirement. Linux Security Modules (LSM) ---------------------------- @@ -158,59 +114,14 @@ security against attacks. The security role will enable SELinux on CentOS systems and enable AppArmor on Ubuntu systems. For more information on how these changes are applied, refer to the -documentation for :ref:`V-51337 `. - -Mail ----- - -Deployers are strongly urged to configure an address to receive the ``root`` -user's email on various hosts. This is done with the -``security_root_forward_email`` variable. - -The STIG requires that a valid user receives the email in case of errors or a -security issue. - -Removing and disabling services -------------------------------- - -The STIG has recommendations for which services shouldn't be running and which -packages shouldn't be installed. These removals can be configured to meet -the requirements of the deployer. - -Disabling services - By default, the role will disable any services that are recommended to be - disabled by the STIG. These changes are controlled by Ansible variables that - match the ``security_disable_SERVICENAME`` pattern. Review these variables in - ``defaults/main.yml`` for more details. - - A setting of ``yes`` for a service will cause the service to be disabled in - accordance to the STIG's requirements. - - A setting of ``no`` causes the role to ignore the service entirely. If the - service is running, it will remain running. If the service is stopped, - it will remain stopped. - -Removing services - The STIG requires that some packages are completely removed from the server. - By default, the role will remove the packages in accordance with the STIG's - requirements. These changes are controlled by Ansible variables that match - the ``security_remove_SERVICENAME`` pattern. Review these variables in - ``defaults/main.yml`` for more details. - - A setting of ``yes`` for a service will cause the package that contains the - service to be removed from the system. If the service happens to be running - at the time, it will be stopped by ``apt``. - - A setting of ``no`` for a service will cause the role to ignore the package - that contains the service. If the package is installed, it will be left - installed. +documentation for :ref:`RHEL-07-020210 `. SSH server ---------- The STIG has some requirements for ssh server configuration and these requirements are applied by default by the role. To opt-out or change these -requirements, see the section under the ``## SSH configuration`` comment in +requirements, see the section under the ``## ssh server (sshd)`` comment in ``defaults/main.yml``. Deviation for PermitRootLogin @@ -222,20 +133,6 @@ Deviation for PermitRootLogin However, this can cause problems in some existing environments and the default for the role is to set it to ``yes`` (direct root logins allowed). -sysctl settings ---------------- - -The STIG requires that TCP SYN cookies enabled by default to protect against -certain types of attacks, like SYN floods. This can cause issues in some -environments with busy load balancers. Deployers should review the notes for -:ref:`V-38539 ` for more details. - -Also, the STIG requires IPv6 support to be fully disabled, and this could cause -issues for production systems. The role will not disable IPv6 by default, but -deployers can adjust this by changing ``security_disable_ipv6`` to ``yes``. - -Core dumps are also disabled by default in the openstack-ansible-security role. - Time synchronization -------------------- @@ -255,12 +152,3 @@ running on each host. That could be changed by using the ``security_allowed_ntp_subnets`` parameter. .. _RFC1918: https://en.wikipedia.org/wiki/Private_network#Private_IPv4_address_spaces - -umask adjustments ------------------ - -Certain umask adjustments are required by the STIG, but these can cause -problems with production systems. The requirements are commented out within -``defaults/main.yml`` and can be applied by uncommenting the variables that -start with ``security_umask_*``. There is extensive documentation available -within the developer notes for each STIG requirement. diff --git a/releasenotes/notes/rhel7-stig-default-f6c7c97498a8b2e7.yaml b/releasenotes/notes/rhel7-stig-default-f6c7c97498a8b2e7.yaml new file mode 100644 index 00000000..e9f06c16 --- /dev/null +++ b/releasenotes/notes/rhel7-stig-default-f6c7c97498a8b2e7.yaml @@ -0,0 +1,19 @@ +--- +features: + - | + The Red Hat Enterprise Linux (RHEL) 7 STIG content is now deployed by + default. Deployers can continue using the RHEL 7 STIG content by setting + the following Ansible variable: + + .. code-block:: yaml + + stig_version: rhel6 +upgrade: + - | + Deployers should review the new RHEL 7 STIG variables in + ``defaults/main.yml`` to provide custom configuration for the Ansible + tasks. +deprecations: + - | + The Red Hat Enteprise Linux 6 STIG content has been deprecated. The tasks + and variables for the RHEL 6 STIG will be removed in a future release. diff --git a/tox.ini b/tox.ini index e02ebdaf..87e9d2a6 100644 --- a/tox.ini +++ b/tox.ini @@ -108,15 +108,8 @@ deps = {[testenv:ansible]deps} setenv = {[testenv]setenv} - # NOTE(odyssey4me): We have to skip V-38462 as openstack-infra are now - # building images with apt config - # Apt::Get::AllowUnauthenticated set to true. - # NOTE(mhayden): Skipping V-38660 since openstack-infra has SNMP v1/2 in - # the images. This can be added back in once - # https://review.openstack.org/354819 merges. - # NOTE(mhayden): Skipping V-38620 since chrony cannot start with ntpd - # running in the gate images. - ANSIBLE_PARAMETERS=--skip-tags V-38462,V-38660 -e security_enable_chrony=no + # NOTE(mhayden): Disabling chrony since it causes conflicts in CI. + ANSIBLE_PARAMETERS=-e security_rhel7_enable_chrony=no commands = {[testenv:tests_clone]commands} bash -c "{toxinidir}/tests/common/test-ansible-functional.sh"