Preserve Reference Labeling Format

[brian-ruf]

User Story:

As an OSCAL user, I can present information from an OSCAL catalog or profile, such that the original reference labeling is similar enough to the original source document as to not be a distraction to a cyber security practitioner who is familiar with the original source document. This can be an optional extension to the OSCAL standard currently defined, and does not need to replace existing unique identifiers currently in use in OSCAL.

For example:
NIST SP 800-53 Rev 4 consistently presents controls with parts as follows:

For controls, the OSCAL content should capture the "a." as meta-data to the part that states, "Develops, documents, and disseminates ..."
Likewise, the OSCAL content should capture the "1." as meta-date to "An access control policy that ..."

In contrast, NIST SP 800-53 Rev 4 also consistently presents control enhancements with parts as follows:

For control enhancements, the OSCAL content should capture the "(a)" as meta-data to "Is uniformly enforced across all subjects ..."; and should capture the "(1)" as meta-data to "Passing the information to ..."

Current OSCAL content uses the structures similar to the following to capture labels:

<part class="objective">
  <p>Determine if:</p>
    <part class="objective" id="ac-2.3_obj_3.1">
      <prop class="name">AC-2(3)[1]</prop>
      <p>the organization defines the time period after which the information system automatically disables inactive accounts; and</p>
     </part>
   </part>
</part>

This pattern is repeated in the SP 800-53 content in a number of parts. An approach needs to be addressed that can work for all of these use scenarios.

Goals:

• When transforming OSCAL data for presentation on a screen or printed document, the reference labeling for the parts should appear as similar as possible to the original source document. The structured OSCAL content must provide a basis to do this.
• When removing a labeled item, the original labeling for items must be preserved.
• Update declarations model to support validation of labels.

Dependencies:

None.

Acceptance Criteria

• Catalog and profile schemas have been adjusted as needed;
• Samples, examples and reference data sets have been adjusted and are demonstrated to be valid to the new schemas.

[wendellpiez]

@brianrufgsa let's assume for sake of argument the 'name' property captures only the last term of a punctuated series (using brackets/parens etc). - a design I think we may agree we should prefer -

<part class="objective" id="ac-2.3_obj_3.1">
  <prop class="name">(3)</prop>
  <p>Determine if:</p>
    <part class="objective" id="ac-2.3_obj_3.1">
      <prop class="name">[1]</prop>

With the inner part element as context (that is, assuming we have part ac-2.3_obj_3.1 in our hand and we wish to know how it is labeled), the XPath prop[@class='name'] will return "(3)" (a string). Another XPath however:

string-join(ancestor-or-self::part[@class='objective']/prop[@class='name'],'')

will produce (in this case) the string "(3)[1]". To do so it traverses through the element structure addressing elements (here, multiple elements), returning their values, and joining these strings together with a library function.

It's also easy enough to do it the other way, of course, assuming data with this consistency -- we actually have that. So if you look at a resolved-and-rendered version (an HTML file) of the catalog, you may see something closer to the PDF than the source XML has it.

This is what I mean by not needing to inscribe (encode) both forms or any mapping between them directly into the data, at least in this case where it is simple enough for the mapping (function) to be left implicit.

However, we might decide (another principle) it isn't right to do it one way with assessments, and another way with objectives. But the PDFs of SP800-53 and 53A have this different (unless I'm mistaken). So we are faced with the question of whether to align them and if so, which way.

Of course, whatever we decide, an assumption has to be made that the receiving system knows what it needs to do and when, and has a clue as to how. My own expectation is that when conventional usages like this one come into play (the production of a document-scoped handle for reference for things by spelling out multiple levels of the hierarchy), smart analysts (and their systems) usually know about this or learn.

I mean to say (short version), either "short" or "long" form is perfectly okay from an XML perspective, although when given a choice we'll usually go for short.

FWIW I am seeing both AC-2(f)[1] and AC-2(h)(3) as an illustration of the lack of consistency between [square] bracketing and (round) parenthesizing. Not that this in itself bothers me: I think we are safe here capturing the data as given. (Especially as the id format normalizes that difference away.)

Sorry for the length, I hope it isn't too much trouble!

[wendellpiez]

After discussion with @brianrufgsa we've decided to go with the "screen friendly" version, i.e. "[a]" not "AC-2(1)[a]"). Among other reasons, since we have referential integrity (and sequencing) in the @id, we don't need to optimize for addressing, and can favor the display string. I am taking this work item and will forward a revised SP800-53 catalog, with these changes, for him to review and present (probably as a PR).

[wendellpiez]

I took this on as a work item only to discover one of my assumptions has been wrong -- that this meant changing a decision I had made earlier in (re)formatting the SP800-53 data. It turns out this decision wasn't mine - these values here are as given in NVD XML source for this data, and our pipeline is providing no numbering or formatting support whatsoever, but only passing the values along as given. So I am following the principle, Fidelity to the Source. (After conversion we have logic to validate the received values for consistency and correctness, but that is a separate issue.)

See screenshot attached. Since truncating the long "address value" is as easy as filling out the "formatted for display" version (that is, it is as easy to convert "AC-4 (1)" into "(1)" as the reverse), I propose leaving the long values in the data and to rely on styling logic to correct/optimize the display (something demonstrated in current HTML XSLT).

Apologies to @brianrufgsa. @david-waltermire-nist may have to take a look at this.

[wendellpiez]

Actually now see commit b0b8943 - wherein names (labels) of subcontrols are not rewritten, only labels of items and subitems at various levels inside controls or subcontrols.

FWIW, we could polish this further by changing these from <prop class="name">[1]</prop> to <prop class="label">[1]</prop> which could be more accurate. (In NVD XML it is 'number' which is perhaps not right either.)

[david-waltermire]

I am a fan of making the name -> label change.

[wendellpiez]

@david-waltermire-nist please also check the ad-hoc @id I added to this catalog? (which can be adjusted) it is NIST_SP-800-53_rev4_catalog.20180619

[brian-ruf]

I like the change to label as well.

On Tue, Jun 19, 2018 at 5:39 PM David Waltermire ***@***.***> wrote: I am a fan of making the name -> label change. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#175 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Aa82NwUMSvKM5liO8f1uLBYq5kavQ-yqks5t-W9ygaJpZM4UJCnv> .

-- Best Regards, Brian J. Ruf, CISSP, PMP FedRAMP PMO 703-625-3702 (Direct/Cell)

[brian-ruf]

June 21 Status: Dave, Brian, and Wendell discussed this on June 19. The final agreement was to just capture the last portion of the label (ie. just "1.", not "AC-1.a.1."). I believe Wendell has already made these changes.

As a follow-up Wendell suggested using <prop class="**label**">[1]</prop> instead of <prop class="**name**">[1]</prop>
Dave and Brian agreed with that change as well.

[david-waltermire]

6/21/2018 Status

This issue is complete and is posted as part of PR #201.

[iMichaela]

7/25/2018 Status

PR #201 was reviewed and merged but this work does not appear to be part of the PR #201. PR #201 has no XML examples at all.

[anweiss]

@iMichaela it looks like the XML examples were moved into the content/ folder. I opened #222 to do the same for the JSON examples.

[wendellpiez]

Using this workspace to track the "re-emerged" issue as reported by @brianrufgsa.

In PR #261 is a revised catalog per requirements for labeling (to reflect presentation-as-published). Merged objectives now follow a different labeling scheme from the main text.

@brianrufgsa if it's any comfort, the code was in place only commented out. Now improved even a bit more.

Here are a couple of screen shots. The files are unfortunately too big for git diff; this shows a couple of views in an XML diff tool. Or download the files themselves.