Component definition tutorial issue #854 #935
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
iMichaela
reviewed
May 25, 2021
| @@ -0,0 +1,335 @@ | |||
| --- | |||
| title: Creating a Component Definition | |||
| description: A tutorial on creating an OSCAL component definition. | |||
There was a problem hiding this comment.
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
reviewed
May 25, 2021
|
|
||
| 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: |
There was a problem hiding this comment.
A hyperlink to the MongoDB product's page could be useful. (e.g https://docs.mongodb.com/)
iMichaela
reviewed
May 25, 2021
|
|
||
| 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 |
There was a problem hiding this comment.
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
reviewed
May 25, 2021
|
|
||
| ## 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. |
There was a problem hiding this comment.
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
reviewed
May 25, 2021
| {{< tabs XML >}} | ||
| {{% tab %}} | ||
| {{< highlight xml "linenos=table" >}} | ||
| <?xml version="1.0" encoding="UTF-8"?> |
There was a problem hiding this comment.
Can the final example be validated? Should the tutorial indicate it? If not, should the tutorial explain why?
iMichaela
previously approved these changes
May 25, 2021
|
@Rene2mt Is the PR ready for the final review, or still a WIP? |
Rene2mt
changed the title
Yes, this PR is ready for final review |
Rene2mt
force-pushed
the
854-component-definition
branch
from
f3855c7
to
6a5460f
Compare
Rene2mt
force-pushed
the
854-component-definition
branch
from
d98f4ae
to
cd396a0
Compare
|
|
||
| ### Defining the Component Definition’s Metadata | ||
|
|
||
| Most OSCAL models have a standard metadata syntax, therefore, this is not covered extensively in this tutorial. There are a few considerations however when authoring metadata for a component definition, such as the `<role>`, `<location>`, and `<party>` elements illustrated in lines 9-18 below. |
There was a problem hiding this comment.
This is an XML-specific reference. Can you generalize this to work with any of the XML, JSON, or YAML examples below?
Comment on lines
126
to
129
| <location uuid="0db91129-35ed-474f-a25e-c3ff1e2cb9dc"> | ||
| <address /> | ||
| <url>https://www.mongodb.com</url> | ||
| </location> |
There was a problem hiding this comment.
This doesn't appear to be a physical location, which is what the location is intended for. A link would be a better way to make this association. Need to figure out what a good `rel would be for this.
Comment on lines
130
to
132
| <party uuid="ef7c799a-c50e-49ab-83e0-515e989e6df1" type="prepared-for"> | ||
| <name>MongoDB</name> | ||
| </party> |
There was a problem hiding this comment.
I don't think this matches the intended purpose of "prepared-for", which should be associated as a responsible-role maybe? We should talk more about how to capture the semantics of this in a better way.
There was a problem hiding this comment.
The type needs to be a "person" or "organization". This party should be the OSCAL project or something similar.
| </component-definition> | ||
| {{< /highlight >}} | ||
|
|
||
| The [`<role>`](/reference/latest/component-definition/xml-reference/#/component-definition/metadata/role) element defines a function assumed or expected to be assumed by a party in a specific situation. Common examples include [component definition authors](/concepts/layer/implementation/component-definition/#component-definition-authors) (e.g., Product and Service Vendors, Capability Owners, Policy and Process Owners, Standards Bodies and Validation Bodies) and [component definition consumers](/concepts/layer/implementation/component-definition/#component-definition-consumers) (e.g., System Owners and SSP Authors). This element has a required `@id` attribute which expects an [NCName data type](/reference/datatypes/#ncname). The `<location>` element can be used to associate the metadata with a location, including physical addresses and urls. The `<location>` element has a `@uuid` attribute which requires a UUID. Lastly, the `<party>` element represents either a person or organization that serves as the responsible entity. There are prescribed types, including *"prepared-for"*, *"prepared-by"*, and *"approved-by"*. |
There was a problem hiding this comment.
URLS are not intended to be locations. Similar issue for prepared-for. See above. We should discuss a better way to capture this.
Comment on lines
155
to
157
| "locations": [{ | ||
| "uuid": "0db91129-35ed-474f-a25e-c3ff1e2cb9dc", | ||
| "address": "", | ||
| "url": "https://www.mongodb.com" | ||
| }], | ||
| "parties": [{ | ||
| "uuid": "ef7c799a-c50e-49ab-83e0-515e989e6df1", | ||
| "type": "prepared-for", | ||
| "name": "MongoDB" | ||
| }] |
| } | ||
| {{< /highlight >}} | ||
|
|
||
| The [`roles`](/reference/latest/component-definition/json-reference/#/component-definition/metadata/roles) property provides a grouping of `role` objects that each define a function assumed or expected to be assumed by a party in a specific situation. Common examples include [component definition authors](/concepts/layer/implementation/component-definition/#component-definition-authors) (e.g., Product and Service Vendors, Capability Owners, Policy and Process Owners, Standards Bodies and Validation Bodies) and [component definition consumers](/concepts/layer/implementation/component-definition/#component-definition-consumers) (e.g., System Owners and SSP Authors). This element has a required `id` property which expects an [NCName data type](/reference/datatypes/#ncname). The `locations` grouping can be used to associate the metadata with any number of locations, including physical addresses and urls. Each `location` object has an `uuid` property. Lastly, the `parties` grouping property represents either persons or organizations that serves as the responsible entities. There are prescribed types, including *"prepared-for"*, *"prepared-by"*, and *"approved-by"*. |
Comment on lines
187
to
183
| locations: | ||
| - uuid: 0db91129-35ed-474f-a25e-c3ff1e2cb9dc | ||
| address: '' | ||
| url: https://www.mongodb.com | ||
| parties: | ||
| - uuid: ef7c799a-c50e-49ab-83e0-515e989e6df1 | ||
| type: prepared-for | ||
| name: MongoDB |
|
|
||
| {{< /highlight >}} | ||
|
|
||
| The `roles` item provides a grouping of `role` objects that each define a function assumed or expected to be assumed by a party in a specific situation. Common examples include [component definition authors](/concepts/layer/implementation/component-definition/#component-definition-authors) (e.g., Product and Service Vendors, Capability Owners, Policy and Process Owners, Standards Bodies and Validation Bodies) and [component definition consumers](/concepts/layer/implementation/component-definition/#component-definition-consumers) (e.g., System Owners and SSP Authors). This element has a required `id` property which expects an [NCName data type](/reference/datatypes/#ncname). The `locations` grouping can be used to associate the metadata with any number of locations, including physical addresses and urls. Each `location` object has an `uuid` property. Lastly, the `parties` grouping item represents either persons or organizations that serves as the responsible entities. There are prescribed types, including *"prepared-for"*, *"prepared-by"*, and *"approved-by"*. |
| <responsible-role role-id="supplier"> | ||
| <party-uuid>ef7c799a-c50e-49ab-83e0-515e989e6df1</party-uuid> | ||
| </responsible-role> | ||
| <protocol name="Transmission Control" /> |
There was a problem hiding this comment.
maybe represent this as an empty <protocol/> element? The name here isn't really discussed until the next section. Same for the other formats.
Comment on lines
319
to
321
| <port-range start="27017" end="27017" transport="TCP" /> | ||
| <port-range start="27018" end="27018" transport="TCP" /> | ||
| <port-range start="27019" end="27019" transport="TCP" /> |
There was a problem hiding this comment.
You should demonstrate using the name and title elements within a protocol. There should be an individual protocol for each port. The names should probably be mongod, shardsrv, and configsrv or something similar. The title would then be a human readable name for these services.
Co-authored-by: David Waltermire <[email protected]>
Co-authored-by: David Waltermire <[email protected]>
Co-authored-by: David Waltermire <[email protected]>
Co-authored-by: David Waltermire <[email protected]>
Rene2mt
force-pushed
the
854-component-definition
branch
from
d6271ab
to
38b2c07
Compare
david-waltermire
added a commit
to david-waltermire/OSCAL
that referenced
this pull request
Aug 27, 2021
Linked the tutorial in the learn and concepts sections of the website.
8 tasks
david-waltermire
added a commit
to david-waltermire/OSCAL
that referenced
this pull request
Aug 27, 2021
Linked the tutorial in the learn and concepts sections of the website.
|
This PR has been replaced by PR #1015. |
david-waltermire
added a commit
to david-waltermire/OSCAL
that referenced
this pull request
Aug 27, 2021
Linked the tutorial in the learn and concepts sections of the website.
david-waltermire
added a commit
that referenced
this pull request
Aug 27, 2021
- Addressed issue #854 creating a tutorial based on component definition content from PR #935. - Linked the tutorial in the learn and concepts sections of the website. - Adjusting deployment workflows. - Adding new website GitHub actions workflow. - Adjusting workflows to decompose specific activities. Co-authored-by: Rene Tshiteya <[email protected]> Co-authored-by: Rene2mt <[email protected]>
david-waltermire
added a commit
that referenced
this pull request
Sep 7, 2021
- Addressed issue #854 creating a tutorial based on component definition content from PR #935. - Linked the tutorial in the learn and concepts sections of the website. - Adjusting deployment workflows. - Adding new website GitHub actions workflow. - Adjusting workflows to decompose specific activities. Co-authored-by: Rene Tshiteya <[email protected]> Co-authored-by: Rene2mt <[email protected]>
3 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Committer Notes
Component definition tutorial ready for review.
All Submissions:
Changes to Core Features: