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:

The tasks in the security role enable the appropriate Linux Security Module
(LSM) for the operating system.

For Ubuntu, openSUSE and SUSE Linux Enterprise 12 systems, AppArmor is installed and
enabled. This change takes effect immediately.

For CentOS or Red Hat Enterprise Linux systems, SELinux is enabled (in
enforcing mode) and its user tools are automatically installed. If SELinux is
not in enforcing mode already, a reboot is required to enable SELinux and
relabel the filesystem.

.. warning::

    Relabeling a filesystem takes time and the server must be offline for the
    relabeling to complete. Filesystems with large amounts of files and
    filesystems on slow disks will cause the relabeling process to take more
    time.

Deployers can opt out of this change by setting the following Ansible variable:

.. code-block:: yaml

    rhel7stig_disruption_high: no

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.