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 files

   touch opencontrol.yaml
   

3. Edit the opencontrol.yaml to contain the following data:

   schema_version: "1.0.0" # 1.0.0 is the current opencontrol.yaml schema version
   name: Project_Name # Name of the project
   metadata:
     description: "A description of the system"
     maintainers:
       - maintainer_email@email.com
   components: # A list of paths to components written in the opencontrol format for more information view: https://github.com/opencontrol/schemas
     - ./component-1
   certifications: # An optional list of certifications for more information visit: https://github.com/opencontrol/schemas
     - ./cert-1.yaml
   standards: # An optional list of standards for more information visit: https://github.com/opencontrol/schemas
     - ./standard-1.yaml
   dependencies:
     certifications: # An optional list of certifications stored remotely
       - url: github.com/18F/LATO
         revision: master
     systems:  # An optional list of repos that contain an opencontrol.yaml stored remotely
       - url: github.com/18F/cg-compliance
         revision: master
     standards:   # An optional list of remote repos containing standards info that contain an opencontrol.yaml
       - url: github.com/18F/NIST-800-53
         revision: master
   

4. Collect dependencies

   compliance-masonry get
   

The get command will retrieve dependencies needed to compile documentation.

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.

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:

• cloud.gov compliance data repository + documentation generated by Compliance Masonry

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.