Develop Tutorial #1: Creating a simple OSCAL control catalog

[iMichaela]

User Story:

As an OSCAL content developer, I need a clear and concise tutorial that illustrates how I can create a simple OSCAL control catalog

Goals:

Document how to generate an OSCAL controls catalog by generating a simple example while explaining in the process the syntax and the basic metaschema basics.

Dependencies:

none

Acceptance Criteria

• The tutorial is clear and concise.
• The example is representative, covering the most significant syntax.

[bradh]

I'd like to see this incorporated into the CI flow, including validation of the example output(s). That will ensure it says up to date as the schema evolves. Common for #592, #593, #594.

[iMichaela]

01/16/2020

The plan is to create a 'personalized' catalog from 1-2 controls from SP 800-53 and ISO/IEC and/or COBIT 5, in pdf, and then convert it to OSCAL showing/describing the elements in the catalog in this process. The settings, environment, and tools are not going to be discussed

[iMichaela]

2/6/2020

Back to this task after 2 weeks out of the office. Settled on a very small subset of ISO/IEC controls since we can use max 20% of the copyrighted catalog for academic purposes. Currently working on the OSCAL representation, which will be used as source for all tutoriasl.

[david-waltermire]

@iMichaela Can you post an outline of the tutorial illustrating the general prose flow of the tutorial? This will allow the OSCAL community to provide feedback on the organization of the tutorial content.

[iMichaela]

2/13/2020

The approach for developing the Catalog Tutorial has the following high-level steps:

1. Create a proprietary (small) catalog of controls using controls from ISO/IEC 27002
2. Convert the entire catalog in OSCAL (XML first, JSON second)
3. Validate the catalog to ensure the fragments captured in the tutorial are valid code
4. Structure the tutorial in a way that decomposes the content of the OSCAL catalog in the schema's elements.
5. Do not cover metadata in details, only highlight the mandatory elements
6. Detail the control structure with explanations of each field
7. Explain the use of nested controls
8. Explain the grouping of controls using group

Progress:
1, & 2 are done. working on validation (3). started 4 already (the top-level flow)

[iMichaela]

2/20/2020

The PR #626 with the catalog tutorial WIP was submitted.

[iMichaela]

3/5/2020

More progress on the tutorial was made this past week, after returning sick from business travel.

[david-waltermire]

The following is an example of what I was hoping this tutorial would look like: https://swagger.io/docs/specification/basic-structure/

This is for a different topic, but represents the basic flow/layout.

[iMichaela]

03/12/2020

Completed Catalog Tutorial. The PR #626 is ready for review.

[wendellpiez]

Update March 12

The team needs to review this: please find time to do so! (this week please).

[david-waltermire]

Will continue this work in #645.