[Docs] More cleanup
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
parent
236813cce5
commit
4cdf533565
18
README.md
18
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
|
||||
--------------
|
||||
|
|
|
|||
34
README.rst
34
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
|
||||
|
|
|
|||
|
|
@ -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 %}
|
||||
----
|
||||
|
|
|
|||
|
|
@ -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'] }}
|
||||
|
|
|
|||
|
|
@ -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 %}
|
||||
----
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -1,6 +1,3 @@
|
|||
.. include:: <xhtml1-lat1.txt>
|
||||
`Home <index.html>`__ |raquo| Security hardening for openstack-ansible
|
||||
|
||||
Security benefits FAQ
|
||||
=====================
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -1,6 +1,3 @@
|
|||
.. include:: <xhtml1-lat1.txt>
|
||||
`Home <index.html>`__ |raquo| Security hardening for OpenStack-Ansible
|
||||
|
||||
Security hardening controls in detail
|
||||
=====================================
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
.. include:: <xhtml1-lat1.txt>
|
||||
`Home <index.html>`__ |raquo| Security hardening for OpenStack-Ansible
|
||||
.. contents::
|
||||
:local:
|
||||
:backlinks: none
|
||||
|
||||
Developer Guide
|
||||
===============
|
||||
|
|
|
|||
|
|
@ -1,6 +1,3 @@
|
|||
.. include:: <xhtml1-lat1.txt>
|
||||
`Home <index.html>`__ |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 <implementation-status-configuration-required>`
|
||||
or :ref:`require opt-in <implementation-status-opt-in>`.
|
||||
|
||||
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
|
||||
--------------------------
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue