TTS Dockerized Compliance Trestle

This repository contains the source code for the ghcr.io/gsa-tts/trestle Docker image and OSCAL models to be used by that image.

Image Use:

General workflow:

1. Download trestle image and run CLI
2. Create the files for a given SSPP
3. Do in a loop:
   1. Edit control statements within markdown files
   2. Assemble markdown contents into a provisional OSCAL SSP
   3. Edit other sections of the SSPP within the smaller json files
   4. Check your progress
4. Assemble everything into a final OSCAL SSP (TODO: within a CI workflow)
5. Update non-OSCAL SSP sections
6. Render a human-readable SSPP (TODO: within a CI workflow)

Use in a GitLab Runner

(beta) We're working on a -glr variant image for use within gitlab-runner-cloudgov

Pull down the trestle image and initialize a compliance trestle project

Prerequisite: $(pwd)/compliance directory exists and is where you want to store all compliance artifacts

docker pull ghcr.io/gsa-tts/trestle
docker run -it --rm -v $(pwd)/compliance:/app/docs ghcr.io/gsa-tts/trestle bash

All other usage commands assume you are operating within the docker container.

Create Control Statement Markdown Files

If you are using a profile that isn't shipped with the image you must import it first

If you are utilizing Component Definitions, you must import and/or create them first.

generate-ssp-markdown -p PROFILE_NAME [-c COMP_DEF_NAMES]

Assemble SSP JSON from Markdown

assemble-ssp-json -n SYSTEM_NAME [-c COMP_DEF_NAMES]

This step will create system-security-plans/SYSTEM_NAME/system-security-plan.json as well as smaller JSON files within system-security-plans/SYSTEM_NAME/system-security-plan/ for editing.

This script should be given the same list of Component Definitions that were passed to generate-ssp-markdown

Check Control Status

The control-status script will output a quick report of all of the Implementation Status lines for your controls. For instance, to report on the status of all controls except those marked as implemented:

control-status -i implemented

Final SSP Assembly

trestle assemble -n SYSTEM_NAME system-security-plan

Update non-OSCAL SSP files.

Edit the files within ssp-markdown to populate data for the rendered SSP that can't yet be pulled from OSCAL.

Hint: Use jinja templates md_clean_include and mdsection_include to populate content from other existing documents your team is using.

Render SSP

Output the SSP as a markdown file within ./ssp-render

render-ssp

You can optionally use pandoc to transform the markdown file into a variety of formats. For example:

PDF

docker run --rm --volume "/dir/with/rendered_ssp.md:/data" pandoc/latex rendered_ssp.md -o your-pdf-file-name.pdf

HTML

docker run --rm --volume "/dir/with/rendered_ssp.md:/data" pandoc/latex rendered_ssp.md -s -o your-html-file-name.html --metadata title="SSP Title"

Import profile into working space:

If you are using a PROFILE_NAME that does not ship with this docker container then you must first manually import it using:

trestle import -f PROFILE_URL -o PROFILE_NAME

Once that is done you can go back to the generate-ssp-markdown step

Import Component Definition into working space:

To import a component that ships with this docker container: copy-component -n COMPONENT_NAME

To import a component that is available from a URL: copy-component -n COMPONENT_NAME -u COMPONENT_URL

Create Component Definition

create-component -n COMPONENT_NAME

And then edit the created files to contain the component definition.

Split SSP into manageable files

This step is automatically handled by the assemble-ssp-json script as long as that script is run from the trestle root.

split-ssp -n SYSTEM_NAME

Templates:

The following templates are included in the Docker image:

profiles/lato

A profile representing the set of controls covered by a GSA LATO SSPP.

component-definitions/cloud_gov

A Component Definition representing the Cloud.gov CRM.

component-definitions/devtools_cloud_gov

A set of testable best practices for running applications on cloud.gov. This component integrates with Auditree and c2p to generate compliance results

catalogs/nist800-53r5

A copy of the full NIST 800-53 revision 5 catalog.

catalogs/lato

A resolved catalog of just the NIST 800-53r5 controls that are used by the LATO profile.

Development

Updating templates:

Run the trestle image locally through Docker Compose:

docker compose run cli bash

Utilize compliance-trestle commands within the /app/templates directory to make any changes that are required.

The /app/docs directory can be used as a scratch area for any temporary trestle tests.

Updating the Docker image:

1. Make required changes to the Dockerfile
2. Push to GitHub and create a PR
3. On merging to main, a new docker image will be built, tagged, and pushed to the github container registry.

Each published image will be tagged with:

1. latest
2. The publication date: YYYYMMDD
3. The branch it was created on: main
4. The short git sha: sha-c9f60e2