ansible-lockdown/RHEL9-CIS
3
0
Fork 1
mirror of https://github.com/ansible-lockdown/RHEL9-CIS.git synced 2025-12-27 15:33:06 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

initial RTD testing

Browse source 
Signed-off-by: Mark Bolwell <mark.bollyuk@gmail.com>
This commit is contained in:
Mark Bolwell 2022-04-28 12:15:53 +01:00
parent 33cfc54a5e
commit 7ec8b73375
No known key found for this signature in database
GPG key ID: F734FDFC154B83FB
14 changed files with 1142 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

16
docs/.readthedocs.yaml Normal file
View file

@ -0,0 +1,16 @@
version: 2
build:
os: "ubuntu-20.04"
tools:
python: "3.8"
python:
# Install our python package before building the docs
install:
- method: pip
path: .
sphinx:
fail_on_warning: true
formats:
- pdf
- epub

181
docs/Makefile Normal file
View file

@ -0,0 +1,181 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS = "-W"
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
clean:
rm -rf $(BUILDDIR)/*
rm source/auto_*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/openstack-ansible.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/openstack-ansible.qhc"
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/openstack-ansible"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/openstack-ansible"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

8
docs/README.md Normal file
View file

@ -0,0 +1,8 @@
To generate the documentation on a RHEL/CentOS 7 system, take the following steps:
1. Install required packages:
* `yum install python3-pip python-sphinx`
2. Install the requirements:
* `sudo pip3 install -r requirements.txt`
3. Generate the documentation:
* `make singlehtml`

9
docs/requirements.txt Normal file
View file

@ -0,0 +1,9 @@
# The order of packages is significant, because pip processes them in the order
# of appearance. Changing the order has an impact on the overall integration
# process, which may cause wedges in the gate later.
# this is required for the docs build jobs
sphinx>1.8
sphinx_rtd_theme
Jinja2
PyYAML

0
docs/source/_static/.gitkeep Normal file
View file

1
docs/source/_static/MPG-logo-mono-blue.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 5.2 KiB

350
docs/source/conf.py Normal file
View file

@ -0,0 +1,350 @@
#!/usr/bin/env python3
# Set Variables
# Used to try and allow multiple benchmark versions to use the same layout
BENCHMARK_TYPE = "CIS"
BENCHMARK_OS = "RedHat Enterprise Linux 9"
BENCHMARK_OS_SHORT = "RHEL9"
BENCHMARK_VERSION = "V0.5 beta"
BENCHMARK_REL_DATE = "TBC"
LOCKDOWN_URL = "https://github.com/ansible-lockdown/{BENCHMARK_OS_SHORT}-{BENCHMARK_TYPE}"
TESTED_OS = '''\
* RHEL9
* ROCKY9
* ALMALINUX9\
'''.format(length='multiline',ordinal='second')
"""Documentation configuration for Ansible Lockdown roles."""
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import os
import sys
from collections import OrderedDict
# import pbr.version
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.join(os.path.abspath('.'), '_exts'))
# NOTE(mhayden): Since the security role docs are fairly lengthy and deeply
# nested in places, sphinx occasionally throws a pickling error as shown in
# Launchpad bug 1627732. Sphinx 1.4 now prints a recommendation in these
# situations to increase Python's recursion limit a bit higher to avoid the
# pickling error.
sys.setrecursionlimit(4000)
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'ansiblelockdown_docs',
]
# Add any paths that contain templates here, relative to this directory.
# templates_path = ['_templates']
# The suffix(es) of source filenames.
source_suffix = '.rst'
# The encoding of source files.
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
author = 'MindPoint Group'
category = 'Security'
copyright = '2022, MindPoint Group'
description = '{BENCHMARK_TYPE} compliance for {BENCHMARK_OS_SHORT} systems'
project = 'Ansible-lockdown {BENCHMARK_OS_SHORT}-{BENCHMARK}'
role_name = '{BENCHMARK_OS_SHORT}-{BENCHMARK_TYPE}'
target_name = '{BENCHMARK_OS_SHORT}-{BENCHMARK_TYPE}'
title = 'Ansible-Lockdown {BENCHMARK_OS_SHORT}-{BENCHMARK_TYPE} Documentation:'
rst_prolog = """
.. |benchmark_name| replace:: {BENCHMARK_TYPE}
.. |benchmark_os| replace:: {BENCHMARK_OS}
.. |benchmark_os_short| replace:: {BENCHMARK_OS_SHORT}
.. |benchmark_version| replace:: {BENCHMARK_VERSION}
.. |benchmark_release_date| replace:: {BENCHMARK_REL_DATE}
.. |lockdown_url| replace:: {LOCKDOWN_URL}
.. |tested_oss| replace:: {TESTED_OS}
"""
# The version info for the project you're documenting, acts as replacement for
# |mindpointversion| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
# version_info = pbr.version.VersionInfo(target_name)
# The full version, including alpha/beta/rc tags.
# release = version_info.version_string_with_vcs()
# The short X.Y version.
# version = version_info.canonical_version_string()
# openstackdocstheme options
# repository_name = 'mindpointgroup/' + target_name
# bug_project = project.lower()
# bug_tag = ''
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = [
'developer-notes/*.rst',
'stig-notes/*.rst',
]
# The reST default role (used for this markup: `text`) to use for all
# documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# -- STIG Ansible Docs extension config items -----------------------------
stig_metadata_dir = '../metadata' # relative path from the doc source dir
stig_ansible_dir = '../../' # relative path from doc source
stig_ansible_task_filenames = ['fix-cat1.yml', 'fix-cat2.yml', 'fix-cat3.yml']
stig_xccdf_file = 'U_Red_Hat_Enterprise_Linux_7_STIG_V2R1_Manual-xccdf.xml' # filename only this should be placed in metadata dir
stig_xccdf_namespace = "{http://checklists.nist.gov/xccdf/1.1}"
stig_control_statuses = {
'default': 'Implemented',
'rhel7stig_complex': 'Complexity High',
'rhel7stig_disruptive': 'Disruption High',
'missing': 'Not Implemented',
}
stig_control_statuses_order = ['Implemented', 'Complexity High', 'Disruption High', 'Not Implemented']
stig_control_severities = ['high', 'medium', 'low']
# -- STIG Ansible Docs extension config items -----------------------------
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'sphinx_rtd_theme'
html_theme_options = {
'display_version': True,
'prev_next_buttons_location': 'bottom',
'sticky_navigation': True,
'collapse_navigation': False,
}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = '_static/MPG-logo-mono-blue.svg'
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
# html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = '%Y-%m-%d %H:%M'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_domain_indices = True
# If false, no index is generated.
html_use_index = False
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = False
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = target_name + '-docs'
# If true, publish source files
html_copy_source = False
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, target_name + '.tex',
title, author, 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# If true, show page references after internal links.
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, target_name,
title, [author], 1)
]
# If true, show URL addresses after external links.
# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, target_name,
title, author, project,
description, category),
]
# Documents to append as an appendix to all manuals.
# texinfo_appendices = []
# If false, no module index is generated.
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
# texinfo_no_detailmenu = False
# -- Options for PDF output --------------------------------------------------
pdf_documents = [
(master_doc, target_name,
title, author)
]

52
docs/source/controls-contrib.rst Normal file
View file

@ -0,0 +1,52 @@
Additional Controls
===================
Although the |benchmark_name| documentation guide contains a
comprehensive set of security configurations, some contributors want to add
extra security configurations to the role. The *contrib* portion of the
role is designed to implement those configurations as an optional set of tasks.
In general, *contrib* controls are limited to items to meet backwards compatibility
with the `Openstack Ansible Hardening`_ project. It is recommended that new *contrib*
items (things that don't address specific items) should be addressed in a separate
Ansible role.
.. _Openstack Ansible Hardening: https://github.com/openstack/ansible-hardening
**BELOW IS NOT YET IMPLEMENTED IN THIS ROLE**
*The below configurations and variables are not yet implemented. This page and
message are being kept until it is implemented.*
The *contrib* hardening configurations are disabled by default, but they can
be enabled by setting the following Ansible variable:
.. code-block:: yaml
rhel7stig_security_contrib_enabled: yes
The individual tasks are controlled by Ansible variables in
``defaults/main.yml`` that are defined under the
``rhel7stig_security_contrib:`` variable.
Kernel
------
Disable IPv6
~~~~~~~~~~~~~~~~~~~~~~
Some systems do not require IPv6 connectivity and the presence of link local
IPv6 addresses can present an additional attack surface for lateral movement.
Deployers can set the following variable to disable IPv6 on all network
interfaces:
.. code-block:: yaml
rhel7_stig_security_contrib:
disable_ipv6: yes
.. warning::
Deployers should test this change in a test environment before applying it
in a production deployment. Applying this change to a production system
that relies on IPv6 connectivity will cause unexpected downtime.

110
docs/source/controls.rst Normal file
View file

@ -0,0 +1,110 @@
.. _controls_label:
Controls
========
This role follows the |benchmark_name| `implementation guide`_.
The guide has over 200 controls that apply to various parts of a Linux system, and it
is updated regularly by the Defense Information Systems Agency (DISA). DISA is part of the
United States Department of Defense. The current version of this role follows |stig_version|
of the |benchmark_os_short| |benchmark_name|.
Controls are divided into groups based on the following properties:
Control Severities
~~~~~~~~~~~~~~~~~~
:ref:`High (CAT I) <severity-high>`
These controls have a large impact on the security of a
system. They also have the largest operational impact to a system and
deployers should test them thoroughly in non-production environments.
:ref:`Medium (CAT II) <severity-medium>`
These controls are the bulk of the items in the STIG and
they have a moderate level of impact on the security of a system.
Many controls in this category will have an operational impact on
a system and should be tested thoroughly before implementation.
:ref:`Low (CAT III) <severity-low>`
These controls have a smaller impact on overall security, but they
are generally easier to implement with a much lower operational impact.
Implementation Status
~~~~~~~~~~~~~~~~~~~~~
It is important to understand the implementation status of each control and
the potential impact each task can have on a system. Some controls are not
implemented for various technical reasons. Some are implemented but disabled
by default. And others are just peform a check and report back if manual
changes need to be made to meet the STIG control.
:ref:`Implemented <status-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.
:ref:`Complexity High <status-Complexity-High>`
These controls are deemed too complex to safely rememdiate via automated
controls. The tasks for these controls perform automated checks and will
report the result of the check in Ansible task output. The purpose of this
output is to alert deployers to items that would fail an audit against the
STIG and should be rememdiated manually. Execution and reporting from these
tasks can be enabled or disabled via the appropriate variables.
.. code-block:: yaml
rhel7stig_complexity_high: no
rhel7stig_audit_complex: yes
:ref:`Disruption High <status-Disruption-High>`
These controls are classified as having a high likelihood of distruption on a
system and disabled by default. Automatic rememdiation can be enabled by
setting the appropriate variables, however the deployer should be aware
that 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.
.. code-block:: yaml
rhel7stig_disruption_high: no
rhel7stig_audit_disruptive: yes
:ref:`Not Implemented <status-Not-Implemented>`
These are controls that have not yet been implemented. The goal of this project
is to have no controls in this status. This does not mean 100% of the controls
will be fully implemented. Just that 100% of the controls will be in one of the
above status categories. We welcome any help in getting these controls implemented.
Deployers should review the full list of controls
:ref:`sorted by implementation status <controls-by-status>`.
Control Deviation
~~~~~~~~~~~~~~~~~
The role deviates from some of the STIG's requirements when a security control
could cause significant issues with production systems. Additionally specific
control settings, which are controlled by role variables, can deviate from
the mandated STIG settings. Deployers should review and update the default
configurations to meet the needs of their environment.
.. note::
All of the default configurations are found within ``defaults/main.yml``.
.. _Security Technical Implementation Guide (STIG): http://iase.disa.mil/stigs/os/unix-linux/Pages/red-hat.aspx
Controls
~~~~~~~~
.. toctree::
:maxdepth: 1
auto_controls-all.rst
.. toctree::
:maxdepth: 2
auto_controls-by-severity.rst
auto_controls-by-status.rst

131
docs/source/customization.rst Normal file
View file

@ -0,0 +1,131 @@
iRole Customization
==================
This role can be fully customized to fit your specific environment. In fact
for most users it is recommended that they customize/tweak the role variables
before applying across their envirnoment.
.. contents::
:local:
:backlinks: none
Tailoring
---------
It is recommended that you tailor this roles tasks for your environment by using
the comprehensive set of variables defined in ``defaults/main.yml``. There are
several ways to override default role variables in Ansible. We cover the recommended
techniques below.
Using ``group_vars``
~~~~~~~~~~~~~~~~~~~~~~~~
The easiest way to tailor this role to your environment is by using ``group_vars``:
**NEED CONTENT**
*insert example for group_vars tailoring*
Variables
---------
The role has a large number of variables that allow the deployer to control the execution
of specific tasks (on/off) as well as the configuration or settings for the tasks and the
controls they implement. For example the deployer can choose to enable or disable tasks
by severity/category *cat1 | high, cat2 | medium, cat3 | low*. The deployer can also set
things like whether any *GUI* related tasks should run or tailor specific STIG settings
like the logon banner text or password complexity settings. We don't cover all the variables
in this section but we do cover some of the major ones. Generally the variables that control
specific tasks or control configurations are detailed in the
:ref:`controls documentation <stig_controls_label>`.
Enable tasks by category/severity
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These variables allow enabling/disabling cat1, cat2, or cat3 rules in bulk. Disabling these
will take precedence over individual task variables but enabling them will not. i.e. If the
``rhel7stig_cat3_patch`` variable is set to ``no`` then all *cat3* tasks will be skipped
regardless of their :ref:`individual settings <individual_rule_vars>`. However if the *cat3*
variable is enabled individual tasks could still be skipped if their variable is disabled.
.. code-block:: yaml
rhel7stig_cat1_patch: yes
rhel7stig_cat2_patch: yes
rhel7stig_cat3_patch: yes
Complex tasks
~~~~~~~~~~~~~
There are several variables that control the execution or behavior of tasks that the
implementers of this role have deemed to be too complex or risky to automatically
remediate. These rules have tasks that audit the system and will optionally report
``changed`` and will report back (via debug statements) if the system would fail
the check. The deployer can use this information to manually remediate the finding.
The execution and reporting behavior of these tasks is controlled by two variables:
.. code-block:: yaml
# Controls execution of these tasks
rhel7stig_complexity_high: no
# Controls whether the tasks reports changed or not
rhel7stig_audit_complex: yes
Disruptive tasks
~~~~~~~~~~~~~~~~
These varaibles are similar to the *complex task* variables. They control the
execution or behavior of tasks that perform automated remediation but are shown
to be potentially disruptive to systems when used in production environments.
The risk of automated remediation of with these tasks is high.
These rules have tasks that audit the system and will optionally report
``changed`` and will report back (via debug statements) if the system would fail
the check. The deployer can use this information to manually remediate the finding.
The execution and reporting behavior of these tasks is controlled by two variables:
.. code-block:: yaml
# Controls execution of these tasks
rhel7stig_disruption_high: no
# Controls whether the tasks reports changed or not
rhel7stig_audit_disruptive: yes
Required system services
~~~~~~~~~~~~~~~~~~~~~~~~
These variables allow the deployer to specify that services are required by the system
to perform its mission. Except for ``ssh``, it is important to note that having these
services installed and enabled are deviations from the STIG benchmark and should have
corresponding documentation approved by the system owner or other signing authority.
.. code-block:: yaml
rhel7stig_ssh_required: yes
rhel7stig_vsftpd_required: no
rhel7stig_tftp_required: no
rhel7stig_autofs_required: no
rhel7stig_kdump_required: no
rhel7stig_ipsec_required: no
Graphical User Interface items
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This variable enables or disables all tasks related to *GUI* packages. i.e. These
generally would only apply to a system with the ``GNOME`` package installed. This
is not to say that ``KDE``, ``XFCE``, or one of the many other desktop systems
would not need to have similar controls in place, but the STIG currently only
covers ``GNOME`` settings.
.. code-block:: yaml
rhel7stig_gui: no
.. _individual_rule_vars:
Individual STIG rules
~~~~~~~~~~~~~~~~~~~~~
These variables enable or disable individual rules or more specifically tasks or
blocks of tasks that enforce individual STIG rules. Each STIG item with an ID
following the format *RHEL-07-###### (ex. RHEL-07-010010)* will have a corresponding
variable in the below format. For more information on each rule and its default state
please see the :ref:`controls documentation <stig_controls_label>`.
.. code-block:: yaml
rhel_07_######: true

43
docs/source/developer-guide.rst Normal file
View file

@ -0,0 +1,43 @@
Developer Guide
===============
Building a development environment
----------------------------------
**NEED CONTENT**
*Insert dev environment setup and test running instructions.*
Writing documentation
---------------------
Documentation for individual controls is automatically generated where possible.
There is also the ability to add deployer notes for individual tasks that discuss
the specific implementation or risks with running the task/etc. Variables that
control the execution of each task are automatically pulled from the Ansible task
files themselves.
Deployer notes
~~~~~~~~~~~~~~
Deployer notes are optional and can be added for each control that needs
additional data to be provided to role users. The notes are simply rST
(reStructuredText) fragments and can contain simple blocks of text or
more complex rST formatted text. The system matches deployer notes to STIG
controls based on the note filename, which should follow the format
``RHEL-07-010010.rst``.
All of the notes are found within ``doc/metadata/notes``. Here is an example:
.. literalinclude:: ../metadata/notes/example-note.rst
:language: yaml
The note should be brief, but it must answer a few critical questions:
* What does the change do to a system?
* What is the value of making this change?
* How can a deployer opt out or opt in for a particular change?
* Is there additional documentation available online that may help a deployer
decide whether or not this change is valuable to them?
Run ``make html`` from the ``doc/`` directory to rebuild the documentation
and review your changes.

69
docs/source/faq.rst Normal file
View file

@ -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)

102
docs/source/getting-started.rst Normal file
View file

@ -0,0 +1,102 @@
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:
.. code-block:: yaml
---
- 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.

70
docs/source/index.rst Normal file
View file

@ -0,0 +1,70 @@
=========================================================
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
.. raw:: html
<p><iframe src="https://ghbtns.com/github-btn.html?user=MindPointGroup&repo=RHEL7-STIG&type=watch&count=true&size=large&v=2"
allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe></p>
What does the role 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.
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.
.. _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.
.. toctree::
:maxdepth: 2
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