From 918d2848b98f266556dcb356f167ed5a6457468d Mon Sep 17 00:00:00 2001 From: Wendell Piez Date: Thu, 2 Jan 2020 15:23:15 -0500 Subject: [PATCH] Adding profile resolution HTML to gitignore --- .gitignore | 1 + .../processing/profile-resolution.html | 1192 ----------------- 2 files changed, 1 insertion(+), 1192 deletions(-) delete mode 100644 docs/content/documentation/specification/processing/profile-resolution.html diff --git a/.gitignore b/.gitignore index 32868c7fd0..6ed86ba58e 100644 --- a/.gitignore +++ b/.gitignore @@ -59,3 +59,4 @@ target/ # node_modules/ +/docs/content/documentation/specification/processing/profile-resolution.html diff --git a/docs/content/documentation/specification/processing/profile-resolution.html b/docs/content/documentation/specification/processing/profile-resolution.html deleted file mode 100644 index dc988743e0..0000000000 --- a/docs/content/documentation/specification/processing/profile-resolution.html +++ /dev/null @@ -1,1192 +0,0 @@ ---- -title: OSCAL Profile Resolution -description: Transforming a profile into the tailored catalog it represents ---- -

These specifications describe how to render an OSCAL profile document in - the form of an OSCAL catalog. We call this profile resolution.

Reading these specifications

Terminology

These DRAFT specifications take the form of a tag set mapping between the OSCAL - profile and OSCAL catalog XML document models. The same mapping - (transformation from source to target) can be effected using other expressions of the OSCAL - model such as JSON or YAML object serializations. In these specifications, XML terminology - is used, with reference to XML constructs such as element and attribute, with - examples given using XML syntax: these however are for illustrative purposes only and - normative only with respect to the semantic mapping, not the syntax as such. The XML - orientation of the specification of this mapping is an expediency; in the longer term we - plan specifications that are format-agnostic. Let us know if you have an interest - in helping to recast the specs / metaschema terminology?

In these specifications there are references to source, target - and result. Source refers sometimes to profile documents as a type - (abstractly), and sometimes to instance profiles in operation, or elements within profiles - (particular kinds of sources). Target refers to the intended output of the - transformation, that is the catalog model generally (as a document type) or, for particular - source instances or elements, particular targets.

Elements in the source format are marked in these specifications to appear distinctively as - source-element (for an element named source-element).

Elements in the target format are marked in these specifications to appear distinctively as - target-element (for an element named target-element).

The term result refers to the actual results of transformation, as opposed to - the intended or expected results. Conformance to these specifications requires that a - processor's result corresponds to the target as described here, given a particular - source.

The term directive is used in these specifications to refer to an element or - combination of elements in source data, which is designed to effect a particular outcome in - the target catalog. For the most part, directives are in the source profile document – for - example, a set element in a profile is a directive to set a parameter value in - the target catalog.

In contrast to profiles, catalogs do not contain directives but instead, representations of - security controls and their parts, optionally gathered in groups, on which directives are - assumed to operate. There is one exception: the insert element in control - catalogs can be considered a directive that a parameter value be inserted into a particular - location in running text (data content), when a catalog is rendered. Since these semantics - respect catalog rendering, however, not profile resolution, they are out of scope for this - document. For purposes of profile resolution, catalogs may be considered to be passive - resources from which contents are replicated (copied): the operation of the profile, in - contrast - its OSCAL semantics as opposed to the domain-specific semantics of the - information it handles – requires that it express what is to be done and how.

Original order refers to the order of elements and objects as given in the - source. Canonical order refers to the correct order of elements or - objects as defined by an OSCAL format such as the catalog or profile models. That is, the - respective schemas of these models enforce order to the extent it is meaningful; where it is - not (for example, in the ordering of properties on objects in JSON), a metaschema can - nevertheless be referenced to provide an order.

So for example, on a JSON object, a links object and a parts object - may be given as properties on an OSCAL control object. Each of these collects a - sequence of one or more objects of the appropriate type (links or parts). As properties in - JSON, these collections are not ordered with respect to one another. However, for the sake - of a complete definition in another of OSCAL's operational contexts (namely XML), the OSCAL - catalog model stipulates that all links come before all parts. This has two consequences. - First, lossless conversion between formats is possible, even when one or both is defective - in some respect (as in this case, JSON's object model does not capture the order of object - properties): the metaschema can provide the difference, enabling a compliant OSCAL processor - to know how deterministically to emit valid XML (with respect to ordering) even from a - property set (intrinsically unordered) JSON source. Second, it ensures that the relative - ordering of links to parts will never be significant in the data: while the order of links - within links and the order of parts within parts may be significant - and can hence be preserved across representations, the order first links, then parts, - being defined by the model, becomes invariant across instances and thus insignificant.

Canonical order is important since there are occasions when, in order to produce valid - outputs in XML, a profile resolver must resequence items. This may happen any place where - the natural or intrinsic order resulting from splicing sequences in original order is not - correct.

Finally, this specification describes not only (source) profiles and (target or result) - catalogs, but control selections as well. The conceptual model of profile - resolution takes a profile through several steps, in which controls are collected from - source catalogs, combined, and potentially modified. As described by this specification, - control selections are produced during this process, as temporary collections of controls in - a transitional state. In the last phase of processing, the discrete selections are combined - into the single catalog, the target.

For illustrative purposes, these control selections are, like source and target formats, - also represented by tagging in examples given here, and described as intermediate targets, - even though no OSCAL processor is obliged to produce or recognize such XML at any point, as - long as it produces the same results (final outputs) from the same inputs.

RFC 2119 Keywords

When complete, this specification will conform to IETF RFC 2119 in its use of - keywords such as must - required and shall. At present (time of writing) an editorial pass to ensure - this consistency has not been conducted.

Use of XPath

Additionally, in these specifications XPath notation is used to identify elements and - attributes in the XML. A summary of some lightweight XPath syntax:

Variable contents in XML examples

Examples given to illustrate targets for particular source (example) inputs are given, like - the source, in XML notation. Sometimes, however, the expected outputs are not fully defined - by the inputs given. In these cases, a description of the dynamic (variable) contents in - curly braces { }.

So for example where a property is added to target metadata, an example could - show

{{< highlight xml>}}{ timestamp }{{}}

This indicates the last-modified element should be produced with contents - generated appropriately, namely with an actual time stamp in this case, and not the string - { timestamp }. In display, these values should also be shown with special - formatting as shown here.

Examples also indicate unspecified content using a simple … (elision) character, - typically for more verbose chunks of target data whose production is specified elsewhere in - the document.

Operational context

Processing context and scope

A profile in OSCAL represents a selection and configuration of a set of - controls. In the normal case, the set of controls available to a profile is - provided by a catalog. For example, the three NIST SP 800-53 profiles representing the - impact baselines HIGH, MODERATE and LOW: each of these calls on a catalog representing the - families, controls and control enhancements described in SP 800-53/53A. In a data processing - system, this dependency can be modeled in the form of separate documents or data instances - - the (nominal) catalog and its profile, the latter being a selection, - adaptation and organization of controls, as distinct from the catalog from which those - controls are derived.

However, profiles may also select controls from profiles, thus deriving them from - underlying catalogs as modified by those profiles. This feature enables an organization that - wishes to promulgate guidelines or requirements to do so by publishing a set of - customizations to an existing catalog, rather than create a catalog from scratch. Profiles - can also arrange combinations of controls from more than one catalog or profile origin, - making it possible to use them to support the creation of hybrid catalogs.

In the general case OSCAL must support sourcing more than one catalog at once, in order to - aggregate and organize controls from disparate sources. For example, it should be routine - for a profile to acquire its controls from an authoritative standard catalog, plus a local - supplement. But multiple catalog inputs, especially when they are produced and sourced - independently of one another, may not combine without issues. In order to provide sensible - and transparent results even for incoherent inputs, this specification defines these - processes such that legible and testable results are produced even when they are formally - invalid to constraints governing the outputs. Such downstream processing errors including - validation errors are expected to be detectable and remediable. This especially applies to - situations where multiple catalogs are sourced, or where the same catalog is sourced more - than once, directly or indirectly.

In order to support these semantics – because whatever data set is sourced by a profile, it - must look like a catalog – the results of resolving a single profile must be in the - form of a single catalog. Two different OSCAL processors that promise profile resolution, - must deliver, for the same input, the same catalog with regard to its contents: which - controls are included; their ordering (insofar as the target format represents ordering); - and the structure (groups) in which they are embedded. This specification is designed to - make this possible, by defining outputs with sufficient rigor that the same is - meaningful and testable in this context.

Why resolve a profile as a catalog

A profile is a representation of a delta, a here to there. As such, a profile might - be conceived of as a recipe or instruction set – a sequence of steps or procedures – whereby - to create an OSCAL catalog (set of controls describing security requirements) from an OSCAL - catalog (set of controls describing security requirements). The primary use case for this is - when we need to make a new catalog to apply to a system or set of systems, starting from a - canonical, received, mandated or standard catalog with a more general scope.

This is because although catalogs - for example, the controls described in NIST SP 800-53 - - are published, available for use, and even standardized, they can never be used exactly in - the form in which they are acquired. They must be taken from the packaging and placed into - operational context before they mean anything. This typically requires that a few operations - over raw catalogs be supported by a profiling mechanism. We must be able to select - controls; we must be able to arrange them in order (or not); and we must be able to qualify - or condition them by setting parameters defined for them and making adjustments to them.

By representing the steps by which a base catalog can be sliced, sifted, amended and - edited, into a (nominally) finished or ready set of control requirements, a profile makes it - easier to codify and preserve even very incidental or temporary local revisions of a control - catalog. Once expressed as a profile in OSCAL format, a set of emendations to a catalog can - be managed entirely separately and independently from the catalog. Because a conformant - processor can always create the customized catalog by resolving the profile against its - sources (executing the transformation described in this document), the profile can also be - examined and used as a proxy for that catalog for other purposes. The customized catalog can - be made available wherever and for whatever purposes it is needed, while its revision and - maintenance can be focused on the profile.

This separation of concerns - between the originating catalog authors, who describe policy - in only general terms, and the authors of the user manual catalog, who must describe - policy in very particular and local terms - is a necessary factor in supporting sustainable - processes with the potential for automation and process improvement. An OSCAL profile - bridges the gap between a set of general guidelines, and actionable rules. Only by examining - the system in the context of the actual intentions appropriate to that system, can we - properly assess its security. Profiles make this possible.

In order for this to work however we need a process that can perform the necessary - operations, to apply the delta to an unmodified catalog, to produce the local view of the - catalog as modified. This is profile resolution.

Formal validation of source and result

In an XML context, document validation is available as a means of determining whether an - arbitrary XML document entity conforms to structural and naming constraints such as must be - assumed by processors respecting application semantics. These specifications assume that XML - inputs for profile resolution will be schema-valid with respect to the OSCAL - profile model, and hence will be tagged in the namespace - http://csrc.nist.gov/ns/oscal/1.0.

Similarly, the definition of the output format or results, is constrained by the OSCAL - catalog model as defined by its schema.

Order of objects in serialization

As described above, original order refers to the order of elements and objects - as given in the source, whereas canonical order refers to the correct - order of elements or objects as defined by an OSCAL format such as the catalog or profile - models. That is, the respective schemas of these models enforce order to the extent it is - meaningful; where it is not (for example, in the ordering of properties on objects in JSON), - a metaschema can nevertheless be referenced to restore an order.

So for example, on a JSON object, a links object and a parts object - may be given as properties on a control object. As properties, they are not - ordered with respect to one another. However, for the sake of a complete definition in - another of OSCAL's operational contexts (namely XML), the catalog model stipulates that all - links come before all parts: in an XML representation, link elements come before - part elements. This restriction ensures that the relative ordering of links to - parts will never be significant in the data: while the order of links within - links and the order of parts within parts may be significant and can - hence be preserved across representations, the order first links, then parts is - defined by the model, with the consequence that it can be represented as such even when an - underlying representation (such as a compiled JSON object) does not encode that relationship - natively.

There are occasions especially when control contents are altered or amended, when a - straightforward representation of elements in their original order, or in two sequences - spliced together (say, the parts of a control, followed by new properties for the same - control, added by the profile), would be invalid, which is to say not conformant with - canonical order. In general the rule in these cases is, in resolution, to reorder the - elements. Example

For any given element (defined as an assembly in the metaschema), the canonical order is - given by its model. So for example the canonical order for contents of a catalog is - metadata, param, control, group, - back-matter. Within this sequence, members may be missing, as for example not - all catalogs will have parameters or groups. Any members that are present, however, must be - given in this order.

ID uniqueness constraint

In addition to those described and enforced by the respective schemas, there are additional - constraints over the data that this process relies on. The most important of these is - ID-distinctiveness. Every id flag (in XML, represented by @id - attributes) on an element in the model, whether it be attached to a control, group or an - element within a control, must be distinct and unique, within the defined processing scope, - inasmuch as this value will be used in processing as a proxy for element - identity and especially (in the case of controls) for control - identity. That is, it is on the basis of their IDs that controls are selected and - referenced, and clashes are detected and recognized between competing representations of - controls.

In this context, defined processing scope includes a profile along with all profiles - and all catalogs it imports, directly and indirectly. Many arrangements are possible in - which a single catalog provides controls to more than a single branch on the import tree. In - profiles where this occurs, distinct imports must identify discrete, non-intersecting, sets - of controls, or clashes occur. Additionally, clashes may naturally occur through implicit - copying of parameters from multiple imports.

OSCAL profiles provide three different modes for handling clashing controls or replicas in - general, where replica refers to any element represented more than once. Each - of these modes is indicated by different directives given on merge/@combine, - namely keep (also the default), use-first and merge.

Because ID distinctiveness within the scope of processing, is critical, OSCAL - users should take care that different catalogs have distinct sets of IDs. This applies to - all structures within the catalogs, not only controls but also groups, parameters, - citations and resources.

Defining control identity

A central problem in profile resolution is determining when two controls are both - representations of the same control, even when those representations have dissimilar - contents or come to a profile through different import pathways.

For purposes of profile resolution, control identity (or parameter, group identity etc.) - can be determined by any of several ways, depending on the identity designation - mode:

Brian Ruf suggested we provide a resolution/disambiguation/debugging mode that - produces valid OSCAL by producing new IDs for everything, thereby disambiguating by brute - force. This is not a bad idea. This proposal offers that feature as 'no identity - designation', i.e. nothing is found to be identical with anything.

Detecting issues in profiles

It is frequently possible by static analysis to detect many conditions even in schema-valid - profile documents, that will result in problematic catalogs in resolution. The most common - issue will be clashing controls, that is more than one control in underlying catalogs with a - given identifier (ID), making references to such controls ambiguous. The identity - designation mode is intended to give profile developers some control over this - handling, for purposes of development or diagnosis; but the quality of the results can only - be guaranteed determinatively by the quality of the inputs, and full analysis in support of - profile development and diagnostics – to produce correct inputs that accurately reflect the - intent – is outside the scope of these specifications.

Comments in result documents

In an XML-based profile resolution, XML comments are one straightforward way for a - processor to record events or conditions without affecting the output's nominal semantics. - To support this, while two processors are obliged to return the same catalog XML for the - same profile XML inputs, they are not required to match one another's comments, whitespace - usage, attribute order, or processing instructions, only each other's elements, attributes - and data content.

One consequence of this is that processes intended to compare two profile resolutions may - have to accommodate differences in comments, considering them as insignificant along with - other differences in serialization.

Target catalog structure

Inasmuch as the target of profile resolution is a catalog, the resulting document is expected - to be a catalog document as specified by OSCAL, conforming to the applicable schema, XSD in - the case of OSCAL XML or JSON Schema for OSCAL object serialization formats.

These two approaches to validation do not constrain their respective data models – although - OSCAL-equivalent – in exactly the same way. In particular, element structures in the XML may - be represented in JSON by either objects, or arrays of objects, depending on the respective object's - OSCAL definition; and where objects appear outside arrays, ordering semantics cannot be respected (whereas in XML, order among nodes is - always an intrinsic property of the graph).

Consequently, where these specifications dictate that targets appear in order, it must be - understood that what is described is both (a) the order in XML, and (b) the - canonical order in OSCAL, which while it is not exposed in a JSON object - serialization, will always available to an OSCAL processor by reference to the appropriate - metaschema (in this case, the Metaschema instance that defines the catalog model). [See: Terminology]

Form and organization of resolution target

The output of a profile resolution should take the form of a catalog. Catalog results (the - output of a conformant profile resolution) will be valid to the OSCAL catalog schema.

At its base, an OSCAL profile source produces a catalog:

{{< highlight xml>}}...{{}}{{< highlight xml>}} - [Required metadata, as described below] - { controls or control groups, as described below } - { back matter as described below } -{{}}

A valid catalog must have metadata in addition to controls and control groups. - Additionally it may have back-matter. How to produce and populate the - metadata and back-matter is described below - link me, as is the construction - of the catalog/@id in the target.

Validation of resolution result

Although the target of profile resolution takes the form of a catalog, it may not be valid - to all constraints that define the OSCAL catalog format, whether enforced by its schema or - by other means such as Schematron. Specifically, while a correctly implemented profile - resolution may produce a result catalog that is structurally valid, there is a mode of - operation, namely the keep-all combination rule, which can permit replication of - controls or control contents, when the control imports are redundant or contain redundant - call or match directives. Such replication can result in violations - of ID uniqueness constraints, in particular. [See: Formal validation of source and result]

If the merge behavior is set to combine[@method='keep'], or not given (as this - setting is the default), a profile with multiple calls on controls will result in multiple - copies of controls with clashing IDs. These should raise validation errors in the results, - since IDs must be unique on elements in document scope. Accordingly, this is an appropriate - combination rule to use in development when any potential collisions should be detected and - removed; it is also an appropriate rule to apply when a profile has been tested and found to - be free of any such collisions. Other combination rules (method='use-first' or - method='merge') are provided for special exigencies or to permit certain kinds - of optimization.

top-level @id

Because document IDs are sometimes used to distinguish data points in processing context, a - resolved profile may not present the same ID as any of the catalogs it is importing, or the - same ID as its source profile.

It is permitted to produce the profile’s ID in resolution via a static mapping from the ID - of the source. For example, the resolution of profile with ID profile-X might - have ID profile-X-RESOLVED.

BR feels this is underspecified and I agree. He also thinks that resolutions - should always have a (generated) unique IDs, since upstream catalogs can change between - resolutions.

Instance metadata

Metadata in the target is derived directly from the source metadata, with modifications. - All elements inside metadata in the source profile are copied in their original - order into the catalog. Additionally, new elements are introduced as described here.

Because of options in producing metadata and especially the requirement for a timestamp, - developers and users should note that two different resolutions of the same profile will - not, ordinarily, be identical inside metadata.

This has been worked, with changes suggested by DW, since BR's - review

Metadata resolution timestamp

A prop element with name - resolution-timestamp is added to the resolution target metadata with a valid - timestamp indicating the time of the resolution runtime. Conforming with canonical order - of metadata in the target, It must be placed into metadata structure after - any title, published, last-modified, - version, oscal-version, or doc-id elements, and before - any prop, link, role, party, or - responsible-party elements. The target is schema valid, and the new - prop is given before copies of prop elements already - present.

{{< highlight xml>}} - Example Profile - 2019-06-30T10:54:16.372-05:00 - NEW -{{}}{{< highlight xml>}} - Example Profile - 2019-06-30T10:54:16.372-05:00 - { timestamp of profile resolution runtime } - NEW -{{}}

The presence of this property with a valid timestamp may be taken as an indicator that - an OSCAL catalog has been produced by resolution of a profile.

Note that due to this provision, two different resolutions of the same profile produced - at different times will not be bit-equivalent, since their timestamps will be - different.

Any provision for systems that cannot provide a valid timestamp?

Metadata link to source profile

Optionally, a processor may add a link to the result - metadata. Conforming with canonical order of metadata in the target, - It must be placed into metadata structure after any title, - published, last-modified, version, - oscal-version, doc-id or prop elements, and before - any link, role, party, or - responsible-party elements. The target is schema valid, and the new - link is given before copies of link elements already present

The new link should have two flags (attributes):

{{< highlight xml>}} - Test profile - 2019-12-03T11:36:32.284-05:00 - 1.0 - 1.0-MR2 - - - Standing Committee - - -{{}}{{< highlight xml>}} - Test profile - RESOLUTION RESULT - 2019-12-03T11:36:32.284-05:00 - 1.0 - 1.0-MR2 - { timestamp of profile resolution runtime } - Test profile - - - Standing Committee - - -{{}}

Body of the target

The construction of the body of the target catalog is described in the next section. [See: Phases of profile resolution]

The body of the target catalog, after its metadata, is structured - as follows, depending on its merge directive. (Details on merging are given below [See: Merge phase].)

Unless it be for special purposes in a debugging or tracing mode, profile results may not - show any groups or structures in the form of elements not described here. Depending on the - merge directive, all groups will be given either by the catalog source(s) - (merge/as-is) or the profile (merge/custom), or there will be no - groups at all (no merge directive).

Back matter

The back matter in target catalogs is assembled from the back matter of their source - profiles in combination with the back matter of source catalogs. In both catalogs and - profiles, back-matter is comprised of (multiple uses of either) - citation or resource. Either of these elements may be - cross-referenced from any location in their source documents by means of a URI fragment - identifier on an href flag, for example <resource id="document-X> - may be referenced from inside its containing document by <link - href="#document-X"> appearing elsewhere. Whether an element inside back matter must - be included in the target, depends on whether such a cross-reference has also been included - in the same target.

Specifically, any citation or resource inside back-matter - either in the profile, or in any imported catalog, is considered eligible for propagation - into the target if either of two conditions obtains:

The assembly of the target back-matter occurs by including copies of all - eligible citation elements followed by all eligible resource elements, - in the same order as given in their sources.

Additionally, combination rules (see next section) will affect whether and how duplicate or - competing citation or resource elements are handled, to remove or - combine multiple occurrences of the same referenced object.

Phases of profile resolution

Considered as a document or integrated data set (object), a profile has three - sections, each of which corresponds to a conceptual step in resolution. To resolve a catalog - fully is to perform all these steps.

While the steps are described in this specification as occurring in sequence, a profile - processor is not obliged to perform them in the order described. Conformance to these - specifications is determined by whether the results of processing (resolution) - appear as described, not on whether the means to produce those results work in exactly the - manner described here.

The three steps are import (control selection); merge; and - modify. In brief:

The selection phase provides the basis for a customized catalog by designating - controls to be included in it; a profile that designates no controls, produces no catalog. The - selection phase is controlled by profile/import directives in the source - profile.

The merge phase addresses two questions: what a processor should produce in - cases of (accidental or intentional) ambiguities in control identification in the selection - phase; and how to structure the outputs, whether in a hierarchy (copied or created) or flat - (without grouping). These two aspects of resolution are addressed by the combination - rule (or combination method) and the merge rule (which - includes a no merge option). In source data (a valid profile document), a - profile/merge directive is optional; when it or its child directives are absent, - default combination and merge rules apply.

The modification phase is an opportunity for a profile to amend, alter or edit - controls, and to set parameter values or constrain or qualify parameters as represented in the - target. A profile can be valid and useful without making any modifications, only selections, - so the profile/modify element (node) is optional in the profile model.

As described in the previous section, when resolved, an OSCAL profile takes the form of an - OSCAL catalog. The merge semantics described below will produce outputs conforming to this - organization.

Selection phase

A profile begins by importing catalogs, all of whose controls are made available. The - catalogs it references may be available as static resources, or they may be produced - dynamically on request; accordingly a profile may also import profiles, to be resolved as - catalogs, instead of or in addition to catalogs as such. Imports are given in sequence after - the metadata:

{{< highlight xml>}} - { Profile metadata } - { … selection of controls … } - { … selection of controls … } - -{{}}{{< highlight xml>}} - { Profile metadata } - { … selection of controls … } - { … selection of controls … } - -{{}}

The resource indicated can be either an OSCAL catalog or an OSCAL profile. A catalog - provides controls in their native form. An imported profile is resolved on import, using the - same rules for profile resolution, so a catalog is presented to the importing profile.

(The result of importing other endpoints or resources besides valid OSCAL catalogs and - profiles is not defined by this specification.)

No profile may import itself either directly or indirectly. An import directive that - indicates either the profile itself, or a profile into which it is being (currently) - imported, must be ignored. Optionally, a processor may issue a warning.

In an import directive, the reference to the resource to be imported appears on an - @href flag. It takes either of two forms, external or internal:

External - import via URI

An external reference appears as an absolute or relative URL

Indicating a file available via [prototol?]

{{< highlight xml>}} - - - - -{{}}

Internal - import via resource

A catalog or profile to be imported can also be indicated using an internal link via a - URI fragment identifier (starting with #). If an import href resolves to a - resource elsewhere in the profile (typically in back matter), that resource - can be retrieved to provide the source catalog.

{{< highlight xml>}} - - - - - - ... - - - - SP 800-53 catalog (OSCAL format) on Github - - - -{{}}

A reference from an import to a resource that does not reference a catalog or profile, or - a cross-reference to something other than a resource, is inoperative for purposes of - importing. It may be signaled as an error [or warning] by a processor. Allow - processors to import other stuff as they like?

Availability of documents returned by given URIs

The rules of XSLT document() apply to the traversal of any URI: that is, it - is assumed that all calls to a given (resolved) URI reference, will return the same - result.

If documents called for import are determined to be unavailable, the processor may drop - them along with a warning, both or either out of band (e.g. through STDERR) - or in the catalog results.

URIs are used as a widely supported, global address with broad utility. A processor is - not obliged, when requested for a resource, to use the given URI in an http request to - produce it. Processors may offer fallback behaviors for URI requests that fail; conversely - a processor may be able to avoid a URI request in favor of a better way to provide - resources identified by URI.

Missing imports

An import that does not reference either an OSCAL catalog, or an OSCAL profile that can - be resolved as a catalog, is dropped.

{{< highlight xml>}} - … - - - - - - -{{}}{{< highlight xml>}} - … - -{{}}

Optionally, a processor may produce a comment indicating the lapse:

{{< highlight xml>}} - … - - -{{}}

In this context, an OSCAL profile that makes direct or indirect reference (via its own - imports) to the importing catalog, is also dropped as unavailable. See below under - Circular Imports.

Circular imports

When a profile imports a profile, the subordinate profile is resolved into a catalog - using the same rules. This presents a possibility of circular imports, when a profile is - directed to import itself either directly or indirectly.

A circular import is defined as a directive to import a resource, which has - already been called higher in the import hierarchy. For example, if Profile A imports - Profile B, and Profile B imports Profile A, the second import is circular. (An import at - the top can only be circular if a profile tries to import itself.) If A imports B, B - imports C and C imports A, C’s import is circular.

Note that an import can only be circular within the context of processing a particular - profile. In the last example, C’s import would not be circular if invoked in the context - of resolving B by itself (without being imported by A), or of resolving some other profile - that did not import A. (D importing B importing C importing A would not be a problem.)

Circular imports are inoperative, and may be reported as an error or - warning.BR wants this to be more draconian but I am not sure every - situation warrants it. It seems like the same sort of thing as a missing import to me, - except it's missing by definition.

An import that is not circular (refers to a document not already imported) results in a - control selection, subject to merging with other control selections in the merge - phase.

A profile identified as home_profile.xml imports another one identified as - circular_profile.xml:

{{< highlight xml>}} - ... - - - - - - -{{}}

In turn this file invokes home_profile.xml:

{{< highlight xml>}} - ... - - - - - - -{{}}

No control selection is produced for the circular import:

{{< highlight xml>}} - ... - -{{}}

Optionally, a processor may produce a comment indicating the lapse:

{{< highlight xml>}} - ... - - -{{}}

Multiple imports

In the selection phase, each import directive is processed to produce a set of controls - and (when they are referenced) parameters. These controls and parameters are represented - in the form of a control selection. Note that this occurs in the selection phase even if - the same catalog (resource) is imported multiple times: each distinct import collects - controls into a selection:

{{< highlight xml>}} - … - - … select controls … - - - … select controls … - - … -{{}}{{< highlight xml>}} - … - … selected controls … - … selected controls … - … - -{{}}

The control selections are combined and collapsed in the next phase of processing, - merge (see below) .

Multiple imports may result in outputs with clashing controls (see below). Typically this - will be because a control has been selected twice (in selection or in the selections of - underlying profiles), and no merge behavior has been indicated to resolve the clash.

Typical cases of multiple imports of the same (underlying) resource will be when a - profile A imports another profile B, which calls catalog Z, and then profile A calls - catalog Z again to acquire other controls not included in profile B, or in an original - form unmodified by profile B.

Selecting controls

Imports can specify controls by inclusion and exclusion, either or both in - combination.

Including controls

Using inclusion, all or some controls may be selected from a catalog.

Selecting by ID

Select individual controls or controls by groups using control-id - selectors corresponding to their IDs.

{{< highlight xml>}} - - -{{}}
Matching IDs to select groups of related controls

Controls may also be selected using match patterns against their IDs. This is useful - because related controls (either in a hierarchy, or together in a group) frequently - have related IDs as well.

{{< highlight xml>}} - - -{{}}

The match pattern is evaluated as a regular expression using XPath regular - expression syntax. [XXXX]

Selecting all controls

Select all controls from a catalog by using an include/all rule:

{{< highlight xml>}} - - -{{}}
Including child controls

In OSCAL, controls may contain controls. For example, in SP 800-53 many controls are - supplemented with control enhancements; in OSCAL these are represented as child - controls within parent controls. So parent AC-2 has children AC-2(1) through AC-2(13), - for example.

Child controls can be included by the same mechanism as controls, i.e. by means of an - ID call. Alternatively a match can frequently be applied (at least given most ID - assignment schemes) to match controls and child controls together.

Additionally, a @with-child-controls directive on a call or - match can indicate that child controls (that is, direct children not all - descendants) should be included with the applicable call(s) or match(es).

Furthermore, all[@with-child-controls='no'] may select all controls placed - directly within a group, excluding all controls appearing inside other controls.

Redundant calls

Calls and matches may be combined in a single import. Their effect is cumulative; any - control that is selected by both calling and matching from a given include - directive, or by matching more than one pattern, is included once (unless it is also - marked for exclusion, see [See: Excluding controls]).

Excluding controls

Exclusions work the same way as inclusions, except with the opposite effect - the - indicated control(s) do not appear in the target catalog.

Additionally, there is no such thing as exclude/all, which is invalid and - should be considered inoperable.

Any control designated to be both included and excluded, is excluded. This holds - irrespective of the specificity of the selection for inclusion or exclusion. For - example, if AC-1 is included by id ac-1 and excluded by matching - ac.*, it is excluded. Selection for exclusion prevails.

One possible exception: what about when a control is excluded, but it has - descendant controls that are included? Under include/all, the descendants - maybe would be excluded. If the subcontrol is included by call or - match perhaps the 'shells' of its ancestors should be included despite - their nominal exclusion. See section on "implicit inclusions under as-is", - below.

Implicit all

An empty import statement should be considered the same as an import with an - include/all. An empy import directive

{{< highlight xml>}} -{{}}

is functionally equivalent to this:

{{< highlight xml>}} - - - - -{{}}

The same thing occurs if an exclude directive is given without an - include directive.

Example:

{{< highlight xml>}} - - - - -{{}}

is the same as this:

{{< highlight xml>}} - - - - - - - -{{}}

Target: all controls from the catalog are included except AC-1.

Order of controls returned in selection

Because controls may be organized in the subsequence merge phase, order of controls - returned in the selection step is unimportant in most circumstances. If no merge - directive is applied, however, or the no merge combination rule is used (see - below), controls are returned for an import in the order of their appearance in their - catalog of origin.

BR suggests we revisit as an alternative would be to sort in call order. I - think the given proposal is simplier given cases of match and "all".

Copying parameters

Unlike controls, parameters are copied implicitly. Whether a parameter in the source - catalog is copied into the target depends on two factors: its location, and whether it is - referenced by an insert directive in the target catalog.

insert directives may occur anywhere in a catalog's data content including not - only in controls, but in other parameters. Thus a parameter may have to be included by - virtue of an insert directive, making reference to it, that occurs in another - parameter, included by virtue of a different insert directive found in an - included control.

Parameters given in controls

Any parameter (param element) that appears in a control being selected, - appears in the target, unless the parameter element was indicated by a remove directive - (see below [See: Removing contents from controls]).

BR thinks such nonsense should be prevented somehow perhaps warnings or - errors. My feeling is, that's what validation is all about.

{{< highlight xml>}} - Control A1 - - - a1.a value - - alive - -

A1 aaaaa aaaaaaaaaa

- -{{}}
Loose parameters

There are two situations where parameters must be considered separately from controls, - in which case they are considered to be loose, appearing in the target directly - inside catalog or group. The first is when they have no control - parent in the source catalog (or rendered profile): they are inherently loose. - The second is when they become loose because the control in which they appear, is - not selected, but they are needed in the target, due to being referenced for insertion - elsewhere. (Examples)

The same parameter, however, cannot be both loose and anchored. If it is invoked from - inside its parent control, it is considered as anchored, even if it would also be called - (as loose) by virtue of insertions made outside the parent control, were the parent - control not included. That is, a param only appears loose in the resolution - target, if it is also loose in its source catalog, or if its parent control in the - source catalog is not included in the profile.

In general, loose parameters (parameter declarations, param) are permitted - to support flexibility for referencing, especially making multiple references to a - parameter. It may be convenient to represent a parameter that is referenced from inside - two different controls, outside both of them, or to group parameters separately from - controls for simpler management. (This does not occur in the SP800-53 - catalog.)

Loose parameters (that is, with catalog or group parents, not - controls) appear in the target if (only if) elsewhere in the target, some content is - also propagated, which after modification contains an insert directive - referencing this parameter. (The param/@id appears on an - insert/@param-id elsewhere in the target document.) In the target, the - param appears in the location corresponding to its location in the source, - albeit ungrouped if no merge/as-is is given, and sorted with respect to - control elements at the same level: all param elements first, - followed by all control elements, conforming to canonical order for the - catalog or group container. this is a case where the - XML and JSON requirements are different.

When a catalog is organized by a merge/custom directive, loose parameters - are copied into the resulting grouping structure directly preceding the first control - appearing that contains an insert directive referencing that parameter.

Parameters that are not referenced by an insert elsewhere in the target, do not appear - in the target. While it is not formally invalid to include unreferenced (unused) parameters, - profile resolution requires that none be included except as a special option.

Merge phase

merge/combine - handling control collisions

Colliding controls (or clashing) describes the condition that - occurs when multiple invocations of controls with the same ID are given, and so a profile - resolution will result in duplicative and/or contradictory information. Even given a rule - against multiple imports of the same resource, it may frequently occur that in profiles - (especially profiles under development), multiple copies – and with variations – may be - invoked from different sources. For example, if a profile tailors another profile which - includes a control with amendments, and then (the top-level profile) includes the same - control directly from its original catalog, a collision will occur between these two - variants.

Generally such a collision is readily detectable as long as IDs have not been modified; - in other words, constraints over uniqueness (within document scope) of IDs will be - violated in resolved instances where two (perhaps different) representations of the same - control appear. Careful profile authors will be able to detect and prevent these resulting - problems.

Apart from handling problems and exceptions, however, for different purposes different - profiles might wish to apply different rules. OSCAL offers three such rules: the - directives for each are given as a value on the @method attribute of a profile - merge/combine element.

No merge/combine given

If no merge directive is given in the profile, or if a merge is - given without a combine, control or parameter clashes are treated as if - merge/combine[@method='keep'] were given. A profile with no - merge directive:

{{< highlight xml>}} - - -{{}}

is the same as

{{< highlight xml>}} - - - - - -{{}}
No merge combination rule

When a merge is indicated by merge/combine[@method='keep'], or not given, - the no merge combination rule is used. Clashing controls or parameters are not - merged. (They are kept.) Their groups are merged only if another merge - directive such as as-is is given. (The combination rules affect only the - handling of colliding controls, not their grouping in the target.)

{{< highlight xml>}} - - -{{}}

Under this directive, colliding controls will result in invalid results, as they will - both appear in the results with the same ID. Accordingly, this setting may be useful in - ensuring integrity of references to controls as given in the profile: if any included - control is called only once, clashing controls will not be produced and validation will - succeed.

{{< highlight xml>}} - … - - - - - - - - - - - - - - - -{{}}

In the target (showing control selections):

{{< highlight xml>}} - … - - … - … - - - … - … - -{{}}

In this case, downstream errors should be expected: the two a1 controls - clash with each other, as do the two b1 controls. To remove the duplicates, - either repair the source catalog to avoid the redundant invocations (usually a better - solution) or (when that is unavoidable) use a different merge combination rule.

Processors may optionally produce warnings when clashing controls are produced due to - redundant invocations.

Use first merge combination rule
{{< highlight xml>}} - - -{{}}

When the use first combination rule is applied, the first reference to a given - control, with respect to the document order of the source data, prevails over later - references. First is determined in reference to a top-down, depth-first traversal - of the profile import hierarchy. So if a profile is imported before a catalog, and the - imported profile presents a representation of a control also given in the catalog - import, the profile’s representation (perhaps modified) is taken. However, if the import - directive targeting the catalog appears first, the catalog's (unmodified) representation - of the control is included.

The same logic applies to parameters in the source catalogs, as modified by parameter - set directives.

{{< highlight xml>}} - … - - - - - - - - - - - - - - - -{{}}

In the target (showing control selections):

{{< highlight xml>}} - … - - … - … - - - … - -{{}}

The use first combination rule also affects back matter, - q.v.

Merge controls merge combination rule
{{< highlight xml>}} - - -{{}}

When the merge controls merge combination rule is applied, the processor - will merge all representations of a given control, as distinguished by ID, into a single - unified representation.

The single unified representation is assembled by aggregating all the contents of all - the (clashing) control instances and discarding replicated branches, so that only a - single instance of each distinctive element appears in the result. The order of the - copied contents will be their original order within their controls, given in the - original order of the controls in their source catalog, then sorted into canonical order - for control contents.

Example:

{{< highlight xml>}} - Control A1 - A-1 - pending - -{{}}

merging with

{{< highlight xml>}} - Control A1 - A-1 - ready - -{{}}

produces

{{< highlight xml>}} - Control A1 - A-1 - pending - ready - -{{}}

Note that groups are not merged by this rule; for that purpose, merge/as-is - or merge/custom should be used (in addition to the combine directive).

Since the effect of this merge rule is to drop data silently (when it is considered to - be redundant or duplicative), it should only be used on well-understood, well-controlled - catalog and profile inputs, whose potential clashes or collisions are known in - advance.

BR wants SP800-53 examples and points out prop[@name='status'] is not in it. - But this is not a guide to SP800-53 it is a spec for any profile - resolution.

Effects of combination rules on back matter

When profiles import from more than one resource (catalog or profile), not only is - there a potential for clashing controls, but also citation and resource elements - appearing in the back matter, may clash with other citations and resources, yielding - validation errors in the result when an ID appears more than once.

This situation is not remedied by the no merge combination rule. Under this - rule, any citation or resource that is referenced from an imported catalog or profile, - is included in the resolution target. This may result in replicated contents, where the - same element is given more than once in the target, producing violations of - ID-uniqueness constraints. For profiles that call controls from more than one import - pathway, the no merge combination may be most useful for debugging.

Under the use first rule (with merge/combine[@method='use-first']), - only the first citation with a given ID is kept from the set of citations - (gathered from all sources). Likewise only the first resource with a given ID - is kept from the set of resources. Note that uncontrolled identifiers may still clash – - for example, this will not prevent a citation and resource from - appearing in the result with the same ID (perhaps sourced from two different catalogs). - Maintenance and possibly revision of upstream data sets is necessary to prevent such - ambiguities.

Examples

How does the merge/combine[@method='merge'] (merge controls) - rule apply to back matter? Maybe the same as use-first. Or maybe use an approach - similar to controls.

Structuring the target

The overall organization of the target document at the top level has been described [See: Target catalog structure]. This section describes how a profile may dictate the body of - the target catalog, apart from its metadata or - back-matter.

The merge element, in addition to proposing a strategy by which to - disambiguate clashing controls, also includes directives that can be used to organize the - target catalog into a structure or hierarchy of groups. Two merge directives - are used to introduce structure into the target catalog, as-is and - custom. If neither is given, no structure is provided: parameters and - controls in the target appear in sequence, with no structure or grouping apart from what - is internal to the controls

Unstructured catalog output

Profiles that have neither of these directives are resolved as unstructured catalogs, - with no groupings of controls.

Unstructured catalog output is produced by emitting the contents of the sequence of - control selections produced in the selection phase, seeing to it that (for validity in - XML) they are sorted so that all loose param elements (that is, that do not - appear inside controls) appear before all control elements.

{{< highlight xml>}} - … - - … - - … - … - … - - - … - … - -{{}}{{< highlight xml>}} - … - … - … - - … - … - … - … -{{}}
Merging as is

An as-isdirective is used to reproduce the structure of a source catalog in - the target catalog. When more than one catalog is referenced by a profile, the - as-is directive produces a catalog that combines the grouping structures of - all the source catalogs.

(consider case of multiple imports of single resource – we need to track - catalog identity here)

Implicit inclusions under as-is

Under as is, a resolved profile’s structure is expected to replicate the - structure of source catalogs.

This is achieved by propagating, with all controls that are included, all groups that - they appear within, along with the groups’ IDs, titles and other contents, including - any parameters to be referenced in the target ([See: Loose parameters] ) or - part element children; but not including any controls not included in one - or another control selection, directly or indirectly. Controls may be included into a - group indirectly when merging as is, by virtue of containing controls - that have been included [See: Merging as is]

Groups that do not include controls that have been included (either directly or as - descendants of contained groups), are not propagated to the target.

This is slightly different from groups, which may in valid inputs have other contents - – besides titles, controls, or groups – that profile authors wish to see copied into - the customized catalog.

Example:

{{< highlight xml>}} - Basic Household - ... - - Kitchen cleanup - ... - - ... - - -{{}}

In this case the profile does not designate either control xyz-1 or - control xyz-1.2 for inclusion

{{< highlight xml>}} - - - - - -{{}}

The unmentioned elements are included, however, with their titles, because controls - that they contain are included. But control xyz-1.3 does not appear in - the target.

{{< highlight xml>}} - Basic Hygiene - ... - - Kitchen cleanup - ... - - - -{{}}

Note that this means there may be controls that are selected implicitly by - as-is merging, over and above controls actually designated in import - statements. Thus the control set, considered strictly, of the target of an - as-is process, will be different from the control set delivered by a - no merge process.

Processors may optionally provide services for detection of nesting and structural - issues related to the importing and merging of controls, including but not limited to - validation / detection utilities (for imports regarded as incorrect, incomplete or - otherwise subject to improvement); runtime warnings; or user interfaces.

Group contents under merging as-is

One title only. Other contents? Elements and controls are subject to the merge - combination rules. Other kinds of contents of groups …

Merging into a new structure: custom

The merge/custom directive provides a way to provide a target catalog with a - custom structure. It combines call or match directives, which work - as they do in selection, into groups, which provide the target with its structure.

The controls to be included must be selected in the profile's import. A call or match - appearing inside custom, if it refers to controls not selected, is - inoperative.

The structures given inside the custom assembly indicate the structure of - the target catalog. They produce this structure by mapping one for one. Unlike - as-is merging, there is no implicit inclusion of controls by virtue of - including descendant controls. Instead, all controls are included in the target in the - locations indicated by the custom structure.

Grouping controls inside a custom structure

A group element given in a custom structure results in an analogous - group. Its attributes (flags) are copied to the target catalog to appear - on the group in the target. All element contents inside the group, - including title, param, prop and part - elements are likewise copied into the target, appearing in the same order as in the - source.

Within custom, call and match elements reference - controls in much the same way as they do when given in import/include directives - a - control is either selected by @id (call.@control-id) or matched - using a pattern on its @id (match/@pattern).

A call results in including, at that point inside the new grouping, all - controls with the @id given by the call/@control-id. They should - be given in the same order as they appear in the control selection(s). Merge - combination rules apply. [See: merge/combine - handling control collisions]

A match results in including, at that point inside the new grouping, all - controls whose @id matching, as an XPath regular expression, the pattern - given in the match/@pattern. This may result in several or many controls; - again they are given in the same order as they have in the control selection(s). - Again, among clashing controls (that have the same ID), merge combination rules apply. - [See: merge/combine - handling control collisions]

{{< highlight xml>}} - … - - - - - - - - - - - - - - New Group I - - - - - - New Group II - - - - -{{}}{{< highlight xml>}} - … - - New Group I - … - … - … - - - New Group II - … - … - -{{}}

In this example, control a2 does not appear in the target - catalog, as a custom structure was indicated (by the presence of the source profile - merge/custom), but the control never referenced by a call - (or match) directive inside the custom structure.

When a custom structure references a control that is not included in any control - selection (in the import phase), the reference is inoperative. A processor may - signal a warning in this case.

Similarly, no error occurs if a control is selected (appears in a control selection - or even more than one), but it is never referenced from the custom - structure given. The control does not appear in the target catalog. Again, a - processor may optionally signal a warning if this occurs.

{{< highlight xml>}} - … - - - - - - - - - - - - - - - - New Grouping - - - - - - - -{{}}{{< highlight xml>}} - … - … - … - - New Grouping - … - … - - … - - -{{}}

In this case, no group container appears in the target for the controls - b2 and c2; because they appear unwrapped before the - group in the profile source, they appear the same way in the target - catalog. Control c2, however, appears in a subgroup group2 - inside the group with ID group1 , again reflecting the source - organization. Note also that id flags are copied.

Again, no provision is made to prevent duplicate or colliding controls from - appearing. Optionally, a processor may signal warnings when it determines that - controls from selections are designated to appear in the results more than once, due - to multiple colliding occurrences of call or match inside - custom.

with-child-controls inside a custom catalog structure

@with-child-controls works also: if child controls are selected, they can - be included implicitly by virtue of including their parents.)

How do we arrange for deeper nesting of controls in a custom - structure?

Modification phase

(Aka patching) Explicit modification of control content

There are two ways a control may need to be modified. Commonly, controls might be amended – - new material might be added. (For example, the priority marker properties P1-P3 in the - SP800-53 LOW MODERATE and HIGH baselines.) Less commonly, materials might be removed or - edited.

OSCAL does not provide for changing a control, but editing can be achieved by - removing contents and adding (edited) contents back. This can be achieved at the control - level, or, when constituent elements inside a control have distinct IDs, at more granular - levels as well. Features make it easy both to trim (filter) and to supplement catalogs.

In addition to any modification or adjustment to controls, this section of a profile is - used to set parameter values or other properties of parameters declared in catalogs and - referenced from their text. Parameters are propagated with the profile's setting into the - target catalog for its use.

Setting Parameters

Modification of parameter settings is indicated using set.

Parameters are not always given within controls. A profile resolution target must include - copies (with or without modifications or settings) of all parameters defined within the - source catalog, which are referenced from insert directives anywhere inside - included controls.

Accordingly, any parameter referenced by an insert in any source catalog is - copied from catalog source to target parameter propagation rules for merge/as-is, - merge/custom without any configuration required in the profile.

However, a profile should not reproduce parameters from source catalogs, which are not - referenced from insert directives.

When parameters are propagated, they may be modified by set directives given - in the profile.

If more than one set directive is given for the same parameter, all are - applied, in the sequence given in the profile. [XXX even when - merge/combine/@method='use-first'?]

  • A set/label replaces the param/label on the affected - parameter

  • A set/value - or a set/select replaces any - param/value or param/select on the affected parameter

  • Other elements given in a parameter set are added to the affected - parameter, after elements of the same name

  • The prescribed order of elements in the affected parameter is retained: - label; usage; constraint; guideline; - value or select (a choice); and link.

[example]

{{< highlight xml>}} - Password length - 10 - -{{}}{{< highlight xml>}} - - -{{}}

Note that select replaces value:

{{< highlight xml>}} - Password length - - -{{}}
Setting a missing parameter

A set directive whose @control-id does not correspond to any - control in the resolved catalog, is inoperative.

Optionally, a processor may issue a warning where such directives are found.

Altering controls

A control can be altered by an alter directive on a control. The - @control-id flag on the alter indicates the control to which the - alteration is applied.

Adding contents to controls

Contents may be added to controls using an add directive inside an alter directive. - There are two forms of alteration: with implicit and explicit bindings.

Implicit binding

An add directive with no id-ref flag is taken to apply to the - control as a whole. Its position flag may be either of two values: - starting and ending.

The contents of the add directive are then added to the control contents in the - target, either after its title when position is - starting, or at the end if its position is ending, or not - given.

However, control contents in catalogs must appear in the order title, param, - prop, link, part, control. Subsequent to adding new elements, the control - contents are sorted to appear in the required order. As a consequence, a new - prop appears after any prop already in the control, when - position is ending, or not given,, or before any - prop in the control when position is - starting.

When add has no @ref-id (has an implicit binding), the position - values before and after are treated like - starting and ending, respectively. The schema - permits these values.

An addition operating on a control with implicit binding and position - starting

{{< highlight xml>}} - Basic precautions - ready -{{}}{{< highlight xml>}} - - enumerated -

Only for adult use.

 - -{{}}{{< highlight xml>}} - Basic precautions - enumerated - ready -

Only for adult use.

 -{{}}

Position is starting but the new part is added after the - existing prop, because prop elements must always occur - first.

An addition operating on a control with implicit binding and position - ending

{{< highlight xml>}} - Basic precautions - ready -{{}}{{< highlight xml>}} - - enumerated -

Only for adult use.

 - -{{}}{{< highlight xml>}} - Basic precautions - ready - enumerated -

Only for adult use.

 -{{}}

The add/@position is ending so the new prop - appears after the existing prop.

Explicit binding

An explicit binding on an addition permits inserting new contents anywhere in a - control, not only at the top level. It is given by a @ref-id flag on the - add directive. The value of the @ref-id must correspond to the - value of an @id flag on an element inside the control, and not the control - itself. If ref-id does not correspond to such a value, the add - directive is inoperative. Optionally, a warning may be issued in such a case.

The element with @id equal to the @ref-id is considered the - target of the addition.

Additionally, with an explicit binding given by a @ref-id, - @position may have any of the values starting, - ending, before and after.

When position is starting or ending, the new - contents are added at the beginning or ending of the target element, inside that - element, as are additions into controls (using implicit bindings).

Additionally, a position given as before indicates the - addition should be made directly before the target element, while after - indicates the addition should appear directly after the target element.

Unlike additions with implicit bindings, an explicit binding does not - provide for sorting of newly added elements to ensure correct ordering. - Consequently, profile authors must take care that additions they make into control - contents using explicit bindings will produce results valid to the catalog - schema.

An addition operating on a control with explicit binding and position - after

{{< highlight xml>}} - Basic precautions - ready - -

Collect recycling for pickup.

 -

Sweep surfaces free of dust.

 - -{{}}

Note that the add directive identifies the element with @id - a1.b1 as its target.

{{< highlight xml>}} - - allocated -

Unavailable on weekends.

 - -{{}}{{< highlight xml>}} - Basic precautions - ready - -

Collect recycling for pickup.

 - allocated -

Unavailable on weekends.

 -

Sweep surfaces free of dust.

 - -{{}}

The position is after so both elements inside - add are added after (not inside) the target element. Since the target - element is inside another part in the control, the new additions appear - there as well.

Note that the result in this case will be schema-invalid since a prop - may not occur directly following a part. A better result can be obtained - (a better target may be defined) by using two add directives, to insert - the new prop separately - before any part elements in the target.

Usage of add directives modifying controls inside controls

OSCAL supports control extensions inside controls in the form of control - elements inside control elements. Because the semantics of the - add directive target any (element) contents of controls, they can be used - to target these control extensions for modification as well as other contents.

Because such a control can already be modified using implicit bindings, it is - recommended that they not be targeted with explicit bindings. Using an implicit - binding supports more robust alteration since contents in the target can be ordered - properly by the resolution processor. XXX can we guarantee valid results here - and do we have to specify a sort/order? However, it is not an error to - target control elements in this way, manipulating them in the same way as other - targets may be manipulated.

Removing contents from controls

Contents inside controls can be removed from them in catalog targets. In combination - with adding new contents, this feature can be used to edit controls as well as amend - them.

A remove directive inside an alter directive identifies an - element or set of elements inside a control to be removed. It does this using any of - four flags:

  • @id-ref, like add/@id-ref, matches an element by its - @id value.

    Because @id values are unique, the remove directive will remove only a - single element.

  • @name-ref keys to the @name attribute on any element inside - the control.

    Any element inside the control with the assigned name, is removed.

  • @class-ref keys to the @class attribute on any element inside - the control. All elements with matching class are removed.

  • @item-name keys to the element or property name; for example, - <remove item-name='prop'/> has the effect of removing all - prop elements from inside the control. (NB: what about in JSON - where names are often group names? Can we support removal by item - name?)

These are examined in the order given here; the first one that appears is used. Thus a - remove directive with both a name-ref and a class-ref, uses only - the name-ref. (Or should the effect be cumulative?)

Unlike an add directive, a remove may not be bound implicitly to - the control; its binding, to contents inside the control, must be explicit.

To remove an control, simply avoid selecting it into the profile, or exclude it - specifically using import/exclude.

As with add, a remove that targets any element outside the control, is - inoperative. Similarly, a remove directive that indicates that all prop - elements should be removed from the target catalog, applies only to prop

Implicit alterations

Finally some alterations are made automatically.

For example, link elements in source data representing cross-references in a - catalog, may no longer be effective in catalogs produced from profiles, which have not - included the elements (controls or other) to which the links refer.

Either: expand the links to refer back to the source catalogs; or remove the - links.

Note: we could also expand links to point back to the (resolved) source, - particularly if it is described in back-matter as a resource...

Null profile

A null profile is a profile that imports a catalog and selects all its controls - without modification. A truly null profile – that is, with only an import and nothing - else – does not return its imported catalog unchanged. But the changes it makes can be useful. - This makes a null profile or its near-null variants, as described in this - section, potentially useful for catalog management, design and use, as described in this - section.

Importing and nothing else

{{< highlight xml>}} - ... - -{{}}

In the target, the catalog group structure and all hierarchy is removed; its controls are - all returned in sequence. Any loose parameters in the catalog not referenced in a control, - are dropped.

This is the same as

{{< highlight xml>}} - ... - - - - - - - - -{{}}

all/with-child-controls='no'

The same, except that only top-level controls are included, not descendants.

unit test this

including merge directives

Using merge as-is='true', the grouping hierarchy of a source catalog can be - reflected in the target.

This enables a near-null profile to define a normalization or cleanup pass on a catalog, as - it will have the result of removing dangling references and orphan parameters, without - otherwise affecting controls.

unit test this too, especially with more than two levels of control hierarchy as - well as groups

unit test this

Options

For conformance, an OSCAL processor must deliver results of profile processing, in a basic - configuration, exactly as described in these specifications with no elaboration.

Conformance does not preclude providing additional features, however, including elaborated - outputs, in an optional mode. Such features could include offering warning or process - exception handling (appropriate to workflow) not described here; outputs provided with - comments or extra structure to support tracing or analytics; or gateway or - Draconian modes that would provide user assistance or refuse to deliver results for - inputs considered erroneous in a workflow.

Profile tools and utilities

  • rendering - showing both unresolved (raw) and resolved profiles

  • editing / integrity checking

  • rewriting/normalization

  • diffing

  • deriving a profile as the delta of two catalogs (base and tailored)

\ No newline at end of file