From 7ec8b733757a8f6422366f4cf11afcfd6cd80bbf Mon Sep 17 00:00:00 2001 From: Mark Bolwell Date: Thu, 28 Apr 2022 12:15:53 +0100 Subject: [PATCH] initial RTD testing Signed-off-by: Mark Bolwell --- docs/.readthedocs.yaml | 16 + docs/Makefile | 181 +++++++++++ docs/README.md | 8 + docs/requirements.txt | 9 + docs/source/_static/.gitkeep | 0 docs/source/_static/MPG-logo-mono-blue.svg | 1 + docs/source/conf.py | 350 +++++++++++++++++++++ docs/source/controls-contrib.rst | 52 +++ docs/source/controls.rst | 110 +++++++ docs/source/customization.rst | 131 ++++++++ docs/source/developer-guide.rst | 43 +++ docs/source/faq.rst | 69 ++++ docs/source/getting-started.rst | 102 ++++++ docs/source/index.rst | 70 +++++ 14 files changed, 1142 insertions(+) create mode 100644 docs/.readthedocs.yaml create mode 100644 docs/Makefile create mode 100644 docs/README.md create mode 100644 docs/requirements.txt create mode 100644 docs/source/_static/.gitkeep create mode 100644 docs/source/_static/MPG-logo-mono-blue.svg create mode 100644 docs/source/conf.py create mode 100644 docs/source/controls-contrib.rst create mode 100644 docs/source/controls.rst create mode 100644 docs/source/customization.rst create mode 100644 docs/source/developer-guide.rst create mode 100644 docs/source/faq.rst create mode 100644 docs/source/getting-started.rst create mode 100644 docs/source/index.rst diff --git a/docs/.readthedocs.yaml b/docs/.readthedocs.yaml new file mode 100644 index 0000000..9f3d9bb --- /dev/null +++ b/docs/.readthedocs.yaml @@ -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 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..a30c545 --- /dev/null +++ b/docs/Makefile @@ -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 ' where 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." diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..fb11aec --- /dev/null +++ b/docs/README.md @@ -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` + diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..47a7375 --- /dev/null +++ b/docs/requirements.txt @@ -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 diff --git a/docs/source/_static/.gitkeep b/docs/source/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/source/_static/MPG-logo-mono-blue.svg b/docs/source/_static/MPG-logo-mono-blue.svg new file mode 100644 index 0000000..561865a --- /dev/null +++ b/docs/source/_static/MPG-logo-mono-blue.svg @@ -0,0 +1 @@ +MPG-logo-mono-blue \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..f14a447 --- /dev/null +++ b/docs/source/conf.py @@ -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 +# " v 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 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) +] diff --git a/docs/source/controls-contrib.rst b/docs/source/controls-contrib.rst new file mode 100644 index 0000000..1a7f0d6 --- /dev/null +++ b/docs/source/controls-contrib.rst @@ -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. diff --git a/docs/source/controls.rst b/docs/source/controls.rst new file mode 100644 index 0000000..c3029a3 --- /dev/null +++ b/docs/source/controls.rst @@ -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) ` + 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) ` + 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) ` + 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 ` + 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 ` + 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 ` + 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 ` + 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 `. + + +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 diff --git a/docs/source/customization.rst b/docs/source/customization.rst new file mode 100644 index 0000000..617ceed --- /dev/null +++ b/docs/source/customization.rst @@ -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 `. + +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 `. 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 `. + +.. code-block:: yaml + + rhel_07_######: true diff --git a/docs/source/developer-guide.rst b/docs/source/developer-guide.rst new file mode 100644 index 0000000..3a8e6ad --- /dev/null +++ b/docs/source/developer-guide.rst @@ -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. diff --git a/docs/source/faq.rst b/docs/source/faq.rst new file mode 100644 index 0000000..9de8d17 --- /dev/null +++ b/docs/source/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/getting-started.rst new file mode 100644 index 0000000..f5a25cf --- /dev/null +++ b/docs/source/getting-started.rst @@ -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 `_. +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: + +.. 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. diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..991a1c1 --- /dev/null +++ b/docs/source/index.rst @@ -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 + +

+ +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 +