compliance-masonry

README

Compliance Masonry

Compliance Masonry is a command-line interface (CLI) that allows users to construct certification documentation using the OpenControl Schema. See Benefits for more explanation, and learn more in our blog post about Compliance Masonry. If you're interested in working on the code, see our developer documentation.

Quick start

1. Install Go 1.6, and ensure your GOPATH is set. Using gvm is recommended.

2. Install the tool

   go get github.com/opencontrol/compliance-masonry
   

3. Run the CLI

   compliance-masonry
   

Creating an OpenControl project

1. Start a fresh directory

   mkdir your-project-name && cd your-project-name
   

2. Create an opencontrol.yaml

3. Collect dependencies

   compliance-masonry get
   

The get command will retrieve dependencies needed to compile documentation in an opencontrols/ folder. You will probably want to exclude this from your version control system (e.g. add opencontrols/ to your .gitignore).

Creating Gitbook Documentation

1. Update dependencies

   compliance-masonry get
   

2. Run the gitbook command

   compliance-masonry docs gitbook LATO
   # Or
   compliance-masonry docs gitbook FedRAMP-low
   

The gitbook command by default will create a folder called exports that contains the files needed to create a gitbook. Visit the gitbook documentation for more information on creating gitbooks via the CLI.

Adding additional markdown content to Gitbook documentation (optional)

Security documentation usually requires unstructured information that is not captured in the control documentation. The markdowns directory can be used to add this supplemental information.

1. Create a markdowns folder in the same directory as the opencontrol.yaml.

   mkdir markdowns
   

2. Create the markdowns/SUMMARY.md and markdowns/README.md documents.

   touch markdowns/SUMMARY.md
   touch markdowns/README.md
   

The content of the markdowns/SUMMARY.md and markdowns/README.md files and the files they reference is prepended to the Gitbook documentation.

For more information on using the SUMMARY.md and README.md files visit the Gitbook documentation. For an example markdowns directory visit the cloud.gov markdowns.

Viewing gitbook locally in browser

Requires NodeJS. After running the steps above,

1. Install the gitbook CLI

   npm install -g gitbook-cli
   

2. Navigate to the exports directory

   cd exports
   

3. Serve the gitbook site locally

   gitbook serve
   

4. Open the site: http://localhost:4000

After making any edits, view the changes by running

compliance-masonry get && compliance-masonry docs gitbook <certification>

Export gitbook as a PDF

1. Following the steps above

2. Navigate to the exports directory

   cd exports
   

3. Follow these instructions

Create Docx template

1. Create a Word Document template that uses the following template tag format:

   Documentation for Standard: NIST-800-53 and Control: CM-2 will be rendered below
   {{ getControl "NIST-800-53@CM-2"}}
   
   Documentation for Standard: NIST-800-53 and Control: AC-2 will be rendered below
   {{ getControl "NIST-800-53@AC-2"}}
   

2. Run the docx command.

   compliance-masonry docs docx -t path/to/template.docx
   

Running the docx command will by default create a file named export.docx in the local directory.

Gap Analysis

Use Gap Analysis to determine the difference between how many controls you have documented versus the total controls for a given certification. This should be used continually as you work to indicate your compliance progress.

Given you have an opencontrol.yaml for your project and you have already collected your dependencies via the compliance-masonry get command, run compliance-masonry diff <the-certification>:

# Example
$ compliance-masonry diff FedRAMP-moderate
Number of missing controls: 5
NIST-800-53@CP-7 (1)
NIST-800-53@PS-2
NIST-800-53@PS-3 (3)
NIST-800-53@MP-5
NIST-800-53@PS-7

Examples

Compliance Masonry examples in the wild (in order of completeness):

• cloud.gov data and gitbook
• 18F Identity-IdP (Upaya)
• 18F Confidential Survey (needs update)

Documentation Format

Compliance Masonry uses the OpenControl v2 Schema.

Benefits

Modern applications are built on existing systems such as S3, EC2, and Cloud Foundry. Documentation for how these underlying systems fulfill NIST controls or PCI SSC Data Security Standards is a prerequisite for receiving authorization to operate (ATO). Unlike most System Security Plan documentation, Compliance Masonry documentation is built using OpenControl Schema, a machine readable format for storing compliance documentation.

Compliance Masonry simplifies the process of certification documentations by providing:

1. a data store for certifications (ex FISMA), standards (ex NIST-800-53), and the individual system components (ex AWS-EC2).
2. a way for government project to edit existing files and also add new control files for their applications and organizations.
3. a pipeline for generating clean and standardized certification documentation.