From 80e5c01e5123ac8e5a1c4e8250531679c6894ae9 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Fri, 19 Aug 2022 12:19:26 -0400 Subject: [PATCH] DRAFT: Update catalog & profile metaschema documentation (#51) Adjustments based on model review. * Update catalog & profile metaschema documentation * Add props to control identifier Co-authored-by: David Waltermire --- src/metaschema/oscal_catalog_metaschema.xml | 20 ++++++-- src/metaschema/oscal_component_metaschema.xml | 51 ++++++++++++++----- src/metaschema/oscal_profile_metaschema.xml | 38 +++++++------- 3 files changed, 76 insertions(+), 33 deletions(-) diff --git a/src/metaschema/oscal_catalog_metaschema.xml b/src/metaschema/oscal_catalog_metaschema.xml index 1ffcd51bd0..6c93690d65 100644 --- a/src/metaschema/oscal_catalog_metaschema.xml +++ b/src/metaschema/oscal_catalog_metaschema.xml @@ -53,9 +53,11 @@ The tool used to produce a resolved profile. + The document-level uuid of the source profile from which the catalog was produced by profile resolution. The profile from which the catalog was produced by profile resolution. + The document-level uuid of the profile from which the catalog was produced by profile resolution. @@ -146,8 +148,8 @@ -

Catalogs can use a group to collect related controls into a single grouping. That can be useful to group controls into a family or other logical grouping.

-

A group may have its own properties, statements, parameters, and references, which are inherited by all members of that group.

+

Catalogs can use the catalog group construct to organize related controls into a single grouping, such as a family of controls or other logical organizational structure.

+

A group may have its own properties, statements, parameters, and references, which are inherited by all controls of that are a member of the group.

 @@ -166,7 +168,12 @@ Control Identifier - A human-oriented, locally unique identifier with instance scope that can be used to reference this control elsewhere in this and other OSCAL instances (e.g., profiles). This id should be assigned per-subject, which means it should be consistently used to identify the same control across revisions of the document. + Identifies a control such that it can be referenced in the defining catalog and other OSCAL instances (e.g., profiles). + + + + + Control Class @@ -232,7 +239,14 @@ The link identifies another control that must be present if this control is present. The link identifies other control content where this control content is now addressed. The containing control definition was moved to the referenced control. + + + + diff --git a/src/metaschema/oscal_component_metaschema.xml b/src/metaschema/oscal_component_metaschema.xml index c757be4c80..9a48bf5289 100644 --- a/src/metaschema/oscal_component_metaschema.xml +++ b/src/metaschema/oscal_component_metaschema.xml @@ -19,10 +19,11 @@ http://csrc.nist.gov/ns/oscal/1.0 http://csrc.nist.gov/ns/oscal -

The OSCAL Component Definition Model can be used to describe the implementation of controls in a component or a set of components grouped as a capability. A component can be either a technical component, or a documentary component. A technical component is a component that is implemented in hardware (physical or virtual) or software. A documentary component is a component implemented in a document, such as a process, procedure, or policy.

-

The root of the OSCAL Implementation Component format is component-definition. -

-

NOTE: This documentation is a work in progress. As a result, documentation for many of the information elements is missing or incomplete.

+

The OSCAL Component Definition Model can be used to describe the implementation of controls in a component or a set of components grouped as a capability. A component can be either a technical component, or a documentary component.

+

A technical component is a component that is implemented in hardware (physical or virtual) or software. Suppliers may document components in an OSCAL component definition that describes the implementation of controls in their hardware and software.

+

A documentary component is a component implemented for a documented process, procedure, or policy. Suppliers may document components in an OSCAL component definition that describes the implementation of controls in their process, procedure, or policy.

+

The information provided by a technical or documentary component can be used by component consumers to provide starting narratives for documenting control implementations in an OSCAL SSP.

+

The root of the OSCAL Implementation Layer Component Definition model is component-definition.

 @@ -34,7 +35,12 @@ Component Definition Universally Unique Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference this component definition elsewhere in this or other OSCAL instances. The locally defined UUID of the component definition can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + Provides a globally unique means to identify a given component definition instance. + + + + + @@ -81,7 +87,12 @@ Component Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference this component elsewhere in this or other OSCAL instances. The locally defined UUID of the component can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + Provides a globally unique means to identify a given component. + + + + + type @@ -252,7 +263,12 @@ Capability Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference this capability elsewhere in this or other OSCAL instances. The locally defined UUID of the capability can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance).This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + Provides a globally unique means to identify a given capability. + + + + + Capability Name @@ -284,12 +300,13 @@

A given component must not be referenced more than once within the same capability.

+ Incorporates Component - TBD + The collection of components that this capability is comprised of. Component Reference @@ -309,7 +326,12 @@ Control Implementation Set Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference a set of implemented controls elsewhere in this or other OSCAL instances. The locally defined UUID of the control implementation set can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance). This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + Provides a means to idenfy a set of control implementations that are supported by a given component or capability. + + + + + @@ -352,13 +374,18 @@ Control Implementation Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference a specific control implementation elsewhere in this or other OSCAL instances. The locally defined UUID of the control implementation can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance).This UUID should be assigned per-subject, which means it should be consistently used to identify the same subject across revisions of the document. + Provides a globally unique means to identify a given control implementation by a component. + + + + + Control Implementation Description - A suggestion for how the specified control may be implemented if the containing component or capability is instantiated in a system security plan. + A supplier (e.g., component vendor or author) suggestion for how the specified control may be implemented if the containing component or capability is instantiated in a system security plan. @@ -398,7 +425,7 @@ -

Implemented requirements within a component or capability in a component definition provide a means to suggest possible control implementation details, which may be used by a different party when authoring a system security plan. Thus, these requirements defined in a component definition are only a suggestion of how to implement, which may be adopted wholesale, changed, or ignored by a person defining an information system implementation.

+

Implemented requirements within a component or capability in a component definition provide a means for component suppliers to suggest possible control implementation details, which may be used by a different party (e.g., component consumers) when authoring a system security plan. Thus, these requirements defined in a component definition are only a suggestion of how to implement, which may be adopted wholesale, changed, or ignored by a person defining an information system implementation.

Use of set-parameter in this context, sets the parameter for the referenced control and any associated statements.

 diff --git a/src/metaschema/oscal_profile_metaschema.xml b/src/metaschema/oscal_profile_metaschema.xml index 5e9db88dfc..df19fa7a0b 100644 --- a/src/metaschema/oscal_profile_metaschema.xml +++ b/src/metaschema/oscal_profile_metaschema.xml @@ -12,9 +12,9 @@ http://csrc.nist.gov/ns/oscal/1.0 http://csrc.nist.gov/ns/oscal -

In OSCAL a profile represents a baseline of selected controls from one or more control catalogs. An OSCAL profile is used in an OSCAL system security plan (SSP) to determine the baseline of controls that must be implemented by the information system. The effective set of controls is generated through profile resolution.

+

In OSCAL a profile represents a baseline of selected controls from one or more control catalogs. An OSCAL profile is used in an OSCAL system security plan (SSP) to determine the baseline of controls that must be implemented by the information system. The effective set of controls is generated through profile resolution process.

In OSCAL a profile represents a set of selected controls from one or more control catalogs. Such a set of controls can be referenced by an OSCAL system security plan (SSP) to establish a control baseline. This effective set of controls is produced from an OSCAL profile using a deterministic, predictable process called profile resolution.

-

A profile references one or more OSCAL catalogs or profiles to import controls from for control selection and tailoring. A profile can also describe how a resulting catalog is structured. When the profile is resolved, these selections and modifications are processed to produce a resulting OSCAL catalog.

+

A profile references one or more OSCAL catalogs or profiles to import controls for control selection and tailoring. A profile can also describe how a resulting catalog is structured. When the profile is resolved, these selections and modifications are processed to produce a resulting OSCAL catalog.

OSCAL profiles have uses beyond establishing a baseline, such as documentation generation or as reference tables for validations.

 @@ -28,7 +28,12 @@ Profile Universally Unique Identifier - A machine-oriented, globally unique identifier with cross-instance scope that can be used to reference this profile elsewhere in this or other OSCAL instances. The locally defined UUID of the profile can be used to reference the data item locally or globally (e.g., in an imported OSCAL instance).This identifier should be assigned per-subject, which means it should be consistently used to identify the same profile across revisions of the document. + Provides a globally unique means to identify a given profile instance. + + + + + @@ -41,13 +46,11 @@

An OSCAL document that describes a tailoring of controls from one or more catalogs, with possible modification of multiple controls. It provides mechanisms by which controls may be selected (import), merged or (re)structured (merge), and amended (modify). OSCAL profiles may select subsets of controls, set parameter values for them in application, and even adjust the representation of controls as given in and by a catalog. They may also serve as sources for further modification in and by other profiles, that import them.

-

See the Concepts - Identifier Use page for additional information regarding this identifier's uniqueness and scope.

 - Import resource - Designates a catalog or profile that defines controls for selection and tailoring by the profile. - + Import Resource + The import designates a referenced source catalog or profile that provides a source of control information for use in creating a new overlay or baseline. This content may Catalog or Profile Reference A resolvable URL reference to the base catalog or profile that this profile is tailoring. @@ -82,7 +85,6 @@ -

A profile must be based on an existing OSCAL catalog or another OSCAL profile. An import indicates such a source whose controls are to be included (referenced and modified) in a profile. This source will either be a catalog whose controls are given (by value), or a profile with its own control imports.

The contents of the import element indicate which controls from the source will be included. Controls from the source catalog or profile may be either selected, using the include-all or include-controls directives, or de-selected (using an exclude-controls directive).

 @@ -92,14 +94,14 @@ - Merge controls - Provides directives for how controls are to be organized in the resulting catalog. + Merge Controls + Provides structuring directives that instruct how controls are organized after profile resolution. - Combination rule - A Combine element defines how to combine multiple (competing) versions of the same control. + Combination Rule + A Combine element defines how to combine multiple (competing) versions of the same control (e.g., controls with the same ID). - Combination method + Combination Method How clashing controls should be handled @@ -193,7 +195,7 @@ - Modify controls + Modify Controls Set parameters or amend controls in resolution @@ -214,7 +216,7 @@ - Depends on + Depends On **(deprecated)** Another parameter invoking this one. This construct has been deprecated and should not be used. @@ -451,11 +453,11 @@ Removal Specifies objects to be removed from a control based on specific aspects of the object that must all match. - Reference by (assigned) name + Reference by (assigned) Name Identify items to remove by matching their assigned name - Reference by class + Reference by Class Identify items to remove by matching their class. @@ -526,7 +528,7 @@ >>>>>>> a8c12d91f (Proposed metaschema docs updates (#50)) - Include contained controls with control + Include Contained Controls with Control When a control is included, whether its child (dependent) controls are also included.