Adding benefits faq + config docs

Implements: blueprint security-hardening

Change-Id: I72fd97ff1cdee96d87ad195828e723aad33934d1

doc/Makefile

@@ -2,8 +2,8 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = "-p 8001"
-SPHINXBUILD   = sphinx-build
+SPHINXBUILD   = sphinx-autobuild
 PAPER         =
 BUILDDIR      = build
 

doc/source/benefits.rst

@@ -0,0 +1,34 @@
+.. include:: <xhtml1-lat1.txt>
+`Home <index.html>`__ |raquo| Security hardening for openstack-ansible
+
+Security benefits FAQ
+=====================
+
+The openstack-ansible-security role provides hardened security configurations
+for the host operating system as well as many common system services.
+
+Why should this role be applied to a system?
+--------------------------------------------
+
+First and foremost, this role should be applied to production systems in
+environments where security is a priority.  If an OpenStack environment is
+exposed to the internet or to large internal corporate networks, applying
+this role will reduce the risk of compromised OpenStack infrastructure. The
+changes made by the role should also reduce the impact of potential
+compromises as well.
+
+Some deployers may be subject to industry compliance programs, such as
+PCI-DSS, ISO 27001/27002, or NIST 800-53.  Many of these programs require
+hardening standards to be applied to critical systems, such as OpenStack
+infrastructure components.
+
+What systems are covered by openstack-ansible-security?
+-------------------------------------------------------
+
+At this time, the openstack-ansible-security role provides security hardening
+for physical servers running Ubuntu 14.04.  The containers that run various
+OpenStack services on these physical servers are currently out of scope.
+
+Virtual machines that are created within the OpenStack environment are also
+not affected by this role, although this role could be applied within those
+VM's if a deployer chooses to do so.

doc/source/configuration.rst

@@ -0,0 +1,213 @@
+.. 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:
+
+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``.
+
+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 creates a file full of audit rules for hosts
+and these rules can be configured via the ``auditd_rules`` dictionary in
+``defaults/main.yml``.
+
+Each key within the dictionary refers to a block of rules that perform a
+certain function.  Setting a value of ``yes`` for these keys will ensure that
+the rules are present in the final auditd configuration file.  Setting a value
+of ``no`` will ensure that they are omitted.
+
+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 ``install_fail2ban`` to
+``yes`` and set an appropriate time for bans with ``fail2ban_bantime``.  See
+the notes for V-38501 for more details.
+
+Kernel
+------
+
+Kernel modules
+^^^^^^^^^^^^^^
+
+Certain kernel modules are restricted by the STIG and those are reflected in
+the ``disable_module`` dictionary within ``defaults/main.yml``.  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 SYNcookes are 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 ``disable_ipv6`` to ``yes``.
+
+Core dumps are also disabled by default in the openstack-ansible-security role.
+
+Mail
+----
+
+Deployers are strongly urged to configure an address to receive the ``root``
+user's email on various hosts.  This is done with the ``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.  The list of these services can be found within the
+``disable_services`` dictionary in ``defaults/main.yml``.
+
+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 services are found within the ``remove_services``
+dictionary within ``defaults/main.yml``.
+
+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.
+Also, the default configuration allows `RFC1918`_ addresses to reach the NTP
+server running on each host. That could be reduced to ``127.0.0.1/32`` for
+greater security.
+
+.. _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 ``umask_*``.  There is extensive documentation available within
+the developer notes for each STIG requirement.

doc/source/controls-cat1.rst

@@ -1,7 +1,7 @@
 .. include:: <xhtml1-lat1.txt>
 `Home <index.html>`__ |raquo| Security hardening for openstack-ansible
 
-Category 1 (Low) configurations
+Category 1 (Low) controls
 ================================
 
 .. toctree::

doc/source/controls-cat2.rst

@@ -1,7 +1,7 @@
 .. include:: <xhtml1-lat1.txt>
 `Home <index.html>`__ |raquo| Security hardening for openstack-ansible
 
-Category 2 (Medium) configurations
+Category 2 (Medium) controls
 ================================
 
 .. toctree::

doc/source/controls-cat3.rst

@@ -1,7 +1,7 @@
 .. include:: <xhtml1-lat1.txt>
 `Home <index.html>`__ |raquo| Security hardening for openstack-ansible
 
-Category 3 (High) configurations
+Category 3 (High) controls
 ================================
 
 .. toctree::

doc/source/controls.rst

@@ -1,12 +1,12 @@
 .. include:: <xhtml1-lat1.txt>
 `Home <index.html>`__ |raquo| Security hardening for openstack-ansible
 
-Security hardening configurations
+Security hardening controls in detail
 =================================
 
 .. toctree::
    :maxdepth: 2
 
-   configurations-cat3.rst
+   controls-cat1.rst
-   configurations-cat2.rst
+   controls-cat2.rst
-   configurations-cat1.rst
+   controls-cat3.rst

doc/source/generate_docs.py

@@ -68,7 +68,7 @@ with open('rhel6stig.csv', 'r') as csvfile:
 category_template = """.. include:: <xhtml1-lat1.txt>
 `Home <index.html>`__ |raquo| Security hardening for openstack-ansible
 
-Category {{ level }} ({{ name | capitalize }}) configurations
+Category {{ level }} ({{ name | capitalize }}) controls
 ================================
 
 .. toctree::
@@ -86,7 +86,7 @@ categories = {
 
 for category_name, category_level in categories.items():
     matching_stigs = [x for x in stigs if x['severity'] == category_name]
-    cat_file = open("configurations-cat{0}.rst".format(category_level), 'w')
+    cat_file = open("controls-cat{0}.rst".format(category_level), 'w')
     template = Template(category_template)
     cat_file.write(template.render(name=category_name,
                                    level=category_level))

doc/source/index.rst

@@ -35,6 +35,8 @@ Table of Contents
 .. toctree::
    :maxdepth: 2
 
+   benefits.rst
+   configuration.rst
    getting-started.rst
    writing-docs.rst
-   configurations.rst
+   controls.rst

doc/source/writing-docs.rst

@@ -1,11 +1,11 @@
 .. include:: <xhtml1-lat1.txt>
 `Home <index.html>`__ |raquo| Security hardening for openstack-ansible
 
-Writing docs for openstack-ansible-security
+Writing documentation
-===========================================
+=====================
 
-The configurations-cat[number].rst files are automatically generated with the
+The ``controls-cat[number].rst`` files are automatically generated with the
-``stigcsv-to-rst.py`` script and the ``rhel6stig.csv``.
+``generate_docs.py`` script and the ``rhel6stig.csv``.
 
 Each hardening configuration does an import from the developer-notes directory
 and looks for a file called ``[STIG_ID].rst``.  As an example, the