[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:
parent
236813cce5
commit
4cdf533565
18
README.md
18
README.md
@ -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
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
|
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
|
|
||||||
|
@ -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 %}
|
||||||
----
|
----
|
||||||
|
@ -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'] }}
|
|
||||||
|
|
||||||
|
|
||||||
|
@ -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 %}
|
||||||
----
|
----
|
||||||
|
@ -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)
|
||||||
|
@ -1,6 +1,3 @@
|
|||||||
.. include:: <xhtml1-lat1.txt>
|
|
||||||
`Home <index.html>`__ |raquo| Security hardening for openstack-ansible
|
|
||||||
|
|
||||||
Security benefits FAQ
|
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
|
Security hardening controls in detail
|
||||||
=====================================
|
=====================================
|
||||||
|
|
||||||
|
@ -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
|
||||||
===============
|
===============
|
||||||
|
@ -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/
|
||||||
|
|
||||||
|
.. 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
|
Using with OpenStack-Ansible
|
||||||
----------------------------
|
----------------------------
|
||||||
|
|
||||||
Starting with the Mitaka release, OpenStack-Ansible installs the
|
The openstack-ansible-security role is automatically enabled and applied in the
|
||||||
openstack-ansible-security role automatically. It's disabled by default for
|
Newton release of OpenStack-Ansible. In the Liberty and Mitaka releases, the
|
||||||
deployments and can be enabled with an Ansible variable:
|
role is easily enabled by adjusting the following Ansible variable:
|
||||||
|
|
||||||
.. code-block:: yaml
|
.. code-block:: yaml
|
||||||
|
|
||||||
apply_security_hardening: true
|
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
|
For more information, refer to the OpenStack-Ansible documentation on
|
||||||
`configuring security hardening`_.
|
`configuring security hardening`_.
|
||||||
|
|
||||||
.. _configuring security hardening: http://docs.openstack.org/developer/openstack-ansible/install-guide/configure-initial.html
|
.. _configuring security hardening: http://docs.openstack.org/developer/openstack-ansible/install-guide/app-advanced-config-security.html#security-hardening
|
||||||
|
|
||||||
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).
|
|
||||||
|
@ -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
266
doc/source/special-notes.rst
Normal 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.
|
Loading…
Reference in New Issue
Block a user