Select Page

COMPASS Part 3: Artifacts and Personas

Vikas Agarwal
Published: September 19, 2022

In part 2 of this multi-part blog series on continuous compliance, we described our open-source SDK called Trestle which provides an implementation of the NIST Open Security Control Assessment Language (OSCAL) standard framework and the corresponding set of key compliance artifacts expressed as compliance as code. We mentioned that in addition to direct editing and manipulation of OSCAL documents, Trestle also provides capabilities for agile authoring of compliance artifacts as Markdown content and its conversion to OSCAL format. Further, in our first blog in this series, we described various personas and their role in the compliance processes.

In this blog post, we will focus on how Trestle enables those diverse personas to collaboratively author the compliance artifacts by providing a variety of interfaces and authoring methods suitable to the broad set of skills of those personas, from editing Markdown and spreadsheets, to editing OSCAL JSON. We also describe how Trestle workflow automation supports the actions that various personas need to take in the compliance end-to-end flow. 

As a reminder, we previously used Figure 1 to concisely illustrate a few examples of compliance artifacts and their representation: regulations and standards such as HIPAA or NIST 800-53 generated by regulators as PDFs; catalogs/profiles of controls and technical policy rules expressed by control providers as compliance as code (e.g., the NIST OSCAL) to describe their systems’ implementation of the regulations’ controls; and policy checks implemented by control assessors as policy as code (e.g., Open Policy Agent – OPA) to verify the systems’ compliance in the regulated environments. We focus hereafter on the compliance artifacts which are candidates for representation as compliance as code. We will cover the policy checks, which are candidates for representation as policy as code, in a following blog.

Illustrative examples for various compliance artifacts and their programmatic representation

Figure 1: Illustrative examples for various compliance artifacts and their programmatic representation. Regulations in PDF format (top) vs. Controls and Rules expressed as Compliance as Code (middle) vs. Checks Scripts as Policy as Code to test the system’s compliance (bottom).

Collaborative Agile Authoring of Compliance Artifacts by Different Personas

Regulators – Control Issuers

Regulators provide security regulations, laws (e.g., GDPR, HIPAA), and standards (e.g., NIST 800-53, PCI-DSS, ISO 2700x). These are typically provided in human consumable formats such as PDFs and Word docs. However, for automation, these need to be represented in a machine-readable format such as the OSCAL catalog format. As discussed, creating and editing large JSON or XML files is not human-friendly. Hence, Trestle provides tools to convert OSCAL files to Markdown format which can be easily edited and then assembled and converted back to OSCAL format.

Personas’ collaboration on compliance artifacts

Figure 2: Personas’ collaboration on compliance artifacts. Compliance artifacts representation in OSCAL compliance as code. Key relations and mappings in the OSCAL Component Definition object from compliance controls to policy as code to reach the traceability needed for compliance automation.

As illustrated in Figure 2, an OSCAL catalog contains control elements. The catalog controls can be created and edited by regulators in a systematic way by using Trestle and a Git repository. Trestle provides a CatalogGenerate command which takes an existing JSON catalog and writes it out as Markdown files, one for each control in a directory. That directory will contain subdirectories for each group in the catalog, and those directories may contain subdirectories for groups within groups.

Trestle uses a Markdown file with a YAML header for representing various pieces of control information. The YAML header is used for more structured content, such as control parameters, whereas a specific Markdown format is used for representing control statements and guidance. Users need to follow this format to enable Trestle to convert the Markdown files back into JSON format properly. Below is an example of a control in Markdown form and the corresponding JSON.

Catalog Markdown and its OSCAL format

Figure 3: Catalog Markdown and its OSCAL format

Users can edit the Markdown file, commit it to a Git branch, and then open a pull request (PR) for approvers to review before merging with the main branch of the repo. Once the right set of approvers agree on the content and merge it into the main, Git workflows can be automatically triggered to invoke Trestle’s CatalogAssemble command to generate the OSCAL JSON with the updated content. This way the control Markdown files and OSCAL JSON file are kept in sync with each other.

Compliance Officers and CISO – Control Owners

Besides the control descriptions and guidance specified by the regulators in the catalog, the Compliance Officers and CISOs of an organization typically add explanatory guidance on how the controls are interpreted and are to be applied in the case of their organization. They need to add, remove, and modify information in the original control description and guidance specified in the catalog. Moreover, they need to be able to limit the catalog controls to a subset and combine multiple controls from various catalogs. This editing activity is executed each time a new version of a catalog is released, or new controls are made available for assessment in the organization’s environment. This can be managed by Compliance Officers and CISO using Trestle to transform Markdown or CSV files into an OSCAL profile object.

As with the catalog, users edit the Markdown file, add content, and then commit it to a Git branch and open a pull request (PR) for approvers to review before merging with the main branch of the repo. Once again, after the right set of approvers accept the content and merge it into the main, Git workflows can be automatically triggered to invoke Trestle’s profile-assemble command to generate the OSCAL JSON with the updated content. Trestle will verify that each catalog reference imported in the profile is a valid link and object. Figure 4 shows the profile in Markdown and OSCAL JSON format created by Trestle.

Profile Markdown and its OSCAL format

Figure 4: Profile Markdown and its OSCAL format 

There can be multiple sets of guidance (e.g., for external and internal audits) to be specified for a control. If there is a single owner for all that information, then it can be maintained as part of a single Git repository. However, if there are separate owners for separate pieces of information, then they can be shared in one Git repository or can be maintained in separate repositories to allow their independent editing and versioning. In this case, new profiles can be created with additional information in a separate repository on top of existing profiles. The new profile will derive from the existing profile and the ownership can be kept separate for independent editing while still having one final profile (resolved catalog/profile) which contains all the information.

Product Vendors, Service Providers, and CISO – Control Providers

The regulation controls get implemented in cloud services, products, processes, or components adhering to that specific regulation. The product vendors or service providers specify their product’s compliance implementation by defining the mapping of the regulation controls to the product’s technical policy rules and their parameters. These rules can be thought of as configurations that can be performed on the service, across multiple services, or as behaviors of a product. Since the catalog or profile controls specify requirements at a coarser granularity and are technology agnostic, the rules capture the technology-specific implementation of those controls at a finer granularity such that they can be programmatically verified via tests based on evidence collected programmatically via APIs. This mapping declaration activity is executed each time the product’s controls implementation changes and can be managed by the Providers via Markdown or CSV and then using Trestle to produce a product, service, or capability-specific OSCAL component definition object. 

Note that given OSCAL’s upcoming support for catalog controls mapping (aka crosswalks), providers would have the choice to declare their product’s implementation for only a selected subset of standards. This would allow for their policy to be validated only against these few frameworks controls and later mapped or aggregated to other regulatory requirements based on the crosswalk mappings.

A control provider needs to provide for a given control both (a) the specific rules with related parameters and values, as well as (b) the control responses as text describing how a control is implemented by that product or service. 

1. Rules and Spreadsheets

Since the mapping of rules, parameters, and values to controls is very structured content, users prefer to provide this content in a spreadsheet format. The spreadsheet then gets converted to an OSCAL component definition object (as shown in Figure 5) using Trestle CLI. As part of the CI/CD pipeline in the trestle-central Git repository, we first automatically check that a submitted spreadsheet is valid, and then the CI/CD pipeline can proceed to create the corresponding OSCAL component definition.

2. Responses and Markdown 

The control providers also need to provide the control response and implementation status (e.g., complete, partial, planned) specific to that product in the context of a given catalog or profile control. Trestle provides Markdown format support for capturing this information as it is more suitable for this kind of content which is formatted text. Thus, we convert the OSCAL component definition object initially created from the spreadsheet to Markdown format (per control) where users can add the response information. Then we convert it back to the OSCAL component definition where the additional information from Markdown is added to the JSON object.

Component Definition spreadsheet and its OSCAL format for authoring of rules

Figure 5: Component Definition spreadsheet and its OSCAL format for authoring of rules itemized elements such as parameters, values, and mapping to controls. Component type “Service”.

Component Definition markdown and its OSCAL format for the authoring of the textual elements for control response to requirements and guidelinesFigure 6: Component Definition Markdown and its OSCAL format for the authoring of the textual elements for control response to requirements and guidelines

Figure 6 illustrates how Trestle handles a product’s control response Markdown (left side) for a particular regulation’s catalog or profile. The Markdown has an un-editable top section with the rules declared for that product and that control, followed by an un-editable middle section providing the user with all the information they need for the control description from the catalog, the guidance from the profile (if any), and finally the editable section with templatized questions about the response. This last section will be added upon conversion to OSCAL to the description field of the corresponding control in the product’s OSCAL component definition JSON (right side).

Besides products’ configuration-based policies, corporate CISO may define more complex policies, across products and processes, specific to a particular organization, or involve the behavior of the product over time. CISO can use the same means as the Control Providers to author via Trestle their policies mapping to regulation’s controls and generate their OSCAL component definition

Policy Validation Points, Validation Tools – Control Assessors

In the case of a policy validation product or service (called hereafter Policy Validation Point, or PVP), the PVP vendor’s component definition will additionally contain the mapping of different products’ technical policy rules to the tests that check the policy compliance, thus bridging the OSCAL compliance as code into the policy as code (see Figure 7). These PVP checks, once deployed within an operational compliance center, will generate at run-time the compliance posture OSCAL system assessment results. (The compliance assessment runtime activities following the compliance documentation authoring Git-based activities will be detailed in a future blog post on the PVP Exchange Protocol). All these mappings described here from controls to policy rules to policy checks are aiming to deliver the key support for compliance automation, end-to-end from the broadly defined regulatory controls to the technology-specific policies. With this traceability in place, we are now able to automatically aggregate policy result status (e.g., pass, fail) across products, services, and capabilities into the posture of the regulatory controls (e.g., satisfied, not satisfied) for the consumption of the Assessors, Compliance Officers, and Auditors.

 Component Definition spreadsheet and its OSCAL format for the authoring of checks itemized elements.

Figure 7: Component Definition spreadsheet and its OSCAL format for the authoring of checks itemized elements. Component type “Validation”.

CISO and System Owners – Control Operators and Their System Security Plan

We have reached the end of our journey where, given all the compliance controls guidance, resolution, and implementation documentation in place, CISO and System Owners now need to provide for audit purposes the control responses for their overall system and the status of the various components in the system. This information is captured in the System Security Plan (SSP) document which Trestle automatically generates for a given profile and an optional list of components (by default all the components), from the OSCAL profile and corresponding catalog and component definitions. Trestle provides a partial SSP as both Markdown format, open to editing, and its converted OSCAL SSP format as shown in Figure 8.

System Security Plan markdown and OSCAL format

Figure 8: System Security Plan Markdown and OSCAL format

For a full SSP, we would need a reference architecture or an actual deployed environment to produce the SSP system characteristics elements and system-implementation inventory or bill of materials. Given that cloud providers typically leverage reference architectures, CISO can use them to create templates of system characteristics and system implementation based on the components and capabilities included in the said cloud reference architectures. 

Note that the NIST OSCAL team is working on additional capabilities to the component definition and SSP schemas to support policy rules as first-class citizens, including rules-to-checks mapping. We are currently using the generic props element as available in the current OSCAL release 1.0.2 to declare the rules and the validate component type to declare the mappings to checks as a workaround until the new OSCAL support for policy declaration. In the same vein, the NIST OSCAL team is also working on the components’ parameters declaration support in the component definition. Hence, we are currently repurposing the set parameters to this end and using the same name for the rule parameters (e.g., a service configuration argument) and the check parameters, until we get the OSCAL support for parameters mapping between component service type and validation type.

Trestle Repository Story

Trestle enables the compliance personas to collaborate on authoring each of the compliance artifacts in their own Git repositories, via various means such as Markdown and spreadsheets, and generates the corresponding OSCAL formats. However, to enable change propagation across repositories, we need to link them so that whenever an artifact in an upstream repository changes, the downstream repositories are notified so that they can merge the upstream content and take suitable actions in their own repo. For example, if a new control gets added to a catalog, the related profile repositories are notified so that they can update to the latest version of the catalog by including the new control as relevant. Figure 9 shows the dependencies between various repos that are set when using Trestle Git workflows to propagate changes downstream.

 End-to-end dependencies between various repos that are set when using Trestle Git workflows to propagate changes downstream

Figure 9: End-to-end dependencies between various repos that are set when using Trestle Git workflows to propagate changes downstream

Trestle also has utilities to convert various OSCAL models into human-friendly formats such as HTML, spreadsheets, Word docs, and PDFs. This is used for cases such as publishing control guidance information on a website, sending SSP documents to an auditor or a reviewer, etc.


In this blog post, we described the compliance-as-code artifacts that different personas need to create and edit and specified their corresponding machine-readable format in OSCAL standard. We also described how Trestle supports collaborative compliance-as-code authoring via various interfaces to suit the variety of the personas’ skills. It then converts these into OSCAL format for compliance interoperability and automation. An important thing to note here is that the downstream artifacts are linked to upstream artifacts to maintain traceability.

What’s Coming Next?

As a system owner, one is responsible to subscribe to services, purchase products, and follow prescribed processes to maintain compliance with their systems in the well-defined regulated environment. We will describe in our next blog posts how to author policy as code, how to transition from the compliance and policy authoring Git-based activities to compliance assessment runtime activities in an operational compliance center, and how the results from various assessors’ tools with their different native interfaces can be integrated to generate standard assessment results artifacts via our OSCAL-based Exchange Protocol. 

Learn More

If you would like to use our open-source Trestle SDK then see compliance-trestle to learn about various trestle CLIs and their usage. For more details on the Markdown formats and commands for authoring various compliance artifacts, see this tutorial from Trestle.