Starting to represent higher-order semantics in SP800-53/A ODPs

[wendellpiez]

User Story:

In the forthcoming release of an integrated Revision 5 SP 800-53 with Appendix A (Assessment Procedures) we have something not so new, a bit of complexity in an ODP (organizationally-defined parameter) --

<param id="au-02_odp.02">
   <prop name="label" class="sp800-53a" value="AU-02_ODP[02]"/>
   <label>event types (subset of AU-02_ODP[01])</label>
   <guideline>
      <p>the event types (subset of AU-02_ODP[01]) for logging within the system are defined;</p>
   </guideline>
</param>

What is shown here in the label property really ought to be in a link and/or constraint (at least).

Goals:

• Post and consider updating (patching) data in this repository with an enhanced parameter tagged to represent this relation and the constraint being expressed
• Define a pathway forward for identifying and tagging other such logical or definitional dependencies in SP800-53 and migrating them into OSCAL

Dependencies:

Does exploiting the OSCAL models in this way to capture semantics of the data have an impact on how the parameters are represented and managed elsewhere in FISMA systems? (Potentially, yes.)

This is connected to Issue tbd in OSCAL, regarding development of any OSCAL-related guidance and modeling.

Acceptance Criteria

• All readme documentation affected by the changes in this issue have been updated.
• A Pull Request (PR) is submitted that fully addresses the goals of this User Story. This issue is referenced in the PR.
• The CI-CD build process runs without any reported errors on the PR. This can be confirmed by reviewing that all checks have passed in the PR.

{The items above are general acceptance criteria for all User Stories. Please describe anything else that must be completed for this issue to be considered resolved.}

[wendellpiez]

See also: AC-03(07) and AC-03(09) ODPs 1 and 2.

[aj-stein-nist]

We need to discuss with @wendellpiez to ensure this is actually done or there are other remaining tasks.

[david-waltermire]

We should consider dropping links into the labels to link to the related ODP.

We should also consider adding a link for rel=subset-of or something similar.

[wendellpiez]

Next (planning):

• Add Schematron to detect apparent untagged references to controls (via control ID regex)
  • in titles, labels, parameter contents?
• Report on detected issues (here)
• Sketch transformation to enhance these
• Consider: can we get more than the link? Can we add more links or relations?

[wendellpiez]

I now have work in my branch that exposes where references to controls and control parts (including ODPs) appear untagged in the SP800-53/A source XML.

The full listing looks like this:

• part[@id='ac-3.3_gdn']/p points to AC-3(4)
• part[@id='ac-3.3_gdn']/p points to AC-3(4)
• part[@id='ac-3.3_gdn']/p points to AC-3(4)
• param[@id='ac-03.07_odp.02']/guideline/p points to AC-03(07)
• param[@id='ac-03.09_odp.02']/guideline/p points to AC-03(09)
• param[@id='ac-16_odp.07']/guideline/p points to AC-16
• param[@id='ac-16_odp.08']/guideline/p points to AC-16
• part[@id='ac-16_obj.c-1']/p points to AC-16_ODP[01]
• part[@id='ac-16_obj.c-2']/p points to AC-16_ODP[02]
• param[@id='au-02_odp.02']/label points to AU-02_ODP[01]
• param[@id='au-02_odp.02']/guideline/p points to AU-02_ODP[01]
• param[@id='au-05.02_odp.01']/guideline/p points to AU-05(02)
• param[@id='au-05.02_odp.02']/guideline/p points to AU-05(02)
• param[@id='au-12_odp.01']/guideline/p points to AU-02_ODP[02]
• part[@id='au-12_obj.a']/p points to AU-02_ODP[01]
• part[@id='au-12_obj.c']/p points to AU-02_ODP[02]
• part[@id='au-12_obj.c']/p points to AU-03
• part[@id='ca-3.7_obj.a']/p points to CA-03
• part[@id='cm-6_obj.b']/p points to CM-06
• part[@id='ia-5.1_smt.b']/p points to IA-5(1)(a)
• part[@id='ia-5.1_gdn']/p points to IA-5(1)(h)
• part[@id='ia-5.1_obj.b']/p points to IA-05(01)(a)
• param[@id='ir-04.03_odp.01']/guideline/p points to IR-04(03)
• part[@id='ir-4.3_obj-2']/p points to IR-04(03)
• part[@id='mp-4_smt.b']/p points to MP-4
• part[@id='mp-4_obj.b']/p points to MP-04_ODP[01]
• part[@id='mp-4_obj.b']/p points to MP-04_ODP[02]
• part[@id='mp-4_obj.b']/p points to MP-04_ODP[03]
• part[@id='mp-4_obj.b']/p points to MP-04_ODP[04]
• part[@id='mp-7_gdn']/p points to MP-7
• part[@id='pm-7_gdn']/p points to PM-7
• param[@id='pt-02_odp.01']/guideline/p points to PT-02_ODP[02]
• part[@id='sa-17_gdn']/p points to SA-17
• part[@id='sc-13_obj.b']/p points to SC-13_ODP[01]
• param[@id='sc-30.05_odp.02']/guideline/p points to SC-30(05)
• part[@id='si-6_smt.b']/p points to SI-6
• part[@id='si-8_asm-examine']/part[@name='assessment-objects']/p points to CM-01

Note the working XSLT captures the actual text not just the locations; with some work it could produce a variant in which these were re-tagged. (We would produce a set of templates for this list, each of which would make the appropriate patch.)

If we were to wrap each of these as an <a href="#{targetID}> (inline anchor) this would at least provide a link.

An example of how this would look:

Before:

<param id="ac-03.09_odp.02">
  ...
  <guideline>
    <p>controls to be provided by the outside system or system component (defined in AC-03(09)_ODP[01]) are defined;</p>
  </guideline>
</param>

After:

<param id="ac-03.09_odp.02">
  ...
  <guideline>
    <p>controls to be provided by the outside system or system component (defined in <a href="#ac-03.09_odp.01">AC-03(09)_ODP[01]</a>) are defined;</p>
  </guideline>
</param>

Comments?

One comment I have is that while this is worded as a cross-reference, it might better be worded more directly:

<param id="ac-03.09_odp.02">
  ...
  <guideline>
    <p>controls to be provided by <insert type="param" id-ref="ac-03.09_odp.01"/> are defined;</p>
  </guideline>
</param>

... but this would entail a change to the copy.

Another comment is that this does not actually capture where there are dependencies (as here).

[wendellpiez]

Also noting a couple of these are self-references, as in MP-7 and PM-7 guidance. (Tag these also?)

[wendellpiez]

Working branch is here: https://github.com/wendellpiez/oscal-content/tree/issue86-opd-analysis

[aj-stein-nist]

AJ talked with Wendell and this seems like the pre-work of analyzing this before 5.2 was a spike effort. We will consider this issue to track that. @wendellpiez agreed to create the follow-on issue to move the spike branch ☝️ with that analysis into production catalogs after 5.2 is released, so we will have to move it accordingly on the backlog.