Create OSCAL output using Metanorma Coradoc

Purpose

This repository contains an example on how Metanorma Coradoc can be used to author controls in a human-oriented markup language.

Background

The OSCAL catalog information model is highly structured and can be complex to create and manage without proper tooling.

For those who prefer a human-oriented markup format, Metanorma Coradoc supports creating OSCAL via AsciiDoc.

This repository provides a sample control from ISO/IEC 27002:2022 that demonstrates the usage of the following Rubygems to author OSCAL in AsciiDoc:

coradoc gem
oscal-ruby gem

Usage

Setup

Clone this repository.

git clone https://github.com/metanorma/coradoc-oscal.git

Install prerequisites

bundle

Generate OSCAL from AsciiDoc

The following command converts an .adoc file into a .yaml (OSCAL YAML).

bundle exec convert.rb {asciidoc-file-name}

The file sample.oscal.adoc is provided in this repository for testing purposes. The following command converts sample.oscal.adoc into sample.oscal.yaml.

bundle exec convert.rb sample.oscal.adoc
# => sample.oscal.yaml created

API usage

For those who wish to use the Ruby API, it is possible to directly call the following method to convert their OSCAL AsciiDoc file into OSCAL in YAML.

> require "coradoc"
> Coradoc::Oscal.parse_to_yaml("sample.oscal.adoc")

The sample.oscal.adoc file is excerpted from the OSCAL version of the "ISO/IEC 27002:2022 Information security controls".

Note	ISO/IEC 27002:2022 is copyrighted content.

The document is structured in the following way:

== Group One

=== Clause One
==== Part One
==== Part Two

=== Clause Two
==== Part One
==== Part Two

== Group Two
=== Clause One
==== Part One
==== Part Two

=== Clause Two
==== Part One

metanorma/coradoc-oscal