How should multiple instances of a control/control statement be represented in the component-definition?

[javery45]

All examples I've seen so far show security controls represented in the OSCAL component-definition with a single reference under implemented-requirements to represent a single description or idea of how that control is satisfied by whatever resource the component-definition itself represents. But what if there are multiple implementations of settings, source code, or policy that you want to link to a control?

My team is building a component definition to represent an application we build form source code, and want to directly reference parts of the codebase for some applicable security controls under the component-definition/components/control-implementations/implemented-requirements/ section of the component-definition.

We're working on some custom tools to scan a project's source code for code comments that contain "control reference" annotations that would tag those sections for a given security control, and then be automatically built into a component-definition model document that our CI/CD pipeline automatically generates when the application gets built. Those "control references" would look something like:

@OSCAL:au-8_smt.a:CCI-001890:Description of how this code applies...

There are instances where multiple different parts of the code could apply to a singular security control or control statement -- but with different implementation details for a description, and I'm not sure exactly how that should be represented in the component-definition model.

Option 1 - multiple statements but with unique UUIDs

My first idea was to list multiples of the same statement (au-8_smt.a) under its parent control (au-8) implemented-requirement object, but see that the Component Definition JSON Format Reference mentions a Constraints: IS UNIQUE for statement. Does this mean that there can be only ONE of each statement in general, or could I have multiples listed with each having its own unique UUID like so?:

"implemented-requirements": [
    {
        "uuid": "bcc874bc-1d0e-4d59-b1de-cf734b431730",
        "control-id": "au-8",
        "description": "the application uses time stamps",
        "statements": [
            {
                "statement-id": "au-8_smt.a",
                "uuid": "559d97e1-69d9-4646-a799-53bb0b4946cd",
                "description": "the application uses the internal system clock to generate time stamps"
                "links": [
                    {
                        "href": "src/examples/file1.txt#L7",
                        "rel": "reference"
                    },
                ]
            },
            {
                "statement-id": "au-8_smt.a",
                "uuid": "bcb7eefe-d88a-4780-a243-e02437801291",
                "description": "another example of source code where internal system clock is used for time stamps"
                "links": [
                    {
                        "href": "src/examples/file2.txt#L20",
                        "rel": "reference"
                    },
                ]
            }
        ]
    }
]

This shows multiples of the same au-8_smt.a statement, but with each having their own uuid, unique description describing different implementation details, and different URI href to source code files and lines. This level of detail and ability to directly map individual parts of the code to a control are very desirable.

Option 2 - single statement but with multiple href links

The second idea was to represent the multiples by having a single statement object, but with multiple links/href URIs to each source code location:

"implemented-requirements": [
    {
        "uuid": "bcc874bc-1d0e-4d59-b1de-cf734b431730",
        "control-id": "au-8",
        "description": "the application uses time stamps",
        "statements": [
            {
                "statement-id": "au-8_smt.a",
                "uuid": "559d97e1-69d9-4646-a799-53bb0b4946cd",
                "description": "the application uses the internal system clock to generate time stamps"
                "links": [
                    {
                        "href": "src/examples/file1.txt#L7",
                        "rel": "reference"
                    },
                    {
                        "href": "src/examples/file2.txt#L20",
                        "rel": "reference"
                    },
                ]
            },
        ]
    }
]

The downside with this option is losing the individual description fields that each of the references previously had.

Option 2 seems like the cleanest solution, but the loss of detail from not having unique descriptions for each referenced implementation seems like it might introduce ambiguity later on, especially when trying to diligently track code and code changes to exact controls.

Are either of these two options better than the other, or is there another solution for representing this use case in OSCAL's component-definition that I might be missing?

[aj-stein-nist]

This is a super great question, but a lot to unpack! I will have to think about some of these questions.

[Agh42]

I was also thinking about this. Wouldn't "option 3" be to model separate components with their own control implementation? This would be very granular, but it would look like this:

 "capabilities": [
      {
        "uuid": "c1050857-93d9-4654-b363-296c5523dd01",
        "name": "Software Application",
        "description": "a description",
        "incorporates-components": [
          {
            "component-uuid": "8eaa855e-d749-441f-894f-9f96ac91487c",
            "description": "file1.txt"
          },
          {
            "component-uuid": "28bea7a9-386a-45ec-bc4b-aabce3373c38",
            "description": "file2.txt"
          }
        ]
      }
    ],
    "components": [
      { "uuid": "8eaa855e-d749-441f-894f-9f96ac91487c",
        "type": "software",
        "title": "file1.txt",
        "description": "file1.txt",
        "control-implementations": [
          {
            "uuid": "cfcdd674-8595-4f98-a9d1-3ac70825c49f",
            "source": "../../../nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json",
            "description": "partial implementation of the SP 800-53 rev5 catalog",
            "implemented-requirements": [
              {
                "uuid": "d1016df0-9b5c-4839-86cd-f9c1d113077b",
                "description": "the application uses the internal system clock to generate time stamps",
                "control-id": "au-8",
                "statements": [
                  {
                    "statement-id": "au-8_smt.a",
                    "uuid": "559d97e1-69d9-4646-a799-53bb0b4946cd",
                    "description": "the application uses the internal system clock to generate time stamps",
                    "links": [
                      {
                        "href": "src/examples/file1.txt#L7",
                        "rel": "reference"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      },
      { "uuid": "28bea7a9-386a-45ec-bc4b-aabce3373c38",
        "type": "software",
        "title": "file2.txt",
        "description": "file2.txt",
        "control-implementations": [
          {
            "uuid": "eb6ae2d9-ced8-4b84-b303-64c54980a31b",
            "source": "../../../nist.gov/SP800-53/rev5/json/NIST_SP-800-53_rev5_catalog.json",
            "description": "partial implementation of the SP 800-53 rev5 catalog",
            "implemented-requirements": [
              {
                "uuid": "e9eb80ed-2717-4853-9943-da670bf63756",
                "description": "the application uses the internal system clock to generate time stamps",
                "control-id": "au-8",
                "statements": [
                  {
                    "statement-id": "au-8_smt.a",
                    "uuid": "8daef7cb-53ac-425f-b0f4-c80f2d82f01c",
                    "description": "the application uses the internal system clock to generate time stamps",
                    "links": [
                      {
                        "href": "src/examples/file2.txt#L20",
                        "rel": "reference"
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]

[sunstonesecure-robert]

I note that the docs say implemented-requirements "suggest possible control implementation details...are only a suggestion of how to implement".

I think it's important to note that the component-definition in the Component Definition Model (CDM) component (the "suggestion") is different from the system-implementation -> component (the "how") that is in the SSP Model.

I think of it in OOP terms that the component-definition in the CDM is really an (abstract) class and a defined-component (ie a component in the SSP implementation) is an object instance (ie some real thing in the system running the compiled source code implementing some security feature like robust time stamps).

Put another way - every SSP component "instance" must necessarily implement the CDM's component-definition's requirements (by virtue of being an object instantiated of that class).

Any CDM component definition should specify the "possible control implementation details" (ie implemented-requirements) but doesn't bind those to any particular SSP implementation "instance".

In the example above, app process A running file1's code and file2's code in VM1 are both using different code in memory to call the same host clock to generate time stamps. app process B in VM2 is using a different inventory code in different memory calling a different system clock to generating time stamps. The component-definition requirement is the same in all these cases, independent of the source files, regardless of where it runs, and even independent of the same SSP being used in 2 different agencies. the SSP definition is different, and the inventory item's actual testable code is different in all these cases and as a 3PAO conducting testing I might test all these (or sample) - but I would review the component-definition once (and link all these together in my fancy OSCAL-enabled SAR generation tool!)

thus I don't think there is a need to add any new model structure to allow for your example:

component-definition/components[file1]/control-implementations/implemented-requirements/
component-definition/components[file2]/control-implementations/implemented-requirements/

would be au-8_smt.a in all source files in all apps. the SSP implemented requirements:

system-security-plan/control-implementation/implemented-requirements

would point to au-8_smt.a as well.

system-security-plan/control-implementation/implemented-requirements/statements/by-components

would reference:
component-definition/components[file1], and
component-definition/components[file2]

in summary - what @Agh42 said just more prolix :)

[iMichaela]

@sunstonesecure-robert and @Agh42 -- The main difference between a component definition (CDef) and SSP is who governs the data and the authoritative level.
NIST designed the CDef to capture information from the vendor describing the controls implemented and the consumer's responsibility when applicable. Those would be suggestions.
Similarly, CDef model can be used to generate playbooks describing how the organization recommends/requires the component to be configured to satisfy applicable controls.
For example, IF a component is implementing the requirement for a low impact level system, the control-implementation/source could point to the low impact baseline and the implemented-requirement/statements/description could read "the application is using the internal clock".
In the same CDef instance (file), in the control-implementation array, the CDef author could provide a control satisfaction for the component when it is part of a high-impact system. In this case, control-implementation/source could point to the high-impact baseline, and the implemented-requirement/statements/description could read "the application must be executed with the flag p=AT for the application to query the atomic clock every 30 min".
When the application becomes part of a system categorized high-impact, the system owner will decide if the second implementation is more appropriate because it needs a very accurate time, and because the organization requires it OR, because it is air gapped all the application can do into use the local time but the system owner insures all components using the same time through a separate process. The system owner (in the SSP) has (as shown) the chance to tailor the suggested control satisfaction to his/her needs but adds compensatory actions to meet the sync requirements.
To support a DevSecOps approach, a pre-assessment/provisional-assessment of the component per the CDef is possible and recommended, but once it gets deployed Ito the air gapped system, the final decision is made and an assessment method corresponding to the final deployment is necessary.