diff --git a/doc/Makefile b/doc/Makefile index 28a679f2..3029a432 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -2,8 +2,8 @@ # # You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build +SPHINXOPTS = "-p 8001" +SPHINXBUILD = sphinx-autobuild PAPER = BUILDDIR = build diff --git a/doc/source/benefits.rst b/doc/source/benefits.rst new file mode 100644 index 00000000..d2cc582a --- /dev/null +++ b/doc/source/benefits.rst @@ -0,0 +1,34 @@ +.. include:: +`Home `__ |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. diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst new file mode 100644 index 00000000..cfe0ed25 --- /dev/null +++ b/doc/source/configuration.rst @@ -0,0 +1,213 @@ +.. include:: +`Home `__ |raquo| Security hardening for openstack-ansible + +Configuration +============= + +The openstack-ansible-security role is highly configurable and it ships with +reasonable defaults that provide a balance of enhanced security with limited +interruptions to production environments. However, some deployers may need to +adjust the default configurations to fit the particular needs of their +OpenStack environment. + +All of the default configurations are found within ``defaults/main.yml`` in the +role itself. + +*NOTE: Deployers are strongly urged to test this role and any configuration +changes in a non-production, test environment.* + +.. contents:: + :local: + +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. diff --git a/doc/source/configurations-cat1.rst b/doc/source/controls-cat1.rst similarity index 99% rename from doc/source/configurations-cat1.rst rename to doc/source/controls-cat1.rst index 6dd68c01..4e1f0650 100644 --- a/doc/source/configurations-cat1.rst +++ b/doc/source/controls-cat1.rst @@ -1,7 +1,7 @@ .. include:: `Home `__ |raquo| Security hardening for openstack-ansible -Category 1 (Low) configurations +Category 1 (Low) controls ================================ .. toctree:: diff --git a/doc/source/configurations-cat2.rst b/doc/source/controls-cat2.rst similarity index 99% rename from doc/source/configurations-cat2.rst rename to doc/source/controls-cat2.rst index 3234c005..3fcd0d99 100644 --- a/doc/source/configurations-cat2.rst +++ b/doc/source/controls-cat2.rst @@ -1,7 +1,7 @@ .. include:: `Home `__ |raquo| Security hardening for openstack-ansible -Category 2 (Medium) configurations +Category 2 (Medium) controls ================================ .. toctree:: diff --git a/doc/source/configurations-cat3.rst b/doc/source/controls-cat3.rst similarity index 96% rename from doc/source/configurations-cat3.rst rename to doc/source/controls-cat3.rst index 2d8f2120..2107aef3 100644 --- a/doc/source/configurations-cat3.rst +++ b/doc/source/controls-cat3.rst @@ -1,7 +1,7 @@ .. include:: `Home `__ |raquo| Security hardening for openstack-ansible -Category 3 (High) configurations +Category 3 (High) controls ================================ .. toctree:: diff --git a/doc/source/configurations.rst b/doc/source/controls.rst similarity index 59% rename from doc/source/configurations.rst rename to doc/source/controls.rst index 74829fc8..14ea9f00 100644 --- a/doc/source/configurations.rst +++ b/doc/source/controls.rst @@ -1,12 +1,12 @@ .. include:: `Home `__ |raquo| Security hardening for openstack-ansible -Security hardening configurations +Security hardening controls in detail ================================= .. toctree:: :maxdepth: 2 - configurations-cat3.rst - configurations-cat2.rst - configurations-cat1.rst + controls-cat1.rst + controls-cat2.rst + controls-cat3.rst diff --git a/doc/source/generate_docs.py b/doc/source/generate_docs.py index 03dad8dc..e0fe02bd 100644 --- a/doc/source/generate_docs.py +++ b/doc/source/generate_docs.py @@ -68,7 +68,7 @@ with open('rhel6stig.csv', 'r') as csvfile: category_template = """.. include:: `Home `__ |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)) diff --git a/doc/source/index.rst b/doc/source/index.rst index 94d168c8..750621dc 100644 --- a/doc/source/index.rst +++ b/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 diff --git a/doc/source/writing-docs.rst b/doc/source/writing-docs.rst index 8a828024..91c2ad96 100644 --- a/doc/source/writing-docs.rst +++ b/doc/source/writing-docs.rst @@ -1,11 +1,11 @@ .. include:: `Home `__ |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 -``stigcsv-to-rst.py`` script and the ``rhel6stig.csv``. +The ``controls-cat[number].rst`` files are automatically generated with the +``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