Profile specification #1017

stephenbanghart · 2021-08-30T19:16:01Z

Committer Notes

PR to merge profile resolution specification into origin. Total document rework, includes several small model changes.

All Submissions:

Have you followed the guidelines in our Contributing document?
Have you checked to ensure there aren't other open Pull Requests for the same update/change?
Have you squashed any non-relevant commits and commit messages? [instructions]
Do all automated CI/CD checks pass?

Changes to Core Features:

Have you added an explanation of what your changes do and why you'd like us to include them?
Have you written new tests for your core changes, as applicable?
Have you included examples of how to use your new feature(s)?
Have you updated all OSCAL website and readme documentation affected by the changes you made? Changes to the OSCAL website can be made in the docs/content directory of your branch.

david-waltermire

Here are a few comments. I'll continue to add more in a separate review.

src/specifications/profile-resolution/profile-resolution-specml.xml

david-waltermire · 2021-09-07T15:29:45Z

src/specifications/profile-resolution/profile-resolution-specml.xml

+        <p>A <term>profile</term> in OSCAL represents a selection and configuration of a set of
+            <term>controls</term>. 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) <q>catalog</q> and its <q>profile</q>, the latter being a
+          selection, adaptation and organization of controls, as distinct from the catalog from
+          which those controls are derived.</p>
+        <p>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. </p>
+        <p>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.</p>
+        <p>In order to support these semantics – because whatever data set is sourced by a profile,
+          it must <q>look like a catalog</q> – 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 <q>the same</q> is meaningful and testable in this context.</p>


This is more a description of profile resolution (and profiles), which should be moved into the introduction/purpose. This section doesn't adequately define what the scope of this document is. Consider focusing this text on what this document covers directly.

As I understand @stephenbanghart hasn't done much with this section yet? Agree it could be flattened and cut. One or two bits (such as how outputs may not be formally valid to OSCAL for bad inputs) could be pulled to elsewhere? Other bits might already be stated elsewhere, or not worth stating.

Also with DW wonder if the header is right for this section at least as it stands. Basically I think it says "btw because of the way catalogs work in the wild, profile resolution cannot guarantee OSCAL valid outputs for any arbitrary combination of valid OSCAL inputs (catalogs and/or upstream profiles). I think that is correct but not sure where/how it should be stated.

@wendellpiez Yes. I believe what you are stating above is correct.

I agree with Dave. You can think at "Why" we need a clear specification that defines the rules, vs "How" or the resolution rules (scope) of specification.

src/specifications/profile-resolution/profile-resolution-specml.xml

david-waltermire · 2021-09-13T18:15:06Z

src/specifications/profile-resolution/profile-resolution-specml.xml

+          operations over <q>raw catalogs</q> 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. </p>


It may be also necessary to tailor controls by adding or removing information to provide more context for a given use of the controls.

#1043
Could you elaborate a bit more on your suggestion?

You talk about making adjustments. You should call this tailoring.

src/specifications/profile-resolution/profile-resolution-specml.xml

stephenbanghart · 2021-12-03T23:03:47Z

Remaining blockers for first draft are resolved. Once Metaschema changes pass validation I'd consider the PR ready for it's develop merge. Re-requesting review to verify.

Co-authored-by: David Waltermire <[email protected]>

…scussions for info.

…work.

…anup

… with "as-type:empty".

david-waltermire

LGTM. Thanks for all the hard work on this draft!

* Updated readme in utils/util (usnistgov#1014) * First draft of profile resolution specification rework * Integrated feedback from 8/31 meeting w/Dave and Wendell * Removed of Explicit/Implicit selection. Added last examples, Target section cleanup * Resolves usnistgov#1046 usnistgov#1043 usnistgov#1042 usnistgov#1041 usnistgov#1040 usnistgov#1039 * Added "flat" * Update specml-html-preview.xsl Co-authored-by: David Waltermire <[email protected]> Co-authored-by: Wendell Piez <[email protected]> Co-authored-by: Stephen Banghart <[email protected]>

stephenbanghart requested review from david-waltermire, wendellpiez and iMichaela September 2, 2021 18:04

david-waltermire suggested changes Sep 13, 2021

View reviewed changes

david-waltermire marked this pull request as ready for review September 13, 2021 14:11

david-waltermire reviewed Sep 13, 2021

View reviewed changes