From e1861c198d0d11f6c06709047ed75b6d88b1c2b1 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Thu, 30 Mar 2023 13:34:56 -0400 Subject: [PATCH] Add the with-parent-controls for #1662. (#1717) * with-parent-controls for import only for usnistgov/OSCAL#1662 Add it for insert-controls, but not exclusion or merge, based upon team review and analysis of current profile resolution specification. * Clarify spec for usnistgov/OSCAL#1662. * Apply suggestions from code review Co-authored-by: Wendell Piez * Update src/specifications/profile-resolution/profile-resolution-specml.xml * Apply suggestions from code review Co-authored-by: Wendell Piez --------- Co-authored-by: Wendell Piez --- src/metaschema/oscal_profile_metaschema.xml | 54 +++++++++++++------ .../profile-resolution-specml.xml | 8 +-- 2 files changed, 41 insertions(+), 21 deletions(-) diff --git a/src/metaschema/oscal_profile_metaschema.xml b/src/metaschema/oscal_profile_metaschema.xml index 2ab7d34dd8..1c3b0dc6db 100644 --- a/src/metaschema/oscal_profile_metaschema.xml +++ b/src/metaschema/oscal_profile_metaschema.xml @@ -81,13 +81,24 @@

Identifies that all controls are to be included from the imported catalog or profile.

- - include-controls - + + Select Control + Select a control or controls from an imported control set. + + + + + + + + + + -

Identifies a subset of controls to import from the referenced catalog or profile by control identifier or match pattern.

+

If with-child-controls is yes on the call to a control, any controls appearing within it (child controls) will be selected, with no additional call directives required. This flag provides a way to include controls with all their dependent controls (enhancements) without having to call them individually.

+

If with-parent-controls is "yes" on the call to a control, it will not be selected and removed from (shown without) a parent control, but instead will be copied with its parent in the source. This flag provides a way to include controls with all their ancestor controls (enhancements) without having to call them individually.

 - + exclude-controls @@ -444,18 +455,12 @@ Select a control or controls from an imported control set. - - Match Controls by Identifier - Selecting a control by its ID given as a literal. + - - - Match Controls by Pattern - Selecting a set of controls by matching their IDs with a - wildcard pattern. + + - - +

If with-child-controls is yes on the call to a control, no sibling callelements need to be used to call any controls appearing within it. Since generally, this is how control enhancements are represented (as controls within controls), this provides a way to include controls with all their dependent controls (enhancements) without having to call them individually.

@@ -471,8 +476,27 @@ + + Include Parent Controls with Control + When a control is included, whether its parent (ancestor) controls are also included. + + + Include parent controls with an included control. + When importing a control, only include parent controls that are also explicitly called. + + + Pattern A glob expression matching the IDs of one or more controls to be selected. + + Match Controls by Identifier + Selecting a control by its ID given as a literal. + + + Match Controls by Pattern + Selecting a set of controls by matching their IDs with a wildcard pattern. + + diff --git a/src/specifications/profile-resolution/profile-resolution-specml.xml b/src/specifications/profile-resolution/profile-resolution-specml.xml index 272faafb59..d56bed22fa 100644 --- a/src/specifications/profile-resolution/profile-resolution-specml.xml +++ b/src/specifications/profile-resolution/profile-resolution-specml.xml @@ -532,7 +532,7 @@ include-controls:

with-child-controls -

Child controls are, for the most part, treated the same as top level controls: they can be explicitly included using the selection directives above. As a shortcut to manually including all of the desired descendant controls of a given control, OSCAL provides the with-child-controls option. with-child-controls appears as a child object under a given inclusion directive, and defines additional behavior that is to be executed alongside the parent inclusion.

+

When a control is selected, any child controls can be included by means the with-child-controls flag. This provides an alternative to selecting child or descendant controls explicitly by id or match. with-child-controls appears as a child object under a given inclusion directive and defines behaviors listed below.

A with-child-controls: yes directive on an include-controls indicates that @@ -549,11 +549,7 @@ include-controls:

with-parent-controls -

Although similar to the above - with-child-controls, the optional - with-parent-controls applies to parents of the included control, and has the opposite default behavior. In order to maintain the structure of the source catalog, profile resolution includes all parents of an included control by default. If a profile author wants to change this structure, they should use an exclude directive that lists all of the undesired parents. As a shortcut for this, - with-parent-controls provides the following functionality: -

+

The the optional with-parent-controls flag defines behavior applicable to parents or ancestors (a parent's parent etc.) of the included control, in cases of nested controls. with-parent-controls appears as a child object under a given inclusion directive and defines the behaviors listed below. Its semantics assume that nesting of controls indicates logical dependencies in catalogs, which should be retained unless a profile specifically indicates otherwise.

A with-parent-controls: yes directive on an include-controls indicates that