diff --git a/README.md b/README.md index 604a4ba2..86bcf4f5 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,25 @@ openstack-ansible-security ========================== -The goal of the openstack-ansible-security role is to improve security within [openstack-ansible](https://github.com/openstack/openstack-ansible) deployments. The role is based on the [Security Technical Implementation Guide (STIG)](http://iase.disa.mil/stigs/Pages/index.aspx) for [Red Hat Enterprise Linux 6](https://www.stigviewer.com/stig/red_hat_enterprise_linux_6/). +The openstack-ansible security role applies security hardening configurations +from the [Security Technical Implementation Guide(STIG)](http://iase.disa.mil/stigs/Pages/index.aspx) +to systems running Ubuntu 14.04, Ubuntu 16.04, CentOS 7, and Red Hat +Enterprise Linux 7. + +The role is part of the +[OpenStack-Ansible project](https://github.com/openstack/openstack-ansible), +which deploys enterprise-grade OpenStack clouds using Ansible. However, the +role can easily be used outside of an OpenStack environment to secure hosts, +virtual machines, and containers. + +For more details, review the +[openstack-ansible-security documentation](http://docs.openstack.org/developer/openstack-ansible-security/). Requirements ------------ -This role can be used with or without the openstack-ansible role. It requires -Ansible 1.8.3 at a minimum. +This role can be used with or without the OpenStack-Ansible role. It requires +Ansible 1.9.1 or later. Role Variables -------------- diff --git a/README.rst b/README.rst index 64d48a43..bd9e9eae 100644 --- a/README.rst +++ b/README.rst @@ -1,39 +1,7 @@ -Security hardening for openstack-ansible +Security hardening for OpenStack-Ansible ---------------------------------------- -**--- Currently a work in progress ---** - Documentation for openstack-ansible-security is available in the `official OpenStack documentation site`_. .. _official OpenStack documentation site: http://docs.openstack.org/developer/openstack-ansible-security/ - -What is this? -~~~~~~~~~~~~~ - -The goal of this Ansible role is to provide additional security for deployments of openstack-ansible, the OpenStack project which deploys a fully-functional OpenStack environment using Ansible roles. For a more detailed explanation, review the security hardening spec in the section below. - -How do I learn more? -~~~~~~~~~~~~~~~~~~~~ - -* `openstack-ansible`_ -* `Security hardening spec`_ in openstack-ansible -* `RHEL 6 STIG`_ in `STIG Viewer`_ - -.. _openstack-ansible: https://github.com/openstack/openstack-ansible -.. _Security hardening spec: http://specs.openstack.org/openstack/openstack-ansible-specs/specs/mitaka/security-hardening.html -.. _RHEL 6 STIG: https://www.stigviewer.com/stig/red_hat_enterprise_linux_6/ -.. _STIG Viewer: https://www.stigviewer.com - -Questions or comments? -~~~~~~~~~~~~~~~~~~~~~~ - -Join ``#openstack-ansible`` on Freenode or email openstack-dev@lists.openstack.org with the tag ``[openstack-ansible]`` in the subject line. - -Where to report bugs? -~~~~~~~~~~~~~~~~~~~~~ - -The openstack-ansible-security role is a part of the `OpenStack Ansible project`_. Please report bugs on `Launchpad in the openstack-ansible project`_. - -.. _OpenStack Ansible project: http://governance.openstack.org/reference/projects/openstackansible.html -.. _Launchpad in the openstack-ansible project: https://launchpad.net/openstack-ansible diff --git a/doc/metadata/template_all.j2 b/doc/metadata/template_all.j2 index 43fbb7d4..acff15d9 100644 --- a/doc/metadata/template_all.j2 +++ b/doc/metadata/template_all.j2 @@ -13,7 +13,9 @@ ID numbers, such as ``V-38463``, or for particular topics, like ``audit``. ---- {% for stig_id in stig_ids | sort %} -.. include:: auto_{{ stig_id }}.rst +.. _stig-{{ stig_id }}: + +{% include "template_doc.j2" %} {% if not loop.last %} ---- diff --git a/doc/metadata/template_doc.j2 b/doc/metadata/template_doc.j2 index fd55cb88..ac98c285 100644 --- a/doc/metadata/template_doc.j2 +++ b/doc/metadata/template_doc.j2 @@ -1,3 +1,4 @@ +{% set rule = all_deployer_notes[stig_id] %} {% set page_title = rule['title'] | trim + ' (' + rule['id'] + ')'%} {{ page_title }} {{ "-" * page_title | length }} @@ -11,8 +12,5 @@ Details: `{{ rule['id'] }} in STIG Viewer`_ Notes for deployers and auditors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -**Implementation Status:** {{ notes['status'] | title }} - -{{ notes['content'] }} - - +**Implementation Status:** {{ rule['deployer_notes']['status'] | title }} +{{ rule['deployer_notes']['content'] }} diff --git a/doc/metadata/template_toc.j2 b/doc/metadata/template_toc.j2 index da546d51..3dac60fb 100644 --- a/doc/metadata/template_toc.j2 +++ b/doc/metadata/template_toc.j2 @@ -14,11 +14,14 @@ {% else %} {% set section_title = section_header | title + " (" + stig_id_list | length | string + " controls)" %} {% endif %} +.. _{{ toc_type | replace(' ', '-') }}-{{ section_header | replace(' ', '-') }}: + {{ section_title }} {{ "=" * section_title | length }} {% for stig_id in stig_id_list | sort %} -.. include:: auto_{{ stig_id }}.rst + +{% include "template_doc.j2" %} {% if not loop.last %} ---- diff --git a/doc/source/_exts/metadata-docs.py b/doc/source/_exts/metadata-docs.py index f51d859c..27a53447 100644 --- a/doc/source/_exts/metadata-docs.py +++ b/doc/source/_exts/metadata-docs.py @@ -105,11 +105,12 @@ def get_deployer_notes(stig_id): return post -def render_all(stig_ids): +def render_all(stig_ids, all_deployer_notes): """Generate documentation RST for each STIG configuration.""" template = JINJA_ENV.get_template('template_all.j2') return template.render( - stig_ids=stig_ids + stig_ids=stig_ids, + all_deployer_notes=all_deployer_notes, ) @@ -122,12 +123,13 @@ def render_doc(stig_rule, deployer_notes): ) -def render_toc(toc_type, stig_dict): +def render_toc(toc_type, stig_dict, all_deployer_notes): """Generate documentation RST for each STIG configuration.""" template = JINJA_ENV.get_template('template_toc.j2') return template.render( toc_type=toc_type, - stig_dict=stig_dict + stig_dict=stig_dict, + all_deployer_notes=all_deployer_notes, ) @@ -149,6 +151,7 @@ def generate_docs(): # Create defaultdicts to hold information to build our table of # contents files for sphinx. + all_deployer_notes = defaultdict(list) severity = defaultdict(list) tag = defaultdict(list) status = defaultdict(list) @@ -177,12 +180,9 @@ def generate_docs(): # Get the deployer notes from YAML deployer_notes = get_deployer_notes(rule['id']) + rule['deployer_notes'] = deployer_notes - # Render our documentation - doc_rst = render_doc(rule, deployer_notes) - all_filename = "auto_{0}.rst".format(rule['id']) - write_file(all_filename, doc_rst) - + all_deployer_notes[rule['id']] = rule stig_ids.append(rule['id']) severity[rule['severity']].append(rule['id']) status[deployer_notes['status']].append(rule['id']) @@ -194,10 +194,16 @@ def generate_docs(): status = OrderedDict(sorted(status.items(), key=lambda x: x[0])) tag = OrderedDict(sorted(tag.items(), key=lambda x: x[0])) - all_toc = render_all(stig_ids) - severity_toc = render_toc('severity', severity) - status_toc = render_toc('implementation status', status) - tag_toc = render_toc('tag', tag) + all_toc = render_all(stig_ids, all_deployer_notes) + severity_toc = render_toc('severity', + severity, + all_deployer_notes) + status_toc = render_toc('implementation status', + status, + all_deployer_notes) + tag_toc = render_toc('tag', + tag, + all_deployer_notes) write_file("auto_controls-all.rst", all_toc) write_file("auto_controls-by-severity.rst", severity_toc) diff --git a/doc/source/benefits.rst b/doc/source/benefits.rst index a40e9ba2..30aad28e 100644 --- a/doc/source/benefits.rst +++ b/doc/source/benefits.rst @@ -1,6 +1,3 @@ -.. include:: -`Home `__ |raquo| Security hardening for openstack-ansible - Security benefits FAQ ===================== diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst deleted file mode 100644 index f7ed9c54..00000000 --- a/doc/source/configuration.rst +++ /dev/null @@ -1,257 +0,0 @@ -.. include:: -`Home `__ |raquo| Security hardening for openstack-ansible - -Configuration -============= - -The openstack-ansible-security role is highly configurable and it ships with -reasonable defaults that provide a balance of enhanced security with limited -interruptions to production environments. However, some deployers may need to -adjust the default configurations to fit the particular needs of their -OpenStack environment. - -All of the default configurations are found within ``defaults/main.yml`` in the -role itself. - -.. note:: - - Deployers are strongly urged to test this role and any configuration - changes in a non-production, test environment. - -.. contents:: - :local: - :backlinks: none - -AIDE ----- - -The STIG sets requirements for integrity monitoring of the system and the role -will install AIDE to meet these requirements. However, Ubuntu's default -configuration will cause AIDE to search through container filesystems and this -will cause a serious performance hit to disk I/O for very long periods. - -By default, this role exludes some directories that cause AIDE to spend a very -long time indexing the disk. Additional directories can be added to the -exclusion list, but the directories currenty listed **should not be removed**. -Deployers can add directories to ``aide_exlude_dirs``. - -.. literalinclude:: ../../defaults/main.yml - :language: yaml - :start-after: ## AIDE - :end-before: # By default, the AIDE database won't be initialized - -The first AIDE database initialization can consume lots of CPU time and I/O -resources. By default, the role won't run the database initialization after -the role is applied to avoid causing performance degradation. The database will -be initialized automatically when the AIDE cron job runs the next day. To force -the initialization to run as soon as the role finishes running, change the -the following variable to ``true``: - -.. code-block:: yaml - - security_initialize_aide: true - -Audit daemon ------------- - -The `audit daemon`_ is required by the STIG and it provides useful logging of -critical events on a Linux server. - -.. _audit daemon: http://people.redhat.com/sgrubb/audit/ - -Rules for auditd -^^^^^^^^^^^^^^^^ - -The openstack-ansible-security role creates a file containing audit rules for -hosts. - -Each group of rules are 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``. - -For example, setting ``security_audit_filesystem_mounts`` 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 group of -rules on each host. - -To review the full list of rules and variables, refer to -``templates/osas-auditd.j2``. - -Other auditd configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -There are several configurations for auditd which are critical for deployers -to review in detail. The options beneath the ``## Auditd configuration`` -comment will change how auditd handles log files and what it should do in case -of emergencies. - -**NOTE:** 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 and -some cannot be met on Ubuntu systems due to the lack of certain packages. - -Deployers are urged to review each item under the ``## Authentication`` comment -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. - -fail2ban -^^^^^^^^ - -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 Ubuntu 14.04. - -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 V-38501 for more -details. - -Kernel ------- - -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 requitements 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. - -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 -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. - -Linux Security Module (LSM) ---------------------------- - -The STIG requires that SELinux is in enforcing mode to provide additional -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 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. - -Services and packages ---------------------- - -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. - -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 -``defaults/main.yml``. - -Special note about PermitRootLogin -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**NOTE:** There is one deviation from the STIG for the ``PermitRootLogin`` -configuration option. The STIG requires that direct root logins are disabled, -and this is the recommended setting for secure production environments. -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). - -Time synchronization with chrony --------------------------------- - -Reliable time synchronization is a requirement in the STIG and the ``chrony`` -package will be installed to handle NTP for systems secured with the -openstack-ansible-security role. - -The default settings will work for most environments, but some deployers may -prefer to use NTP servers which are geographically closer to their servers. - -The role configures the chrony daemon to listen only on localhost. To allow -chrony to listen on all addresses (the upstream default for chrony), -set the ``security_ntp_bind_local_interfaces_only`` variable to ``False``. - -The default configuration allows `RFC1918`_ addresses to reach the NTP server -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/doc/source/controls.rst b/doc/source/controls.rst index d2155513..04af6c02 100644 --- a/doc/source/controls.rst +++ b/doc/source/controls.rst @@ -1,6 +1,3 @@ -.. include:: -`Home `__ |raquo| Security hardening for OpenStack-Ansible - Security hardening controls in detail ===================================== diff --git a/doc/source/developer-guide.rst b/doc/source/developer-guide.rst index 6f94def2..20de2ea3 100644 --- a/doc/source/developer-guide.rst +++ b/doc/source/developer-guide.rst @@ -1,5 +1,6 @@ -.. include:: -`Home `__ |raquo| Security hardening for OpenStack-Ansible +.. contents:: + :local: + :backlinks: none Developer Guide =============== diff --git a/doc/source/getting-started.rst b/doc/source/getting-started.rst index 80e1f572..e20c0b96 100644 --- a/doc/source/getting-started.rst +++ b/doc/source/getting-started.rst @@ -1,6 +1,3 @@ -.. include:: -`Home `__ |raquo| Security hardening for OpenStack-Ansible - Getting started =============== @@ -10,55 +7,74 @@ with other Ansible playbooks. .. _OpenStack-Ansible: https://github.com/openstack/openstack-ansible/ +.. contents:: + :local: + :backlinks: none + +Prepare your system +------------------- + +Start by installing ansible and then install the role itself using +``ansible-galaxy``: + +.. code-block:: console + + pip install ansible + ansible-galaxy install git+https://github.com/openstack/openstack-ansible-security + +The role will be installed into +``/etc/ansible/roles/openstack-ansible-security``. + +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. + +Using as a standalone role +-------------------------- + +Adding the openstack-ansible-security role to existing playbooks is +straightforward. Here is an example of an existing role for deploying web +servers with the security hardening role added: + +.. code-block:: yaml + + --- + + - name: Deploy web servers + hosts: webservers + become: yes + roles: + - common + - webserver + - openstack-ansible-security + Using with OpenStack-Ansible ---------------------------- -Starting with the Mitaka release, OpenStack-Ansible installs the -openstack-ansible-security role automatically. It's disabled by default for -deployments and can be enabled with an Ansible variable: +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: .. code-block:: yaml apply_security_hardening: true -If the variable is set, the security hardening configurations will be applied -automatically on new builds that use the ``scripts/run_playbooks.sh`` script -provided with OpenStack-Ansible. However, the role can be applied anytime by -using the playbook provided with OpenStack-Ansible: - -.. code-block:: bash - - cd /opt/openstack-ansible/playbooks/ - openstack-ansible -e "apply_security_hardening=true" security-hardening.yml - For more information, refer to the OpenStack-Ansible documentation on `configuring security hardening`_. -.. _configuring security hardening: http://docs.openstack.org/developer/openstack-ansible/install-guide/configure-initial.html - -Using as a standalone role --------------------------- - -There are several options for using openstack-ansible-security as a standalone -role or along with another existing project. Here are two fairly easy methods: - -* Add openstack-ansible-security as a git submodule in the roles directory - of an existing Ansible project -* Clone the role into ``/etc/ansible/roles/`` on any system and write a custom - playbook and hosts inventory file - -The playbook for openstack-ansible-security can be fairly simple, depending -on the configuration of the systems: - -.. code-block:: yaml - - --- - - - name: Run openstack-ansible-security - hosts: webservers - user: root - roles: - - openstack-ansible-security - -This playbook will run the tasks in the openstack-ansible-security role against -all hosts in the ``webservers`` group (as defined in an inventory file). +.. _configuring security hardening: http://docs.openstack.org/developer/openstack-ansible/install-guide/app-advanced-config-security.html#security-hardening diff --git a/doc/source/index.rst b/doc/source/index.rst index f31165c0..8fa52a93 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -45,8 +45,8 @@ Newton release. The Newton release supports the following Linux distributions: :maxdepth: 2 benefits.rst - configuration.rst getting-started.rst + special-notes.rst controls.rst developer-guide.rst diff --git a/doc/source/special-notes.rst b/doc/source/special-notes.rst new file mode 100644 index 00000000..7f76fcee --- /dev/null +++ b/doc/source/special-notes.rst @@ -0,0 +1,266 @@ +Deviations & Special Notes +========================== + +The Security Technical Implementation Guide (STIG) provides over 200 controls +to secure a Linux system, but some of these configurations can cause problems +with production environments. + +.. contents:: + :local: + :backlinks: none + :depth: 2 + +Reviewing deviations +-------------------- + +The openstack-ansible-security role deviates from some of the STIG's +requirements when a security control could cause significant issues with +production systems. The role classifies each control into an implementation +status and provides notes on why a certain control is skipped or altered. + +The following provides a brief overview of each implementation status: + +Exception + If a control requires manual intervention outside the host, or if it could + cause significant harm to a host, it will be skipped and listed as an + exception. All controls in this category are not implemented in Ansible. + +Configuration Required + These controls require some type of initial configuration before they can + be applied. Review the notes for each control to determine how to configure + each of them. + +Implemented + These controls are fully implemented and they may have configurations which + can be adjusted. The notes for each control will identify which configuration + options are available. + +Opt-In + The controls in the opt-in list are implemented in Ansible, but are disabled + by default. They are often disabled because they could cause harm to a subset + of systems. Each control has notes that explains the caveats of the control + and how to enable it if needed. + +Deployers should review the full list of controls +`sorted by implementation status `_. + +.. note:: + + All of the default configurations are found within ``defaults/main.yml``. + +AIDE initialization +------------------- + +The STIG sets requirements for integrity monitoring of the system and the role +will install AIDE to meet these requirements. + +By default AIDE will examine and monitor all of the files on a host unless +directories are added to its exclusion list. The security role sets directories +to exclude from AIDE monitoring via the ``aide_exlude_dirs`` variable. this +list excludes the most common directories that change very often via automated +methods. + +Even with the excluded directories, the first AIDE initialization can take a +long time on some systems. During this time, the CPU and disks are **very +busy**. + +The security role will skip the AIDE initialization step by default. Deployers +must set the following Ansible variable to initialize the database: + +.. code-block:: yaml + + security_initialize_aide: true + +auditd +------ + +The audit daemon (``auditd``) is required by the STIG and it provides useful +logging of critical events on a Linux server. The audit daemon monitors +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``. + + For example, setting ``security_audit_filesystem_mounts`` 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 + group of rules on each host. + + To review the full list of rules and variables, refer to + ``templates/osas-auditd.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`` + comment will change how auditd handles log files and what it should do in + case of emergencies. + + .. note:: + + 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 requitements 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. + +Linux Security Modules (LSM) +---------------------------- + +The STIG requires that SELinux is in enforcing mode to provide additional +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. + +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 +``defaults/main.yml``. + +Deviation for PermitRootLogin + There is one deviation from the STIG for the ``PermitRootLogin`` + configuration option. The STIG requires that direct root logins are + disabled, and this is the recommended setting for secure production + environments. + + 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 +-------------------- + +Reliable time synchronization is a requirement in the STIG and the ``chrony`` +package will be installed to handle NTP for systems secured with the +openstack-ansible-security role. + +The default settings will work for most environments, but some deployers may +prefer to use NTP servers which are geographically closer to their servers. + +The role configures the chrony daemon to listen only on ``localhost``. To allow +chrony to listen on all addresses (the upstream default for chrony), +set the ``security_ntp_bind_local_interfaces_only`` variable to ``False``. + +The default configuration allows `RFC1918`_ addresses to reach the NTP server +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.