Catalog control parts require NIST-specific part structure even with a different namespace

[xee5ch]

Describe the bug

As a developer of OSCAL catalog content and using OSCAL-enabled tools, I would like to be able to define a control without part[@name="statement"] or a corresponding prop[@name="status]/@value of "withdrawn" for parts outside of the OSCAL namespace.

This requirement is enforced by the oscal-catalog-control-require-statement-when-not-withdrawn constraint below, which needs to be adjusted.

OSCAL/src/metaschema/oscal_catalog_metaschema.xml

Lines 222 to 230 in 1eb7d81

	<expect id="oscal-catalog-control-require-statement-when-not-withdrawn" target="."
	test="prop[@name='status']/@value=('withdrawn','Withdrawn') or part[@name='statement']"/>
	<allowed-values id="oscal-control-prop-name"
	target="prop[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name">
	&allowed-values-control-group-property-name;
	<enum value="status">The status of a <code>control</code>. For example, a
	value of 'withdrawn' can indicate that the <code>control</code> has
	been withdrawn and should no longer be used.</enum>
	</allowed-values>

Who is the bug affecting

Developers of OSCAL catalogs with data that is not in the core OSCAL namespace.

What is affected by this bug

Metaschema, Modeling

How do we replicate this issue

1. Create a catalog like so.

---
catalog:
  uuid: 546aecef-bad9-4cfe-9679-edd5775f9d06
  metadata:
    title: Example Catalog for Issue
    published: 2025-02-20T00:00:00Z
    last-modified: 2025-02-20T00:00:00Z
    version: alpha
  groups:
  - id: g1
    class: family
    title: Example Group
    controls:
      - id: g1-c1
        class: g1
        title: Example Control
        parts:
        - id: g1-c1-p1
          name: recommendation
          ns: https://example/ns/oscal
          prose: "Example"

3. Validate with the CLI.
4. Observe the following error.

oscal-cli validate '/home/me/catalog.yml'
Validating 'file:/home/me/catalog.yml' as YAML.
Validation identified the following issues:
[ERROR] [/catalog/group[1]/control[1]] catalog-control-require-statement-when-not-withdrawn: Expect constraint 'prop[@name='status']/@value=('withdrawn','Withdrawn') or part[@name='statement']' did not match the data at path '/catalog/group[1]/control[1]'
The file 'file:/home/me/catalog.yml' is invalid.

Expected behavior (i.e. solution)

This catalog validates without an error.

Other comments

I will propose a more targeted constraint change in an upcoming PR to resolve this issue.

Revisions

No response

[iMichaela]

@xee5ch - The issue you are raising is not a bug - it was determined at the time the catalog schema was created, that a control cannot exist without a statement that needs to be considered for implementation and assessment. With that said, there are catalogs I am aware of that would have informative statements (not a requirement) with normative children controls. I will put this issue in the queue, but will remove the "bug" label for the reasons stated above.

[xee5ch]

@xee5ch - There issue you are raising is not a bug

The key detail I mentioned in the bug report and the sample catalog is that NIST asserts that is true for use of statement the way NIST uses it for its own purposes (with the namespace definition in has-oscal-namespace('http://csrc.nist.gov/ns/oscal')), but not all uses of statement, including custom ones where others say they want to have a different kind of part and not follow the NIST catalog structure. The following constraint syntax makes that clear.

OSCAL/src/metaschema/oscal_catalog_metaschema.xml

Lines 254 to 266 in 1eb7d81

	<allowed-values id="oscal-control-part-name"
	target="part[has-oscal-namespace('http://csrc.nist.gov/ns/oscal')]/@name">
	<enum value="overview">An introduction to a control or a group of
	controls.</enum>
	<enum value="statement">A set of implementation requirements or recommendations.</enum>
	<enum value="guidance">Additional information to consider when selecting,
	implementing, assessing, and monitoring a control.</enum>
	<enum value="example">An example of an implemented requirement or control statement.</enum>
	<enum value="assessment" deprecated="1.0.1">**(deprecated)** Use
	'assessment-method' instead.</enum>
	<enum value="assessment-method">The part describes a method-based assessment
	over a set of assessment objects.</enum>
	</allowed-values>

If not, non-NIST usage must always use statement, and really perhaps SP800-53? There are many errors in NIST SP 800-53's catalog around invalid part/@names but that is a different issue for a different day.

I still believe the reported issue to be a bug that needs fixing, and I will make a PR. Feel free to change the label.

EDIT: I pasted the wrong relevant constraint to prop; I updated to include the actually relevant one for part.

[iMichaela]

@xee5ch - If you recall issue #1949 - this constraint was discussed there too. You had a position there as well, but for CSF (and EUCS) to be able to use a proper representation of the information I added "overview" as allowed value for 'core OSCAL' content (namespace 'http://csrc.nist.gov/ns/oscal'). For EUCS and others a different namespace allowed for other values. If I understand you correctly, you argue that other namespaces cannot use any other value but "statement". Can you please provide the version of the oscal-cli tool you are using? Based on the cmd provided, I am assuming you are using the metaschema-framework/oscal-cli, not usnistgov/oscal-cli (oscal-version 1.1.2 support as of now). Nothing that OSCAL v1.1.3 did not change this constraint, v1.1.2 can be used for the purpose of this analysis. I will test again your scenario since the work I mentioned above is about 1 year old. I am for enhancements to facilitate a global use of OSCAL and marked the issue accordingly.

[xee5ch]

You had a position there as well, but for CSF (and EUCS) to be able to use a proper representation of the information I added "overview" as allowed value for 'core OSCAL' content (namespace 'http://csrc.nist.gov/ns/oscal').

I reviewed what you and @aj-stein-nist said. In short, it would seem that you and your staff expanded the enumerated allowed-values for NIST-defined part types to include overview (for all catalogs that have a control broken down into parts, [CSF 1.x, CSF 2.x, SP 800-53; technically CSF does not have controls, but functions, categories, and subcategories and they never use the word control). That is all well and good, but what if I want to specifically say, outside of NIST's use of overview or statement, or I want to identify my specific organization's use of statement being different from NIST, how would I do that? In #1949, it would seem you worked with the team to collapse CSF and SP 800-53 uses of pieces of controls for controls and other non-control items (parts) in the same grouping NIST-wide. What if I or others want to do something that is related but very different from every use of the term example or overview?

The answer to that is @ns, or namespace, per the official documents the team maintains on customizing and extending the data models.

A namespace is managed by a given organization or individual. Using a namespace, different organizations can assign a unique semantic meaning to the use of a property name within their namespace; thus, the different meaning of two properties with the same name can be easily determined by identifying the associated namespaces. This allows different organizations to assign names within their own namespace, without coordinating with other organizations, avoiding naming conflicts. This provides a low-effort means to ensure that naming clashes are avoided.

So let's go back to the really important question in your follow-up comment.

For EUCS and others a different namespace allowed for other values. If I understand you correctly, you argue that other namespaces cannot use any other value but "statement".

Almost. I am saying that the constraint code must be further refined to allow for both your allowed-values and others. This related constraint I reported as a big does not account for parts that are not in the default namespace.

or part[@name='statement']

Given the logic, anyone who uses a non-core-namespace part will always require a prop[@name="status"]/@value to be "withdrawn" regardless of which namespace the part is in. That is the big.

Nothing that OSCAL v1.1.3 did not change this constraint, v1.1.2 can be used for the purpose of this analysis. I will test again your scenario since the work I mentioned above is about 1 year old. I am for enhancements to facilitate a global use of OSCAL and marked the issue accordingly.

I can test this with github.com/usnistgov/oscal-cli and github.com/metaschema-framework/oscal-cli, you will get the same constraint violation report for the former. Therefore, I will propose a more specific constraint target later today if you do not have objections.

$ /tmp/oscal-cli/bin/oscal-cli --version
oscal-cli 1.0.3 built at 2024-02-02 20:49 from branch 5cfe61c695f598f1b4240aa39313bade4397cbeb (5cfe61c) at https://github.com/usnistgov/oscal-cli
liboscal-java v3.0.2 built at 2024-02-01 19:17 from branch bc4c35981305bd3ae7f626d3b8042ea216a02392 (bc4c359) at https://github.com/usnistgov/liboscal-java
oscal v1.1.2 built at 2024-02-01 19:17 from branch 4f02dac6f698efda387cc5f55bc99581eaf494b6 (4f02dac) at https://github.com/usnistgov/OSCAL.git
metaschema-java 0.12.2 built at 2023-09-19T20:12:43+0000 from branch f50c0658054175fd2d72fb8755404e8a998e0fb3 (f50c065) at https://github.com/usnistgov/metaschema-java
metaschema v0.9.0 built at 2023-09-19T20:12:43+0000 from branch a36f579e1e30abb2263895242cdbd2cf4bd29513 (a36f579) at https://github.com/usnistgov/metaschema
$ /tmp/oscal-cli/bin/oscal-cli catalog validate '/home/me/catalog.yml'
Validating '/home/me/catalog.yml' as YAML.
Validation identified the following in file '/home/me/catalog.yml'.
[ERROR] [/catalog/group[1]/control[1]] Expect constraint 'prop[@name='status']/@value=('withdrawn','Withdrawn') or part[@name='statement']' did not match the data at path '/catalog/group[1]/control[1]'

I am for enhancements to facilitate a global use of OSCAL and marked the issue accordingly.

I mean, me too? That is why I file the issues and work on them. If you would prefer I report them and fix them somewhere else, let me know.

[xee5ch]

Also since you asked about versions, I was able to go from oscal-version 1.1.3 to 1.0.0 for the example catalog and reproduce the error with the NIST CLI and other community tooling. Thanks for the questions.

[iMichaela]

@xee5ch - Thank you for running the oscal-cli 1.0.3. If the world is allowed to use any name for the part, how will a GRC tool know what needs to be assessed, versus what is guidance, overview, or example for the human? Opening to any other value under a namespace will require a registry for tools to understand the type of action that needs to be employed

Please note that an 'OSCAL control' is used to represent anything that one would like to assesses or monitor. One can even create a catalog with policy requirements mapped (using the mapping model) to "safeguards" that can be assessed or monitor, and use such approach to continuously report on compliance.

CSF categories and subcategories are used around the world to secure systems and compliance against it is expected. the CRI profile (in OSCAL) is a profit based on CSF v2) and it is used by the financial sector - see OSCAL Foundation event (financial sector panel discussion).

I'll work on this issue (and others) when I'll be back in the office.

[xee5ch]

@xee5ch - Thank you for running the oscal-cli 1.0.3. If the world is allowed to use any name for the part, how will a GRC tool know what needs to be assessed, versus what is guidance, overview, or example for the human? Opening to any other value under a namespace will require a registry for tools to understand the type of action that needs to be employed

To answer the direct question, if you, as a person in NIST representing one some or all catalogs add interpretations of control types and they are not documented (or conflict with one I will document elsewhere in a registry of extension values), how can I delineate that without a namespace?

Are you implying or directly asking me to add recommendation to the core allowed-values enumeration for part, or am I misunderstanding the comment? You want that to be general available for all GRC tools? I am happy to code a PR with that proposal, if you are suggesting that.

Please note that an 'OSCAL control' is used to represent anything that one would like to assesses or monitor. One can even create a catalog with policy requirements mapped (using the mapping model) to "safeguards" that can be assessed or monitor, and use such approach to continuously report on compliance.

Where is this documented? I cannot find anywhere in the models or supporting pages.nist.gov documentation that states it. That's a first for me.

I'll work on this issue (and others) when I'll be back in the office.

So you are saying you will code a change to the constraint? I assume you meant review the issue. I can draft a PR later today unless I hear otherwise.

[xee5ch]

Because I did not get clarity from the most recent comments on whether my original proposal was desired or understood, I opened to pull requests (#2115 and #2116) to choose from to move forward the conversation and hopefully move to select one approach, merge it, and fix the problem.