manage.get.gov/docs/compliance

Compliance Template

A compliance documentation workflow using OSCAL with Trestle to generate a System Security Plan (SSP) using Markdown.

Usage

Background

For a little background on OSCAL please see the glossary and control families documentation.

Make

We use the Makefile for our workflow. You will be primarily working in dist/system-security-plans/ato where all the Markdown for our controls live. You will usually not need to run any Make commands while documenting. Just add your explanation on each control to the SSP Markdown. But the Make commands we have are:

• make generate to have trestle generate the corresponding control statement in Markdown. Use this if you need to add a control.
• make generate-with-header to have trestle generate the corresponding control statement in Markdown with the status headers.
• make assemble will generate the resulting OSCAL System Security Plan (SSP).
• make status will print out some basic metrics about control status bits.

Suggested workflow

Here is a suggested compliance documentation workflow that uses compliance-trestle:

• Add a control to the profile that will be satisfied.
• Run make generate to have trestle generate the corresponding control statement in Markdown.
  • This Markdown file will live in dist/system-security-plans/.
• Flesh out implementation detail stubs for that control.
  • It is OK to leave a control implementation description blank initially.
  • Backfill missing implementation descriptions as needed.
  • If links to existing code are needed, consider linking to high level artifacts with a general description.
    • Avoid linking directly to lines of code as these will change over time.
• (Optionally) Run make assemble to generate the resulting OSCAL System Security Plan (SSP).
  • This is an optional step because nothing uses the OSCAL SSP yet.

Status

To track compliance status, there's a header yaml file with a status list. The options are:

• c-not-implemented: this control has not been met or documented.
• c-implemented: this control has been met and documented.
• c-inherited: this control is inherited from cloud.gov or another system we use.
• c-org-help-needed: this control needs to be implemented at a higher level.

make status will print out some basic metrics about control status bits.

Controls

Below are details about the controls, including additional parameters, notes, and control families.

Parameters

A few controls require us to supply parameters to the control. These parameter choices are given in the official NIST catalog description. For instance, sc-12.2 requires us to choose between NIST FIPS-compliant or NSA-approved symmetric keys.

To provide a parameter, edit the profile and add the relevant parameter id to the set-parameters section, along with the value(s) that best fits the control. (Note that some controls allow more than one parameter.)

It is also possible to override the default parameters for a control, if needed.

Once new parameters are set in the profile, please run make generate to re-generate the control Markdown with the new parameters.

Attribution

This is a copy with alternations from the 18F compliance-template

Getting started for non-python devs

1. Install pipenv
2. Run pipenv install to install dependencies from Pipfile
3. Run pipenv shell to start a shell with the correct virtual environment configured