Introducing Rx and Howser: Compliance Automation Made Easy
Devin Smith – Software Engineer
When writing safety-critical software, demonstrating compliance with a set of guidelines can present a formidable challenge. For example, when applied to a standard like ISO 26262 (an international functional safety standard of a vehicle’s safety-critical components) compliance can only be shown through exhaustive evidence. Up to this point, creating this kind of evidence has required meticulous manual reviews and continuous cycles of explicit sign-offs, ultimately generating a mountain of paperwork.
Large companies solve this paperwork problem by hiring functional safety engineers–sometimes by the hundreds. As a startup that values its agility, we needed a way for these documents to be the natural byproduct of our normal engineering process, eliminating the need for additional resources. We’re currently developing a method of automating the entire process to achieve the same level of assurance without wading through the bureaucratic elements.
As part of our solution to automate the generation of compliance documentation we built two open source resources: Rx and Howser. Rx is a DSL (Domain Specific Language) that defines a document's structure and content using "prescription" files which act as a blueprint of sorts. These prescription files can then be used to measure whether or not a plain Markdown file conforms to the “blueprint.” Howser is a tool that performs this validation by comparing each block of a document against an Rx prescription, identifying the areas where the requirements haven’t been met. By writing prescriptions for all of our engineering documentation, we have a way to ensure that certain types of information necessary for ISO compliance will be present in predictable locations while allowing the actual format of our documentation to reflect our workflow rather than the format prescribed by ISO 26262.
Using literals and tokens, Rx prescriptions can be used in conjunction with Markdown's standard block and inline elements. While the meaning of a token depends on the kind of Markdown element it’s used with.
For example, a prescription file with
# We're off to see -!!- The -!!- of -!!-.
would match the Markdown file
# We're off to see the wizard The wonderful wizard of Oz.
# We're off to see The dentist because our teeth are full of cavities.
because the literal tokens have not been satisfied.
When it comes time to generate compliance documents, we can leverage the fact that all of our engineering documents must conform to a consistent structure in order to predictably extract the necessary information to produce ISO 26262 compliance paperwork. Since measuring document conformance is integrated into our build pipeline, we can produce some forms of documentation for every successful build at no extra cost. Conversely, we can prevent builds of our software from advancing and reaching production if compliance hasn't been met. Including these kinds of compliance checks in our continuous integration process allows us to catch potential issues quickly and early. In using Rx and Howser, our ISO documentation becomes a natural byproduct of our software development life cycle, significantly reducing the time and paperwork associated with generating compliance documents. Not only does this save us time and resources, but these tools also instill greater confidence in the quality of our documentation.
Share Devin's post: