Valid OSCAL File Fragments

[brian-ruf]

User Story:

As an OSCAL content user, I sometimes need to exchange only a portion of an OSCAL file (file fragment) with other parties. For example, the entire SSP must be reviewed annually, but the system inventory within the SSP must be submitted monthly (along with scanning data and POA&M snapshots).

I need a way to send an OSCAL file fragment that still allows OSCAL validation tools to recognize the file fragment as valid.

Goals:

Provide a mechanism for exchanging and validating OSCAL file fragments.

Dependencies:

None.

Acceptance Criteria

• All OSCAL website and readme documentation affected by the changes in this issue have been updated. Changes to the OSCAL website can be made in the docs/content directory of your branch.
• 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 defined mechanism must allow a portion of an OSCAL file to be extracted and be recognized as valid within reasonable constraints.

[brian-ruf]

Case Study: As mentioned in the issue above, the SSP model includes a system inventory. FedRAMP requires a CSP to deliver the entire SSP (including system inventory) to FedRAMP annually. FedRAMP also requires a CSP to deliver their up-to-date system inventory monthly (along with monthly system scans and POA&M snapshot).

The CSP should be able to extract the relevant data under /system-implementation/system-inventory from the System Security Plan and deliver it. In this example, the file must still have other OSCAL content that is not relevant to system-inventory, such as an import-profile assembly, or it will fail validation.

We need a mechanism that indicates this is an OSCAL file fragment, thus requires relaxed validation.

Minimally, a validation mechanism would still enforce the minimum requirements of any OSCAL file (title, last-modified, UUID, etc.), yet would relax any model-specific cardinality rules to zero. (No field would be "required" except as noted above.)

Ideally, a validation mechanism could be configured to identify which portions of the OSCAL file fragment should be subject to more complete validation requirements. For example, the validation mechanism could be directed to still enforce required fields for children of system-inventory, even though it is relaxing those requirements for the rest of the ssp-specific structure.

[bradh]

This feels like maybe a different format within the implementation layer. Possibly the implementation layer needs to be finer grained, and use some kind of include mechanism.

[brian-ruf]

@bradh I'm open to any solution that allows OSCAL file fragments.
This came up verbally a few weeks ago with @david-waltermire-nist and @wendellpiez, but other topics overshadowed our plan to discuss it. For now It's more of a place-holder to make sure we don't lose sight of it.

[wendellpiez]

As for today's question: on the XML side, a document rooted at system-inventory will be valid. How it is to be integrated with other SSP pieces in a workflow is not defined (the other and more difficult part of Brian's question), but formal validity of such a fragment is not a problem.

This is not currently the case on the JSON side, but we know how to ameliorate that. The current thinking is to provide anything defined as an assembly in a metaschema, as a valid root for an instance.

How document assembly -- an include mechanism -- is to be implemented is a somewhat different question. XML has two standard widely adopted mechanisms -- external parsed entities, and XInclude -- offering different affordances and tradeoffs. (For the curious I can be more specific.) Both of these deliver functionality as specified, are well understood, and are implemented in commodity tooling; this makes me reluctant to reinvent that wheel. Especially since on the JSON side things appear more more fluid. (No one seems to have thought much about how to model hypertext resources in JSON. Heh. JSON pointer - as I understand, designed to support graph structures - might be useful.)

All that leads me to feel that managing dynamic assembly of OSCAL instances from fragments is an implementation question, not something that needs to be supported by the standard. (Yet.)

On the other hand, the need stated by @brianrufgsa is real, and we can help him with that.

[david-waltermire]

@wendellpiez and @david-waltermire-nist will organize some thoughts on this topic. A meeting to discuss this issue will follow.

[wendellpiez]

@brianrufgsa could you please restate the requirement here?

Note that currently, an XML document rooted at system-inventory may be schema-valid against the SSP XSD. Assuming all its pieces are correct, etc. (Maybe the documentation should be updated so as not to create an impression this is not the case?)

A JSON document rooted at system-inventory will not today be valid against the SSP JSON Schema; if we make this modification to permit it (given this is already okay using XML/XSD) would that address the need?

Yet the complexity of the choreography here (doc A is submitted annually but its logical or nominal component Ab is submitted monthly) makes me think that schema validation alone is not going to support all applicable constraints (even automatable ones): there will be other considerations as well and other kinds of checking to be performed including content-checking.

So I am also led to wonder (oppositely) if the problem isn't actually deeper: does a standalone system inventory need its own document-level metadata? Maybe this is about not only schema validation, but modeling as well. Adding metadata as an optional element inside system-inventory and perhaps other elements could be a solution ... to some problems. Not yet sure if that would address the use case -- and it does introduce other complications.

[brian-ruf]

@wendellpiez, simply putting system-inventory at the root may be valid syntax, but does not address the requirement.

Any inventory fragment must at least include the system name, system owner's organization (CSP name), and a publication date.
These are snapshots in time of the inventory, which are correlated with security scans logs (also snapshots in time), thus the publication date is important for processing.

Further, the system-inventory assembly relies on component assembly, and the metadata assembly (to reflect who is responsible for the components and inventory-items).

To properly reflect the inventory as an SSP fragment using the current SSP syntax, I would need the following assemblies/fields:

• metadata (assembly)
• system-characteristics/system-name (field)
• system-implementation/component (assembly)
• system-implementation/system-inventory (assembly)

Unfortunately, I suspect most fragment examples, are going to be more complex than just using an assembly at the root. This is why I verbally suggested an approach where we can put a directive at the top of the OSCAL file which essentially indicates to syntax validation tools that required fields should not be enforced.

Perhaps using such a directive would still require title, last-modified, and an updated root @id attribute, and still performing all other syntax checks. Essentially this would treat all other fields/assemblies with a cardinality of "1" as if they were "0 or 1", and all fields/assemblies with a cardinality of "1 or more" as if they were "0 or more". All other syntax validation would process normally.

I would love to see something like a fragment attribute at the root element, so I could specify something like:

<system-security-plan id="12345" fragment="inventory">
   <metadata>
      <!-- detail -->
   </metadata>
   <system-characteristics>
      <system-name>This System's Name</system-name>
   </system-characteristics>
   <system-implementation>
      <component>
         <!-- detail -->
      </component>
      <system-inventory>
         <!-- detail -->
      </system-inventory>
   </system-implementation>
</system-security-plan>

This would allow syntax validation tools to still process the file, relaxing only the cardinality, while providing a specific value for fragment that can be used by schematron or other downstream mechanisms to perform validation tailored to that fragment type.