Component definition tutorial issue #854 #935

Rene2mt · 2021-05-21T18:31:08Z

Committer Notes

Component definition tutorial ready for review.

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]
Do all automated CI/CD checks pass?

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)?
Have you updated all OSCAL website and readme documentation affected by the changes you made? Changes to the OSCAL website can be made in the docs/content directory of your branch.

iMichaela · 2021-05-25T16:07:17Z

docs/content/learn/tutorials/component/_index.md

@@ -0,0 +1,335 @@
+---
+title: Creating a Component Definition
+description: A tutorial on creating an OSCAL component definition.


I wonder if adding "file" after 'component definition' would not help with better distinguishing between 'component definition model' (OSCAL model) and 'component definition file' (OSCAL content).

iMichaela · 2021-05-25T16:13:30Z

docs/content/learn/tutorials/component/_index.md

+
+A component definition describes how a given implementation of a component or sets of components (e.g., hardware, software, service, policy, process, or procedure) can support specific controls.  Product and Service Vendors, Capability Owners, Policy and Process Owners, and others can create component definitions that readily serve as inputs for a System Security Plan (SSP), helping describe how components might satisfy controls.  It is important to note that component definitions do not describe actual implementations. Component definitions serve as references with content that can be used (e.g., in the SSP OSCAL model) to develop comprehensive and consistent control implementations within an SSP.
+
+In this tutorial, we will walk through the process of creating an [OSCAL component definition model](/documentation/schema/implementation-layer/component/) for MongoDB.  Our goal is to provide standard control implementations for the benefit of system owners and SSP authors. As potential components in systems that may need to meet the OMB A-130 Authorization to Operate requirements, the component definition in this tutorial will demonstrate proper implementation of a couple [NIST SP 800-53 rev 5 controls](https://github.com/usnistgov/oscal-content/tree/master/nist.gov/SP800-53/rev5/xml) deemed necessary for high / moderate / low impact systems. While this example focuses on NIST controls, the same approach could be used for any cybersecurity frameworks and their respective controls.  We'll presume the MongoDB component can partially or fully satisfy the following controls:


A hyperlink to the MongoDB product's page could be useful. (e.g https://docs.mongodb.com/)

iMichaela · 2021-05-25T16:31:24Z

docs/content/learn/tutorials/component/_index.md

+
+For simplicity of this tutorial, we will only discuss certain data structures in the sections that follow and identify how they can be used to represent our component definition.
+
+## Defining the Component Definition’s Metadata


This title has a different structure than the "Component", and "Control-implementations".
Maybe making the titles for Metadata, Component, Control-implementations one 'header level down:

level 3 subsection as oppose to

level 2 which is the "Creating an OSCAL Component Definition Model"

would help structuring the content.

Similar for Protocol (sub-component of 'Component"

The "Catalog tutorial" uses different header levels.

iMichaela · 2021-05-25T16:42:04Z

docs/content/learn/tutorials/component/_index.md

+
+## The Final Component Definition
+
+Combining all the content described in this tutorial, we can produce this final component definition model.  Having these implementation details readily available in an OSCAL component definition means they can be referenced in an OSCAL SSP and should give SSP authors helpful content for their control implementation statements.


the statement reads: "means they can be referenced in an OSCAL SSP". I think the information is used to populate the SSP not to just reference it.

iMichaela · 2021-05-25T16:43:48Z

docs/content/learn/tutorials/component/_index.md

+{{< tabs XML >}}
+{{% tab %}}
+{{< highlight xml "linenos=table" >}}
+<?xml version="1.0" encoding="UTF-8"?>


Can the final example be validated? Should the tutorial indicate it? If not, should the tutorial explain why?

iMichaela

Please see the comments I inserted. They are not PR blockers, but I would appreciate it if you review and consider them. Pls let me know if you want to discuss them.

iMichaela · 2021-05-25T23:28:56Z

@Rene2mt Is the PR ready for the final review, or still a WIP?

Rene2mt · 2021-05-25T23:44:18Z

@Rene2mt Is the PR ready for the final review, or still a WIP?

Yes, this PR is ready for final review

docs/content/learn/tutorials/component-definition/component.md

david-waltermire · 2021-07-16T14:29:17Z