Dataset Versioning in Catalogs

[ohsh6o]

User Story:

As an OSCAL developer, I want to explicitly explain what dataset (NIST 800-53, ISO-27001 respectively) and which version of that dataset (respectively 4.0 and 5.1; ISO/IEC 27001:2013 and ISO/IEC 27001:2018) is the source of the catalog and resolved profile catalog without using human interpretation of semantic context, or externalized file and directory naming.

Goals:

When processing catalogs in software, especially beyond the pre-existing oscal-content resources, especially beyond SP800-53 baselines, ETL pipelines cannot rely on explicit file and directory names. Introspecting the content of an OSCAL catalog and resolved profile catalog, the closest to understanding the catalog's content is "800-53 Revision 5, version 5.1 from NIST specifically" requires reading in file names or free-form title text values. This is achievable, but runs counter the objectives of OSCAL with structured, machine-readable content.

First-Order Question and Goal

First order problem: within a given document, how do we determine the origin (provenance) and that origin document’s version when referenced in a particular document?

• We currently have //metadata/version
• Maybe not a defined way to determine provenance
• document-id exists but may not be sufficiently
• This other idea
  • “Is this document 800-53?” “Or 800-53 Rev 5?” “Is it ISO-27001?” or “ISO/IEC 27000:2018 or ISO/IEC 27000:2013?”
• Maybe we need a series or dataset prop to clarify questions like: “is this document 800-53?”
  • Continue the version to answer questions like: “Or 800-53 Rev 5?” “ISO/IEC 27000:2018 or ISO/IEC 27000:2013?”

Second-Order Question and Goal

Second order question: In a resolved profile catalog, how do I know the provenance of the profile the new profile is based off of?

• In the vanilla profile, it is present.
• It is not in the resolved profile, we can mark the source profile
• Might be nicer to insert that in the resolved profile
• Work commentary for this question and effort into: Profiles when resolved should show their provenance #680

Dependencies:

• For the first order question, there would need to be potentially new props
• For the second order question, there would need to be enhancement to the profile resolution standard and OSCAL implementation

Acceptance Criteria

• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

{The items above are general acceptance criteria for all User Stories. Please describe anything else that must be completed for this issue to be considered resolved.}

[ohsh6o]

We discussed this today in the model meeting and a few pieces of feedback or other impressions on this work came up.

• Is this a deficiency in the current Metadata model: yes, no, or maybe?
• Can we just add additional prop elements to metadata for dataset-name and dataset-version and the like?
• @rgauss had some interesting insights into potentially refining this further to match a Maven-like POM structure with group, artifactId, and version.
  • More interesting is: can this be the first parts of an open public catalog/profile registry and this question, and going further with Maven like metadata, would take it a step further.
• @mosi-k-platt had some interesting insights into the applicability here for UCF but I know more of them in respect to accredited mapping of compliance controls, I would like to hear more about how this fits in.

[david-waltermire]

@ohsh6o Do you have an update to this proposal based on your notes above?

[ohsh6o]

@ohsh6o Do you have an update to this proposal based on your notes above?

I believe the last model meeting we had, I believe consensus would be to keep as close to the current v1.0.0 models (with a o:prop) as possible. The main issue is the profile resolution pipeline changes. I presume we can discuss in the meeting today, @david-waltermire-nist ? :-)

[david-waltermire]

@ohsh6o Can you create a concrete change proposal listing each property to add and providing a corresponding definition. We talked about organization name (or party reference), dataset-name, and dataset-version on the 7/9/2021 model review.

How do we point to the dataset-source? Maybe by a reference to a backmatter resource? This would allow a cryptographic hash to be included.

How do we handle multiple source datasets? Perhaps by multiple backmatter references?

@ohsh6o Will draft an updated proposal that will address this. @david-waltermire-nist will assist.

[ohsh6o]

So following up on this comment in anticipation of tomorrow's meeting, I am going to recommend:

• Add a link/@rel="dataset-source for catalogs and profiles and point that to one or more back-matter/resources.
• Add the following props for the back-matter/resources to match previously discussed expectations:
  • @name="dataset" @class="collection" to represent a grouping, such as how NIST has Special Publications (SP) versus Internal Reports (IR).
  • @name="dataset" @class="name" to give the specific dataset a particular name.
  • @name="dataset" @class="version" to give the dataset a logical version, such as "5" for Revision 5.
  • @name="dataset" @class="organization" which I am torn over: using a UUID to the relevant /metadata/party/@uuid or a reverse DNS record notation to allow optional grouping the organization that provided the source material; I prefer the latter since it might allow build primitives similar to dependency/package-management tools.

This recommendation would allow for 0 to ∞ dataset-source elements and, with recommended to profile resolution, would permit rudimentary tagging of dataset provenance for one or more sources and optionally tracing it through successive hops of resolution, but that can also be retrieved from a previous hop, if preferred.

<resource uuid="example-uuid">
         <prop name="dataset" class="collection" value="Special Publication"/>
         <prop name="dataset" class="name" value="800-53"/>
         <prop name="dataset" class="version" value="5"/>
         <prop name="dataset" class="organization" value="gov.nist.csrc"/>
</resource>

I have prepared some example code and a presentation for tomorrow.