openstack/openstack-ansible-security
Code Issues Proposed changes

[Docs] More cleanup

Browse Source 
This patch cleans up various parts of the security role docs:

* Updates README files
* Uses jinja2 includes rather than sphinx includes (faster builds)
* Adds sphinx refs for each STIG control and implementation status
* Adds ToC's to pages that didn't have them
* Updated getting started and special notes guide
* Makes deviations more clear

Change-Id: I1eed2705c64a857bd94577dbe735f2516ca87732
This commit is contained in:
Major Hayden 2016-09-14 12:18:30 -05:00
parent 236813cce5
commit 4cdf533565
13 changed files with 375 additions and 366 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
README.md
View File

@ -1,13 +1,25 @@
openstack-ansible-security 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 Requirements
------------ ------------
This role can be used with or without the openstack-ansible role. It requires This role can be used with or without the OpenStack-Ansible role. It requires
Ansible 1.8.3 at a minimum. Ansible 1.9.1 or later.
Role Variables Role Variables
-------------- --------------

34
README.rst
View File

@ -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 Documentation for openstack-ansible-security is available in the `official
OpenStack documentation site`_. OpenStack documentation site`_.
.. _official OpenStack documentation site: http://docs.openstack.org/developer/openstack-ansible-security/ .. _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

4
doc/metadata/template_all.j2
View File

@ -13,7 +13,9 @@ ID numbers, such as ``V-38463``, or for particular topics, like ``audit``.
---- ----
{% for stig_id in stig_ids | sort %} {% for stig_id in stig_ids | sort %}
.. include:: auto_{{ stig_id }}.rst .. _stig-{{ stig_id }}:
{% include "template_doc.j2" %}
{% if not loop.last %} {% if not loop.last %}
---- ----

8
doc/metadata/template_doc.j2
View File

@ -1,3 +1,4 @@
{% set rule = all_deployer_notes[stig_id] %}
{% set page_title = rule['title'] | trim + ' (' + rule['id'] + ')'%} {% set page_title = rule['title'] | trim + ' (' + rule['id'] + ')'%}
{{ page_title }} {{ page_title }}
{{ "-" * page_title | length }} {{ "-" * page_title | length }}
@ -11,8 +12,5 @@ Details: `{{ rule['id'] }} in STIG Viewer`_
Notes for deployers and auditors Notes for deployers and auditors
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**Implementation Status:** {{ notes['status'] | title }} **Implementation Status:** {{ rule['deployer_notes']['status'] | title }}
{{ rule['deployer_notes']['content'] }}
{{ notes['content'] }}

5
doc/metadata/template_toc.j2
View File

@ -14,11 +14,14 @@
{% else %} {% else %}
{% set section_title = section_header | title + " (" + stig_id_list | length | string + " controls)" %} {% set section_title = section_header | title + " (" + stig_id_list | length | string + " controls)" %}
{% endif %} {% endif %}
.. _{{ toc_type | replace(' ', '-') }}-{{ section_header | replace(' ', '-') }}:
{{ section_title }} {{ section_title }}
{{ "=" * section_title | length }} {{ "=" * section_title | length }}
{% for stig_id in stig_id_list | sort %} {% for stig_id in stig_id_list | sort %}
.. include:: auto_{{ stig_id }}.rst
{% include "template_doc.j2" %}
{% if not loop.last %} {% if not loop.last %}
---- ----

32
doc/source/_exts/metadata-docs.py
View File

@ -105,11 +105,12 @@ def get_deployer_notes(stig_id):
return post return post
def render_all(stig_ids): def render_all(stig_ids, all_deployer_notes):
"""Generate documentation RST for each STIG configuration.""" """Generate documentation RST for each STIG configuration."""
template = JINJA_ENV.get_template('template_all.j2') template = JINJA_ENV.get_template('template_all.j2')
return template.render( 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.""" """Generate documentation RST for each STIG configuration."""
template = JINJA_ENV.get_template('template_toc.j2') template = JINJA_ENV.get_template('template_toc.j2')
return template.render( return template.render(
toc_type=toc_type, 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 # Create defaultdicts to hold information to build our table of
# contents files for sphinx. # contents files for sphinx.
all_deployer_notes = defaultdict(list)
severity = defaultdict(list) severity = defaultdict(list)
tag = defaultdict(list) tag = defaultdict(list)
status = defaultdict(list) status = defaultdict(list)
@ -177,12 +180,9 @@ def generate_docs():
# Get the deployer notes from YAML # Get the deployer notes from YAML
deployer_notes = get_deployer_notes(rule['id']) deployer_notes = get_deployer_notes(rule['id'])
rule['deployer_notes'] = deployer_notes
# Render our documentation all_deployer_notes[rule['id']] = rule
doc_rst = render_doc(rule, deployer_notes)
all_filename = "auto_{0}.rst".format(rule['id'])
write_file(all_filename, doc_rst)
stig_ids.append(rule['id']) stig_ids.append(rule['id'])
severity[rule['severity']].append(rule['id']) severity[rule['severity']].append(rule['id'])
status[deployer_notes['status']].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])) status = OrderedDict(sorted(status.items(), key=lambda x: x[0]))
tag = OrderedDict(sorted(tag.items(), key=lambda x: x[0])) tag = OrderedDict(sorted(tag.items(), key=lambda x: x[0]))
all_toc = render_all(stig_ids) all_toc = render_all(stig_ids, all_deployer_notes)
severity_toc = render_toc('severity', severity) severity_toc = render_toc('severity',
status_toc = render_toc('implementation status', status) severity,
tag_toc = render_toc('tag', tag) 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-all.rst", all_toc)
write_file("auto_controls-by-severity.rst", severity_toc) write_file("auto_controls-by-severity.rst", severity_toc)

3
doc/source/benefits.rst
View File

@ -1,6 +1,3 @@
.. include:: <xhtml1-lat1.txt>
`Home <index.html>`__ |raquo| Security hardening for openstack-ansible
Security benefits FAQ Security benefits FAQ
===================== =====================

257
doc/source/configuration.rst
View File

@ -1,257 +0,0 @@
.. include:: <xhtml1-lat1.txt>
`Home <index.html>`__ |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.

3
doc/source/controls.rst
View File

@ -1,6 +1,3 @@
.. include:: <xhtml1-lat1.txt>
`Home <index.html>`__ |raquo| Security hardening for OpenStack-Ansible
Security hardening controls in detail Security hardening controls in detail
===================================== =====================================

5
doc/source/developer-guide.rst
View File

@ -1,5 +1,6 @@
.. include:: <xhtml1-lat1.txt> .. contents::
`Home <index.html>`__ |raquo| Security hardening for OpenStack-Ansible :local:
:backlinks: none
Developer Guide Developer Guide
=============== ===============

84
doc/source/getting-started.rst
View File

@ -1,6 +1,3 @@
.. include:: <xhtml1-lat1.txt>
`Home <index.html>`__ |raquo| Security hardening for OpenStack-Ansible
Getting started Getting started
=============== ===============
@ -10,55 +7,74 @@ with other Ansible playbooks.
.. _OpenStack-Ansible: https://github.com/openstack/openstack-ansible/ .. _OpenStack-Ansible: https://github.com/openstack/openstack-ansible/
Using with OpenStack-Ansible .. contents::
---------------------------- :local:
:backlinks: none
Starting with the Mitaka release, OpenStack-Ansible installs the Prepare your system
openstack-ansible-security role automatically. It's disabled by default for -------------------
deployments and can be enabled with an Ansible variable:
.. code-block:: yaml Start by installing ansible and then install the role itself using
``ansible-galaxy``:
apply_security_hardening: true .. code-block:: console
If the variable is set, the security hardening configurations will be applied pip install ansible
automatically on new builds that use the ``scripts/run_playbooks.sh`` script ansible-galaxy install git+https://github.com/openstack/openstack-ansible-security
provided with OpenStack-Ansible. However, the role can be applied anytime by
using the playbook provided with OpenStack-Ansible:
.. code-block:: bash The role will be installed into
``/etc/ansible/roles/openstack-ansible-security``.
cd /opt/openstack-ansible/playbooks/ Initial configuration
openstack-ansible -e "apply_security_hardening=true" security-hardening.yml ---------------------
For more information, refer to the OpenStack-Ansible documentation on Some of the security configurations need initial configuration or they may
`configuring security hardening`_. require you to opt-in for a change to be applied. Start by reviewing the list
of STIG controls that
:ref:`require initial configuration <implementation-status-configuration-required>`
or :ref:`require opt-in <implementation-status-opt-in>`.
.. _configuring security hardening: http://docs.openstack.org/developer/openstack-ansible/install-guide/configure-initial.html An example of a STIG requiring initial configuration is
:ref:`V-38446 <stig-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 <stig-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 Using as a standalone role
-------------------------- --------------------------
There are several options for using openstack-ansible-security as a standalone Adding the openstack-ansible-security role to existing playbooks is
role or along with another existing project. Here are two fairly easy methods: straightforward. Here is an example of an existing role for deploying web
servers with the security hardening role added:
* 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 .. code-block:: yaml
--- ---
- name: Run openstack-ansible-security - name: Deploy web servers
hosts: webservers hosts: webservers
user: root become: yes
roles: roles:
- common
- webserver
- openstack-ansible-security - openstack-ansible-security
This playbook will run the tasks in the openstack-ansible-security role against Using with OpenStack-Ansible
all hosts in the ``webservers`` group (as defined in an inventory file). ----------------------------
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
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/app-advanced-config-security.html#security-hardening

2
doc/source/index.rst
View File

@ -45,8 +45,8 @@ Newton release. The Newton release supports the following Linux distributions:
:maxdepth: 2 :maxdepth: 2
benefits.rst benefits.rst
configuration.rst
getting-started.rst getting-started.rst
special-notes.rst
controls.rst controls.rst
developer-guide.rst developer-guide.rst

266
doc/source/special-notes.rst Normal file
View File

@ -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 <auto_controls-by-status.html>`_.
.. 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 <stig-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 <stig-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 <stig-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.