"Go-to" tool for UUID generation and refreshing

[joshualubell]

User Story

I'm using the OSCAL catalog and profile models to creating Cybersecurity Framework Profiles. I want an easy-to-find, easy-to-use NIST-maintained tool for generating and refreshing UUIDs. This is critical, since UUIDs are required in multiple places in OSCAL profile and catalog content.

The only NIST-supported tool that serves this purpose is in the XSLT-Tooling repo, requires that I use an XSLT processor, and the README documentation is more complicated than what I need, i.e., it covers a lot of stuff besides UUIDs. And the NIST OSCAL website doesn't even mention that XSLT-Tooling includes UUID stuff among its capabilities.

I wish the OSCAL Java Command Line Tool had a UUID option. Then I could use the same tool for doing many basic tasks: XML/JSON conversion, profile resolution, and UUID generation/refreshing as well!

Goals

I want a NIST-provided functionality for generating/refreshing/maintaining UUIDs with a simple-to-use CLI interface (including a ''--help'') option. Ideally, this functionality should be part of the OSCAL Java Command Line Tool, which I already use for XML/JSON conversion and for profile resolution.

Dependencies

No response

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.

(For reviewers: The wiki has guidance on code review and overall issue review for completeness.)

Revisions

No response

[aj-stein-nist]

Thanks for opening this. Given the request is for oscal-cli, I will transfer for the issue there. Stay tuned for comments and status updates as this gets designed and implemented.

[david-waltermire]

@joshualubell This feature request doesn't indicate how the refresh should work.

Is the intent to update all UUID fields or just a targeted field (perhaps using a Metapath)?

Also, how is the UUID determined? Is it a version 4 random UUID or as version 5 SHA-1 based UUID that is based on a hash of the objects contents?

We need to answer some of these design decisions before such a command could be produced.

[joshualubell]

Honestly, I haven't given any thought to my personal UUID requirements. I just want my OSCAL content to be valid, and I want CSF informative references to point to their authoritative source. I guess at a minimum, for my purposes, I would want to be able to generate the following UUIDs for an OSCAL profile representation of a CSF profile: * @uuid for <profile> element * @uuid for each <resource> in <back-matter> I would also want any attribute values that reference a UUID to be refreshed/regenerated whenever any of the above UUIDs is generated for the first time or is changed. For example, a collection of informative references to SP 800-53 controls should reference the UUID of the resource whose <rlink> has an @href pointing to the SP 800-53 DOI. Does this help? Josh Joshua Lubell Systems Integration Division Engineering Laboratory National Institute of Standards and Technology Gaithersburg, Maryland, USA From: David Waltermire ***@***.***> Sent: Friday, September 15, 2023 10:50 AM To: usnistgov/oscal-cli ***@***.***> Cc: Lubell, Joshua (Fed) ***@***.***>; Mention ***@***.***> Subject: Re: [usnistgov/oscal-cli] "Go-to" tool for UUID generation and refreshing (Issue #191) @joshualubell<https://github.com/joshualubell> This feature request doesn't indicate how the refresh should work. Is the intent to update all UUID fields or just a targeted field (perhaps using a Metapath)? Also, how is the UUID determined? Is it a version 4 random UUID or as version 5 SHA-1 based UUID that is based on a hash of the objects contents? We need to answer some of these design decisions before such a command could be produced. - Reply to this email directly, view it on GitHub<#191 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ACRBFFS6A5DXFMFQKIJ4YXDX2RTKLANCNFSM6AAAAAA4YTEZL4>. You are receiving this because you were mentioned.Message ID: ***@***.******@***.***>>

[aj-stein-nist]

At the very least, shouldn't we start with:

1. a CLI argument (perhaps --update-document-uuid) that will allow the user to force a new UUID for the top-level OSCAL document (e.g. catalog, profile, component definition, SSP, etc.; the liboscal-java/oscal-cli code treats them in this way almost identically)
2. another CLI argument (perhaps --detect-uuid-update) where, given certain impactful UUIDs changing in a document, this warrants automatically updating the top-level UUID since embedded UUID identifiers changing would trigger a top-level change given our current developer guidance?

A stretch goal of 2 is allow for an alternative to a default handler in liboscal-java such that developers could add or extend the default behavior for what necessitates a top-level document UUID change, but I am not sure that is the best place to start. Thoughts?