Create style guide for FedRAMP OSCAL Constraints

[aj-stein-gsa]

Committer Notes

Add the style guide for FedRAMP staff and community developers of Metaschema-constraints-based OSCAL requirements for digital authorization packages. Closes #675.

All Submissions:

• Have you selected the correct base branch per Contributing guidance?
• Have you set "Allow edits and access to secrets by maintainers"?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?
• Have you squashed any non-relevant commits and commit messages? [instructions]
• Have you added an explanation of what your changes do and why you'd like us to include them?
• If applicable, does this PR reference the issue it addresses and explain how it addresses the issue?
• If applicable, have all FedRAMP Documents Related to OSCAL Adoption affected by the changes in this issue have been updated? This is developer documentation.

By submitting a pull request, you are agreeing to provide this contribution under the CC0 1.0 Universal public domain dedication.

[aj-stein-gsa]

@GSA/fedramp-oscal-contributors, before I proceed further on this I would like a temperature check. It is a little beyond draft, but would like feedback before considering the addition of other rules.

I have talked to @david-waltermire and he is definitely supportive of deeper integration work with the metaschema-cli to enforce these in CI/CD and backporting fixes to the existing 60-70 rules. I too can help with that.

[brian-ruf]

@aj-stein-gsa this looks like a great start!
FWIW, I view this as less of a style guide and more of a data guide.

A style guide would get more into language and presentation. (active voice, present tense, third person) and might provide a set of common terminology that ensures consistent descriptions. (vs. different people using synonyms or alternative names for the same thing)

I think this totally hits the mark of what we need, so I'm not questioning the work itself. Just what the work is called.

---

As for the work itself:

• I'm not sure I understand the point of FCSR-1 in that I believe FedRAMP has no choice but to define constraints external to the metaschema module since the metaschema definitions for OSCAL are owned by NIST. No organization should be inserting their own constraints and NIST should be enforcing that.

• I have concerns about FCSR-3 in that sometimes alphabetical isn't the best sequence. For example, Low, Moderate, and High would end up as High, Low, Moderate, which is more difficult to consume. Perhaps this should be revised from "MUST" to "SHOULD" and to favor alphabetical where no specific logical order applies.

As far as a temperature check, I think this is totally on the right track.

[aj-stein-gsa]

@aj-stein-gsa this looks like a great start! FWIW, I view this as less of a style guide and more of a data guide.

OK, that's useful feedback. I use the term style guide the way others document data and prose recommendations for a programming language or data format. That said, you are right: these too have prose requirements or recs.

Do you have in mind style guide recommendations we can act upon?

A style guide would get more into language and presentation. (active voice, present tense, third person) and might provide a set of common terminology that ensures consistent descriptions. (vs. different people using synonyms or alternative names for the same thing)

Sure do we think we have any that apply to constraints message language yet that are not controversial? I am fine with active voice, but do we have them?

I think this totally hits the mark of what we need, so I'm not questioning the work itself. Just what the work is called.

I understand, I tried to give a representative example of why I call it what I do: I do not prefer the Google ones, I just know they are commonly cited and followed once they make them public for Lisp (above); C++; Java; et cetera. I do see those, not surprisingly, have guidance on formatting and style of prose in comments and how variables are named and other guidance closer (not exactly the same as what you say), but I do understand your point.

Do you want to include the things mentioned above and keep the name and concept? Do you still want us to call it something else? I just do not have much of a strong opinion on that, but will string up testing and analysis to point to the file.

As for the work itself:

• I'm not sure I understand the point of FCSR-1 in that I believe FedRAMP has no choice but to define constraints external to the metaschema module since the metaschema definitions for OSCAL are owned by NIST. No organization should be inserting their own constraints and NIST should be enforcing that.

I do not disagree, but it is not really documented anywhere for FedRAMP staff on day one. Also, there OSCAL constraints that are not specific to FedRAMP, but remain external. We will evaluate and consider over the progression of our work if we upstream to NIST (they are not specific to FedRAMP and could/should be maintained by NIST eventually not us, depending on what their receptivity).

So that aside, if you had not prior knowledge, I am not sure how else we can document that principle for people when they ask why.

• I have concerns about FCSR-3 in that sometimes alphabetical isn't the best sequence. For example, Low, Moderate, and High would end up as High, Low, Moderate, which is more difficult to consume. Perhaps this should be revised from "MUST" to "SHOULD" and to favor alphabetical where no specific logical order applies.

Currently, we do not include any information in the constraints about this data yet. If so, how would we sort on that? I would rather not organize on <!-- BLOCK COMMENTS, MANY LINES LONGER THAN THIS EXAMPLE --> is not good for code linting/sorting.

I only point this out because some of these things I would look to be augmented by tooling. Thus, I propose sorting by context path (highest level of the model, to specific deep into the "tree" of instance data related to a given model) and then within that alphabetically to make it easy for the developers to search on places to add, change, or remove. I am all for different presentation layer. I am not sure if you mean how they are developed, how they are presented, or both.

If you have ideas about this, I want to be clear: I am not saying no and dismissing them. If you have ideas at this point, I would like to hear them. If not not now, I am totally supportive of ADRs to add an approach once we come up with one and we like it. It doesn't only have to be now.

As far as a temperature check, I think this is totally on the right track.

That's good, but it seems like there is more work to be had, so keep your feedback coming, and look forward to hearing more from you and the rest of the crew.

[Rene2mt]

Nice work!!! Definitely on the right track. Not as urgent, but I propose we also add requirements for:

• FedRAMP constraints must have id - we can establish a naming convention (for consistency), uniqueness requirements, etc.
• FedRAMP constraints must have level, and specified values must be ERROR, WARNING, or INFORMATIONAL. We can clarify when to use a specific level. Not sure if we also want to include CRITICAL (I'm not clear on when to use CRITICAL vs ERROR)
• FedRAMP constraints must have message. Longer term, we can provide some style guidance so messages use similar terminology / sound consistent.
• Add guidance on when to add remarks
• We have the ability import constraints (e.g. have separate constraints files that can reference on another). We've avoided doing that so far, but we should come up with guidance for when or when not to split out constraints in separate files, and how to organize them.

[aj-stein-gsa]

Nice work!!! Definitely on the right track. Not as urgent, but I propose we also add requirements for:

All good recommendations, will work on these quickly then as I lunch!

[wandmagic]

we currently have a file for external constraints targeting oscal that are considered outside of fedramp scope. oscal-external-constraints.xml

At the moment the test runner ignores this file. Ignored because the responsibility of these constraints is outside the scope of this repo. They should eventually be moved upstream. if we determine that they ARE inside the scope, we should adjust the test runner to not ignore them (or move the constraints to another file)

this information should be included in the style guide

[aj-stein-gsa]

this information should be included in the style guide

I can definitely add that, excellent feedback!

[aj-stein-gsa]

At the moment the test runner ignores this file. Ignored because the responsibility of these constraints is outside the scope of this repo. They should eventually be moved upstream. if we determine that they ARE inside the scope, we should adjust the test runner to not ignore them (or move the constraints to another file)

I addressed this concern in f7dd4aa.

[aj-stein-gsa]

OK I think I address all high-level concerns from @Rene2mt's previous review and feedback.

Also, @brian-ruf I added a few (but not expansive) style guide requirements around prose in messages. Let me know what you think.

[brian-ruf]

@aj-stein-gsa This is really shaping up nicely!
I just have a few refinement suggestions:

1. In the Summary at the top, consider a list or table that just includes the ID, Formal Name, and possibly State (see below)
2. For the formal names, drop the "FedRAMP Requires" approach.
3. Consider an ID scheme and sequence that allows grouping and allows those groups to go. For example, I'd group FCSR-2 and 3 under a "Sequencing" group. I'd also group 5 and 6 as "Identifiers", as well as 9, 11, 12 and 13 as "Messages".

Sample Table for Summary Section with Suggested Formal Name Changes (Items # 1 and # 2)

ID	Formal Name	State
FCSR-1	External Constraints	Required
FCSR-2	Sort Constraints by Path	Required
FCSR-3	Sort Constraints Alphabetically	Required
FCSR-4	Include Help URL	Required
FCSR-5	Assign a Unique Identifier	Required
FCSR-6	Valid Identifiers	Required
FCSR-7	Assign Severity Level	Required
FCSR-8	Critical Severity Strict Limited Use	Required
FCSR-9	Violation Messages	Required
FCSR-10	Use Remarks for Clarity	Recommended
FCSR-11	Violation Messages in Active Voice	Recommended
FCSR-12	Use IETF BCP14 Keywords in Messages	Recommended
FCSR-13	Avoid Metaschema and OSCAL Jargon in Messages	Required
FCSR-14	Single Item Focus	Recommended
FCSR-15	Single Item Hints	Recommended
FCSR-16	Formal Names	Required

[aj-stein-gsa]

@aj-stein-gsa This is really shaping up nicely! I just have a few refinement suggestions:

1. In the Summary at the top, consider a list or table that just includes the ID, Formal Name, and possibly State (see below)
2. For the formal names, drop the "FedRAMP Requires" approach.
3. Consider an ID scheme and sequence that allows grouping and allows those groups to go. For example, I'd group FCSR-2 and 3 under a "Sequencing" group. I'd also group 5 and 6 as "Identifiers", as well as 9, 11, 12 and 13 as "Messages".

Thanks for great feedback, @brian-ruf. For 3, would you be amenable to, perhaps, the document have one or more labels/tags and those tools mentioning those instead of embedding them into the ID? The only reason I actually started with that early on and walked away is we can see the table and know there are a bunch in order "FCSR-1" to the last "FSCR-N", but with inserting the category/categories into the ID, you start have multiple 1s, 2s, 3s, et cetera. (e.g. fcsr-id-1, fcsr-message-1, fcsr-sequences-1; the list goes on). I am trying to learn from old bad habits, but if others really want to lean into this, I want to make it approachable to the group, not just me. 😄

[Rene2mt]

One non-blocking comment regarding the "security-level" constraint fix.

As for the guide, I think it looks awesome!!! We should move forward with it. We can add / update in the future if we think of other things to include or changes we want to make.