Review and Tech Edit of the Model Documentation

[david-waltermire]

Committer Notes

For issue #212, this PR provides edited catalog and profile model documentation that more completely describes the use of the elements in these models.

All Submissions:

• Have you followed the guidelines in our Contributing document?
• 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]

Changes to Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you included examples of how to use your new feature(s)?

[david-waltermire]

This work has progressed to a point where we can merge this PR, and continue working on more documentation refinements in another PR before closing out #212.

[david-waltermire]

Please review the schema docs in this archive. Please focus your review on:

• Checking for spelling and grammatical errors.
• Looking for statements that are just flat wrong.

This schema documentation is still not great, but it is improved from before. I plan to continue to work on improving it during the early part of sprint 22, so don't worry about missing or inadequate documentation at this time.

[brian-ruf]

@david-waltermire-nist Overall this looks very good!

• 2nd bullet: The JSON schema is not v7, it's draft-07.
• 4h paragraph: "In future, we plan to" - missing "the" ("In the future...")

I don't know if this is within the scope of what you wanted reviewed or not. When I click the "Catalog Schema" link on the right, the introductory text for the Schema Reference is XML-specific. I have a few observations:

• It's not obvious/intuitive to click the JSON button on the right in order to see the JSON reference instead. (I realize you are using the convention of having an active button in color and an inactive button as grey, but it comes across more as a label than a button, and is disorenting because it also comes across as these are JSON-relevant labels. Especially since there is one in every section, even though they all do the same thing.)

- When I click the JSON button and get the JSON Sechema Reference, the last sentence in the first section still talks about - and links to - the XML Schema, rather than the JSON Schema.

• I was surprised to see the hash element and algorithm attribute. I thought we were leaving those out for now.

A few other notes that don't need to be addressed now, but should be considered for future revisions:

• I am able to understand what is being said here as a result of my time with the project. I am concerned some of the statements here are difficult to follow by those who are not close to the project.

• Related to above, I would suggest simplifying the terminology. Early in the description you talk about "schemas" written out into two different "expressions". You mention the "metamodel", and a "data model". Near the end, you mention "the models", and "each of the component models". I can follow it, but I'm concerned most outsiders won't be able to.

[iMichaela]

@david-waltermire-nist - The site looks great! Thank you, all!
Here are small things/suggestions (in addition to what @brianrufgsa pointed out:

1. Policy Authors page - I suggest capitalizing also (content creator) to read (Content Creator)
2. Case Studies page:
   - the sentence: "The National Institute of Standards and Technology’s Open Security Controls Assessment Language, which speeds up the security controls assessment process through standardization and automation, will be available for testing by the end of this fiscal year, FedRAMP Director Matt Goodrich said at the June 13 ATARC Federal Cloud and Data Center Summit." needs the year specified, either "June 13, 2019" or 'by the end of 2019 fiscal year'.
   - the sentence "Goodrich also provided an update on FedRAMP Tailored, a streamlined approval process for low-impact software-as-a-service offerings. He said 15 SaaS offering
   s are currently in process for authorizations with three already approved." - can be removed since it is not linked to OSCAL
   - the sentence "To address these requirements, Docker has collaborated with the National Institute of Standards and Technology (NIST), and today, we are excited to announce that Docker is fully embracing the Open Security Controls Assessment Language (OSCAL) standard and committing to its future development. OSCAL is a machine-readable, “standard of standards” that normalizes how system security controls and corresponding assessment information are represented. Its goal is to improve the efficiency, accuracy, and consistency of system security assessments and enable a large decrease in assessment-related labor. OSCAL gives users the ability to assess a system’s security state continuously and against several sets of requirements simultaneously. The OSCAL specification is designed with security and agility in mind. It is both XML- and JSON-based, is technology and infrastructure-agnostic, and is incredibly flexible in its use." should be at present continuous and not past... and have quotes if constructs as : 'today, we are excited to announce" are used. This is necessary because we as in NIST cannot represent Docker. I also suggest removing the sentences in italics because they do not describe anything specific to this case and the information is repeatative.
3. Page Scenarios - needs a little re-writing to not focus on compliance with FISMA since FISMA promotes a risk-based approach and provides requirements than need to be met. I can do the re-write tomorrow afer 10:00am. Also C&A has been dropted and replaced with A&A.
   --- More reviews tomorrow morning after 10:00am.

[iMichaela]

@david-waltermire-nist: Here are few additional comments. Due to our deadline constraints, please feel free to ignore the comments that are not OSCAL release-stoppers.
-- Page "Profiles": Sentence "There are also JSON versions of the NIST SP 800-53 rev4 profiles." should read "There are also JSON versions of the NIST SP 800-53 rev4 baselines." since profile is not a concept used in the NIST SP. Similar change is suggested for "There are also JSON versions of the FedRAMP profiles." down the same page.
--- Page "Concepts":
--- the statement "A catalog is a set of security control definitions. Examples include the controls in NIST SP 800-53, ISO 27001, HIPAA, and PCI.". Health Insurance Portability and Accountability Act of 1996 (HIPAA) is a law that consists of 5 'titles.Title 2 addresses, among others the 'security rules'. So, HIPAA, like FISMA, cannot be referred in the same context with security controls. The sentence could read: " Examples include the controls in NIST SP 800-53, ISO 27001, **HIPAA security and privacy rules". Payment Card Industry Data Security Standard (PCI DSS) is the information security standard (please add DSS) provides 'requirements' and not controls.
--- the statement: "Examples include the control baselines in NIST SP 800-53, the FedRAMP baselines, NIST SP800-171 (a controls baseline for CUI/NFO), and the PCI DSS requirements" has 2 problems:
a) PCI DSS is listed as profile example but also as catalog example. It cannot be in both places as listed. If PCI DSS is represented using the OSCAL catalog, then only a customized subset of requirements would use the OSCAL profile to be represented in machine readable format. Page "Concepts -> Profile" discusses also PCI DSS as profile. Need consistency, based on the clarification on this page.
b) NIST SP 800-171 provides federal agencies with a set of recommended security requirements for protecting the confidentiality of Controlled Unclasified Information (CUI). The requiremetns are mapped to 800-53 controls in the SP 800-171, with one-to-many relations (more of a framework type). DO WE SUPPORT IN THE OSCAL PROFILE, AT THIS TIME, SUCH RELATIONS? DID WE TEST? If not, maybe we should not include 800-171 at thsi time. THOUGHTS?

AS A MORE GENERAL RULE - in this page in particular, abreviations are used before they are spelled out.

NOTE: I am provided the comments incrementally - I still have to review Schema Reference.

[brian-ruf]

See separate comment with my changes. Some are optional, or could be deferred, but some should be addressed now.

[david-waltermire]

@brianrufgsa I made the following changes:

@david-waltermire-nist Overall this looks very good!

* 2nd bullet: The JSON schema is not v7, it's draft-07.

Fixed.

* 4h paragraph: "In future, we plan to" - missing "the" ("In **the** future...")

Fixed.

I don't know if this is within the scope of what you wanted reviewed or not. When I click the "Catalog Schema" link on the right, the introductory text for the Schema Reference is XML-specific. I have a few observations:

I rewrote the intro paragraph to be more neutral. Once I post updated content to this issue, please give it another look and let me know what you think.

* It's not obvious/intuitive to click the JSON button on the right in order to see the JSON reference instead. (I realize you are using the convention of having an active button in color and an inactive button as grey, but it comes across more as a label than a button, and is disorenting because it also comes across as these are JSON-relevant labels.  Especially since there is one in every section, even though they all do the same thing.)

Not sure how to address this. Can you create an issue for this? We can consider what to do in the next sprint.

- When I click the JSON button and get the JSON Sechema Reference, the last sentence in the first section still talks about - and links to - the XML Schema, rather than the JSON Schema.

I removed this text. I will talk with @wendellpiez about adding a general capability to link to the relevant schema.

* I was surprised to see the hash element and algorithm attribute. I thought we were leaving those out for now.

IMHO, we modeled it, so no harm in keeping it.

A few other notes that don't need to be addressed now, but should be considered for future revisions:

* I am able to understand what is being said here as a result of my time with the project. I am concerned some of the statements here are difficult to follow by those who are not close to the project.

I agree. This will be the focus of future refinements to these docs.

* Related to above, I would suggest simplifying the terminology. Early in the description you talk about "schemas" written out into two different "expressions". You mention the "metamodel", and a "data model". Near the end, you mention "the models", and "each of the component models". I can follow it, but I'm concerned most outsiders won't be able to.

Hopefully, my new intro paragraph will help, but we can do a bunch of terminology cleanup going forward. Can you create a new issue raising these points?

Thanks for the comments!

[david-waltermire]

See separate comment with my changes. Some are optional, or could be deferred, but some should be addressed now.

For some reason, I can't see your requested changes. Can you jump on Gitter?

[iMichaela]

Here are the promised updates to the Scenario page (see comment above):
OSCAL - Scenario page updates.docx

[iMichaela]

@david-waltermire-nist - I am on gitter now - but my comments were submitted 13 hours ago (part 1), 4 hours ago (part 2) and then the file abnove (2 hours ago)- see above.