Select Page

COMPASS Part 2: Trestle SDK

Anca Sailer
Published: September 16, 2022

In part 1 of this multi-part blog series on continuous compliance, we detailed the personas and their role in the compliance processes. We concluded that the key to achieving compliance automation and hence continuous compliance is the compliance artifacts programmatic representation, as code, expressed in generic and standard security language terms.

In this blog post, we introduce Trestle, our open-source implementation of the NIST Open Security Control Assessment Language (OSCAL) standard framework adopted as a workflow automation of compliance artifacts managed as compliance as code. Trestle enables those diverse personas to collaboratively author the compliance artifacts and offers a platform and OSCAL SDK for teams to automate their specific native processes and formats. Trestle implicitly provides a core opinionated workflow driven by its pipeline to allow standardized interlocks with other compliance tooling platforms.

What Is OSCAL?

Open Security Control Assessment Language (OSCAL) is a National Institute of Standards and Technology (NIST) standard which provides a compliance framework. The corresponding set of key compliance artifacts expressed as compliance as code in XML, JSON, and YAML. OSCAL is like a Rosetta Stone that enables tools and organizations to exchange compliance information via automation.

As illustrated in Figure 1, the OSCAL compliance artifacts provide a machine-readable representation of control catalogs, control profiles or baselines, system security plans, assessment plans, assessment results, and plans of actions with full traceability of the encompassing compliance elements across the artifacts. For instance, the reference of a control in a system security plan or plan of action is traceable to the control element in the originating regulatory catalog source, and its associated baseline. 

 NIST Open Security Control Assessment Language (OSCAL) framework layers and corresponding compliance artifacts

Figure 1: NIST Open Security Control Assessment Language (OSCAL) framework layers and corresponding compliance artifacts

The reason behind selecting the NIST OSCAL compliance as code standard to support compliance automation is that although one may have certain aspects of the compliance processes already automated, such as evidence collection, posture monitoring, prevention, enforcement (remediation), or audit reporting, with some representation as code, those siloed automations typically do not fully support an enterprise-wide end-to-end continuous compliance, as follows. 

  • In case the standardization is missing, it is restricting the enterprise-wide posture aggregation since each tool will generate posture results in a different format. 
  • If the mappings of evidence to checks to technical rules, parameters, to controls are missing, the automation is only partial and manual intervention is needed to achieve the end-to-end flow. 
  • Moreover, if there is no specific owner of an artifact or the wrong owner, the automation is delayed, or simply stuck waiting for resource allocation or for the wrong owner to acquire the expertise to provide that artifact. 
  • Lastly, if the representation as code does not natively include ontology support, the translation between the taxonomy of the various tools involved in providing similar artifacts becomes the burden of the continuous compliance provider.

Therefore, it was critical to choose a representation “as code” that addressed all these dimensions, particularly end-to-end artifacts mapping and ownership support, for authentic enterprise-wide continuous compliance. Hence, our choice of OSCAL for compliance as code.


Trestle is an open-source OSCAL SDK and an ensemble of tools that enables the creation, validation, and governance of documentation artifacts for compliance authoring in general and for compliance automation as our targeted use case. As shown in Figure 2, at the core it has OSCAL framework models as Python classes converted directly from the OSCAL schema to enforce strict constraints on the classes based on the schema. Next, we have an adapter that converts OSCAL documents into Python objects and vice-versa. These two components enable manipulating OSCAL documents as Python objects ensuring that the integrity of OSCAL models is maintained at runtime.

Trestle Layered Architecture

Figure 2: Trestle Layered Architecture

On top of this core functionality, we have tools for creating, editing, splitting, merging, and validating OSCAL documents while ensuring that all these changes are compliant with the OSCAL schema. Since it is hard to manipulate JSON documents manually, Trestle provides content authoring tools for creating and editing OSCAL documents as markdown files. It also has a set of transformers for converting data from different formats such as spreadsheets, tool-specific JSON format, etc. to OSCAL format. This enables bringing external content into a format suitable for interchanging with other compliance tools. Trestle’s functionality can also be extended via plugins.

Managing Compliance Artifacts as Code Using Trestle

Trestle uses an opinionated directory structure similar to git to manage various compliance artifacts as code and related workflows. Most of the Trestle CLIs that directly manipulate OSCAL models work on top of this directory structure. As outlined in the documentation, the Trestle CLI has three primary use cases:

  1. Serve as tooling to generate and manipulate OSCAL files directly by an end user: The objective is to reduce the complexity of creating and editing workflows. Example commands are: trestle import, trestle create, trestle split, and trestle merge.
  2. Act as an automation tool that, by design, can be an integral part of a CI/CD pipeline, e.g., trestle validate, trestle tasks
  3. Allow governance of markdown documents so that they conform to specific style or structure requirements.

Apart from the basic commands for importing an existing OSCAL model into the Trestle workspace and validating it, Trestle also provides functionality to manage large OSCAL files as fragments in a directory tree. As OSCAL models can run into tens of thousands of lines of formatted JSON files, they become completely unmanageable for users. To combat this, Trestle provides a command to split a large OSCAL file into fragments for easy editing which can then be merged, while still ensuring that the fragments are compliant with OSCAL schema. The figure below shows how to split a catalog into different groups and then merge them back.

Trestle CLI

Figure 3: Trestle CLI

Most of the existing compliance content maintained by various tools and processes is either in spreadsheet format or in tools’ native formats. These contents need to be converted to OSCAL format for automation. For this, Trestle provides a set of tasks and transformers that can be used to convert these into OSCAL. For example, Trestle has a transformer for converting Tanium results data in its native format to OSCAL format, details for which are described in the tutorial, “Setup for and use of Tanium to OSCAL transformer.” Similarly, it has other transformers and tasks for converting spreadsheet data into OSCAL component definition format. Additional transformers can also be added easily to Trestle for transforming other data to OSCAL format. Refer to the tutorial that describes how to create a new transformer in Trestle.

Trestle also has authoring tools that convert OSCAL documents into small markdown files that are easy to read and edit by humans. The markdown files can then be assembled and converted back into JSON format to re-generate a new OSCAL document with those edits. These operations are supported through command line tools that let one break apart, edit, and recombine documents while ensuring that all changes are consistent with the OSCAL schema. The Trestle tutorial on content authoring provides details on the usage of these commands and markdown formats.

Trestle command line tools can be used with GitOps-based processes to maintain a single, traceable source of truth for all compliance documents and artifacts in Git repositories. This enables an effective change management process. The authoring tools are designed to work in a CI/CD environment where changes are made in a pipeline by people with different responsibilities and authority. In this setting, changes to documents can trigger changes downstream, e.g., the editing of a control would cause an update in the catalog, which could then flow down to an updated SSP. Git repositories keep track of changes, errors are avoided, and manual human input is avoided. Further, compliance requirements prescribe that only certain people should be able to make certain changes. User privileges in CI/CD pipeline operations enforce such user rights in a natural way. 


In this blog post, we described our open-source OSCAL SDK called Trestle which provides tools for editing and manipulation of OSCAL documents and managing these compliance artifacts as code in a git repository for enabling the compliance-as-code paradigm. Trestle is suitable for both humans by enabling markdown support for compliance artifacts, and for automation by providing CLIs to be used in CI/CD workflows.

What’s Coming Next? 

In addition to direct editing and manipulation of OSCAL documents as described in this blog, Trestle provides three separate but related capabilities in the compliance space:

  • Provide support for agile authoring of compliance artifacts as markdown content and its conversion to OSCAL format
  • Transform documents from other formats to OSCAL: The Trestle SDK providing this capability enables the integration of 3rd party assessment tools with Trestle or any Governance, Risk, and Compliance framework.
  • Provide support and governance to author-governed content such as architectural documents, design decisions, etc. as markdown and DRAWIO files and their related workflows.

Our next blogs will cover each of these Trestle capabilities in detail.

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. To see Trestle in action, explore various Trestle demos to learn more about how to use the different capabilities of Trestle.