new layout

Signed-off-by: Mark Bolwell <mark.bollyuk@gmail.com>

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)

docs/source/audit/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 <http://docs.ansible.com/ansible/intro_installation.html>`_.
+
+and has a good understanding of using ansible
+
+* `Ansible User Guide <https://docs.ansible.com/ansible/latest/user_guide/index.html>`_.
+
+
+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.