diff --git a/docs/source/audit.rst b/docs/source/audit.rst new file mode 100644 index 0000000..51730be --- /dev/null +++ b/docs/source/audit.rst @@ -0,0 +1,6 @@ +Welcome to the documentation for the audit component +#################################################### + +.. toctree:: + getting_started.rst + faqs.rst diff --git a/docs/source/audit/faq.rst b/docs/source/audit/faq.rst new file mode 100644 index 0000000..9de8d17 --- /dev/null +++ b/docs/source/audit/faq.rst @@ -0,0 +1,69 @@ +FAQ +=== + +Does this role work only with |benchmark_os_short|? +----------------------------------------------------- + +No -- it works on multiple distributions! + +The |benchmark_name| guidance is designed to ONLY be applicable to |benchmark os| +systems and if you are using this role in a regulated organization you should be aware +that applying these settings to distributions other than listed is unsupported +and may run afoul of your organization or regulatory bodies guidelines during a compliance +audit. It is on YOU to understand your organizations requirements and the laws and regulations +you must adhere to before applying this role. + +See :ref:`system_applicability_ref_label` below for more details on applying this role to non-RedHat EL 7 +or CentOS 7 systems. + +Why should this role be applied to a system? +-------------------------------------------- + +There are three main reasons to apply this role to production Linux systems: + +Improve security posture + The configurations from the |benchmark_name| add security and rigor around multiple + components of a Linux system, including user authentication, service + configurations, and package management. All of these configurations add up + to an environment that is more difficult for an attacker to penetrate and use + for lateral movement. + +Meet compliance requirements + 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 systems. + +Deployment without disruption + Security is often at odds with usability. The role provides the greatest + security benefit without disrupting production systems. Deployers have the + option to opt out or opt in for most configurations depending on how their + environments are configured. + +.. _system_applicability_ref_label: + +Which systems are covered? +-------------------------------------------------------- + +This role and the |benchmark_name| guidance it implements are fully applicable to servers +(physical or virtual) and containers running the following Linux distributions: + +* |benchmark_os| + + + +The role is tested against each distribution to ensure that tasks run properly. +it is idempotent, and an Audit is used to run a compliance scan after the role +is applied to test compliance with the STIG standard. + +Which systems are not covered? +------------------------------ + +This role will run properly against a container (docker or other), however +this is not recommended and is only really useful during the development and +testing of this role (ie most CI systems provide containers and not full VMs), +so this role must be able to run on and test against containers. + +Again for those in the back...applying this role against a container +in order to secure it is generally a *BAD* idea. You should be applying this +role to your container hosts and then using other hardening guidance that is +specific to the container technology you are using (docker, lxc, lxd, etc) diff --git a/docs/source/getting-started.rst b/docs/source/audit/getting-started.rst similarity index 94% rename from docs/source/getting-started.rst rename to docs/source/audit/getting-started.rst index 4e90384..4e40829 100644 --- a/docs/source/getting-started.rst +++ b/docs/source/audit/getting-started.rst @@ -13,9 +13,12 @@ standalone role or it can be used along with other Ansible roles and playbooks. Requirements ------------ This documentation assumes that the reader has completed the steps within the -`Ansible installation guide `_. + +* `Ansible installation guide `_. + and has a good understanding of using ansible -`Ansible User Guide `_. + +* `Ansible User Guide `_. Installation @@ -31,6 +34,7 @@ The easiest installation method is to use the ``ansible-galaxy`` command that is provided with your Ansible installation: .. code-block:: console + ansible-galaxy install git+|lockdown_url| diff --git a/docs/source/benchmarks.rst b/docs/source/benchmarks.rst new file mode 100644 index 0000000..cced9ee --- /dev/null +++ b/docs/source/benchmarks.rst @@ -0,0 +1,55 @@ +**Operating Systems** + +- CIS + - Amazon + - 2 + - RedHat Enterprise Linux + - 6 (no longer maintained) + - 7 + - 8 + - 9 (WIP) + - Ubuntu + - 18.04 + - 20.04 + - Windows + - 2016 + - 2019 + - 2022 + +- STIG + - RedHat Enterprise Linux + - 7 + - 8 + - Windows + - 10 + - 2012-Member + - 2012-DomanController + - 2016 + - 2019 + +**Hardware** + +- STIG + - Cisco-IOS-L2S + +**Platform** +- CIS + - AWS-Foundations + - Azure + +**Applications** + +- CIS + - Apache 2.4 (Linux) + - Postgres 12 (Linux) + - Kubernetes 1.6.1 (Linux) + +- STIG + - Apache 2.4 (Linux) + - Postgres 9 (Linux) + +**Archived(No Longer Maintained)** +- STIG + - RHEL5 + - RHEL6 + - 2008R2-Member diff --git a/docs/source/index.rst b/docs/source/index.rst index 991a1c1..30bf788 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,69 +2,72 @@ Automated security hardening for Linux hosts with Ansible ========================================================= -.. image:: https://secure.travis-ci.org/MindPointGroup/RHEL7-STIG.svg?branch=devel - :alt: Build Status Badge - :target: https://travis-ci.org/MindPointGroup/RHEL7-STIG +What is security hardening? +--------------------------- -.. raw:: html +The content delivered is based upon either one of the two major contributors to the security best practices in the IT industry. -

+- Center for Internet Security (CIS): https://www.cisecurity.org/cis-benchmarks/ + - A global IT community of experts helping to build, document sets of benchmarks to produce industry best security practices -What does the role do? +or + +- Security Technical Implementation Guide (STIG): https://public.cyber.mil/stigs/downloads/ + - From the Defense Information Systems Agency (DISA) + - The STIG is released with a public domain license and it is commonly used to secure systems at public and private organizations around the world. + +Both are well known and respected benchmarks created for the industry to assist in achieving recognised compliance (e.g. PCI DSS, HIPAA, SOC2, NIST) and adopting security best practices. + + +What is provided? +----------------- + +The content provided is open source licensed configurations to assist in achieving or auditing compliance to one of the benchmark providers listed above. + +This consists of two components + +- Audit +- Remediate + +Both can be run alone or inconjunction with each other. + +What do the roles do? ---------------------- -This role uses the |benchmark_name| `Security Technical Implementation Guide (STIG)`_ guidance -from the `Defense Information Systems Agency (DISA)`_. The STIG is released with a -public domain license and it is commonly used to secure systems at public and private -organizations around the world. -We analyze each configuration hardening item from the applicable STIG benchmark -to determine what impact it has on a live production environment and how to -best implement it using Ansible. Tasks are added to the role that configure a host -to meet the configuration requirements. Each task is documented to explain what was -changed, why it was changed, and what deployers need to understand about the change. +- Audit + - runs a small single binary on the system written in go called goss: http://goss.rocks + - enables you to very quickly scan your host and output the status of compliance for your host. -Deployers have the option to enable/disable STIG items that do not suit their environments -needs. Each STIG item has an associated variable that can be used to switch it on or off. -Additionally, the items that have configurable values, i.e. number of password attempts, will -generally have a corresponding variable that allows for customization of the applied value. -It is imperative for each deployer to understand the regulations and compliance requirements -that their organization and specific environments are responsible for meeting in order to -effeectively implement the controls in the |benchmark_name_short| STIG. +- Remediate + - Ability to run from a central location using the configuration management tool ansible + - Assists in bringing your host into compliance for the relevant benchmark + + +How do we do this? +------------------ + +We analyze each configuration control from the applicable benchmark to determine what impact it has on a live production environment and how to +best implement a way to audit the current configuration and how to achieve those requirements using Ansible. +Tasks are added to the role that configure a host to meet the configuration requirements. Each task is documented to explain what was changed, why it was changed, and what deployers need to understand about the change. + +Deployers have the option to enable/disable every control that does not suit their environments needs. +Every control item has an associated variable that can be used to switch it on or off. + +Additionally, the items that have configurable values, i.e. number of password attempts, will generally have a corresponding variable that allows for customization of the applied value. +It is imperative for each deployer to understand the regulations and compliance requirements that their organization and specific environments are responsible for meeting in order to effeectively implement the controls in the relevant benchmark. -.. _Security Technical Implementation Guide (STIG): http://iase.disa.mil/stigs/os/unix-linux/Pages/red-hat.aspx -.. _Defense Information Systems Agency (DISA): http://www.disa.mil/ Documentation ------------- -The following documentation applies to the devel branch and is currently under -active development. Documentation for the latest stable and previous stable -releases will be generated and available once the first stable release is cut. +Documentation is split in the two categories .. toctree:: :maxdepth: 2 + audit + remediate - getting-started.rst - customization.rst - controls.rst - controls-contrib.rst - developer-guide.rst - faq.rst - -Releases --------- - -devel -~~~~~~ - -* **Status:** Active development - -* **STIG Version:** - |benchmark_name_short| |stig_version| *(Published on* |stig_release_date| *)* - -* **Supported Operating Systems:** - - * Red Hat Enterprise Linux 7 - * CentOS 7 - +Content list +------------ +.. code-block: txt + .. include:: benchmarks.rst diff --git a/docs/source/remediate.rst b/docs/source/remediate.rst new file mode 100644 index 0000000..fca3f36 --- /dev/null +++ b/docs/source/remediate.rst @@ -0,0 +1,6 @@ +Welcome to the documentation for the remediate component +######################################################## + +.. toctree:: + getting_started.rst + faqs.rst diff --git a/docs/source/remediate/faq.rst b/docs/source/remediate/faq.rst new file mode 100644 index 0000000..9de8d17 --- /dev/null +++ b/docs/source/remediate/faq.rst @@ -0,0 +1,69 @@ +FAQ +=== + +Does this role work only with |benchmark_os_short|? +----------------------------------------------------- + +No -- it works on multiple distributions! + +The |benchmark_name| guidance is designed to ONLY be applicable to |benchmark os| +systems and if you are using this role in a regulated organization you should be aware +that applying these settings to distributions other than listed is unsupported +and may run afoul of your organization or regulatory bodies guidelines during a compliance +audit. It is on YOU to understand your organizations requirements and the laws and regulations +you must adhere to before applying this role. + +See :ref:`system_applicability_ref_label` below for more details on applying this role to non-RedHat EL 7 +or CentOS 7 systems. + +Why should this role be applied to a system? +-------------------------------------------- + +There are three main reasons to apply this role to production Linux systems: + +Improve security posture + The configurations from the |benchmark_name| add security and rigor around multiple + components of a Linux system, including user authentication, service + configurations, and package management. All of these configurations add up + to an environment that is more difficult for an attacker to penetrate and use + for lateral movement. + +Meet compliance requirements + 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 systems. + +Deployment without disruption + Security is often at odds with usability. The role provides the greatest + security benefit without disrupting production systems. Deployers have the + option to opt out or opt in for most configurations depending on how their + environments are configured. + +.. _system_applicability_ref_label: + +Which systems are covered? +-------------------------------------------------------- + +This role and the |benchmark_name| guidance it implements are fully applicable to servers +(physical or virtual) and containers running the following Linux distributions: + +* |benchmark_os| + + + +The role is tested against each distribution to ensure that tasks run properly. +it is idempotent, and an Audit is used to run a compliance scan after the role +is applied to test compliance with the STIG standard. + +Which systems are not covered? +------------------------------ + +This role will run properly against a container (docker or other), however +this is not recommended and is only really useful during the development and +testing of this role (ie most CI systems provide containers and not full VMs), +so this role must be able to run on and test against containers. + +Again for those in the back...applying this role against a container +in order to secure it is generally a *BAD* idea. You should be applying this +role to your container hosts and then using other hardening guidance that is +specific to the container technology you are using (docker, lxc, lxd, etc) diff --git a/docs/source/remediate/getting-started.rst b/docs/source/remediate/getting-started.rst new file mode 100644 index 0000000..4e40829 --- /dev/null +++ b/docs/source/remediate/getting-started.rst @@ -0,0 +1,106 @@ +Getting started +=============== + +This role is part of the `Ansible Lockdown`_ project and can be used as a +standalone role or it can be used along with other Ansible roles and playbooks. + +.. _Ansible Lockdown: https://github.com/ansible-lockdown + +.. contents:: + :local: + :backlinks: none + +Requirements +------------ +This documentation assumes that the reader has completed the steps within the + +* `Ansible installation guide `_. + +and has a good understanding of using ansible + +* `Ansible User Guide `_. + + +Installation +------------------------------------- + +The recommended installation methods for this role are +``ansible-galaxy`` (recommended) or ``git``. + +Using ``ansible-galaxy`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +The easiest installation method is to use the ``ansible-galaxy`` command that +is provided with your Ansible installation: + +.. code-block:: console + + + ansible-galaxy install git+|lockdown_url| + +The ``ansible-galaxy`` command will install the role into +``/etc/ansible/roles/`` and this makes it easy to use with +Ansible playbooks. + +Using ``git`` +~~~~~~~~~~~~~ + +Start by cloning the role into a directory of your choice: + +.. code-block:: console + + mkdir -p ~/.ansible/roles/ + git clone |lockdown_url| ~/.ansible/roles/|benchmark_os_short|-|benchmark_name| + + +Ansible looks for roles in ``~/.ansible/roles`` by default. + +If the role is cloned into a different directory, that directory must be +provided with the ``roles_path`` option in ``ansible.cfg``. The following is +an example of a ``ansible.cfg`` file that uses a custom path for roles: + +.. code-block:: ini + + [DEFAULTS] + roles_path = /etc/ansible/roles:/home/myuser/custom/roles + +With this configuration, Ansible looks for roles in ``/etc/ansible/roles`` and +``~/custom/roles``. + +Usage +----- + +This role works well with existing playbooks. The following is an +example of a basic playbook that uses this role: + +.. ansible-playbook:: + + --- + + - hosts: servers + become: yes + roles: + - role: |benchmark_os_short|-|benchmark_name| + when: + - ansible_os_family == 'RedHat' + - ansible_distribution_major_version | version_compare('7', '=') + +The role is fully customizable by setting the variables provided in the ``defaults/main.yml``. +These variables are designed so that categories/severities or individual rules can be enabled, +disabled, or can alter configuration for various items in the role. For more details +on the available variables, refer to the :ref:`controls_label` +section. + +.. note:: + + The role requires elevated privileges and must be run as a user with ``sudo`` + access. The example above uses the ``become`` option, which causes Ansible to use + sudo before running tasks. + +.. warning:: + + It is strongly recommended to run the role in check mode (often called a + `dry run`) first before making any modifications. This gives the deployer + the opportunity to review all of the proposed changes before applying the + role to the system. Use the ``--check`` parameter with ``ansible-playbook`` + to use check mode.