[EPIC] OSCAL Exchange Protocol

[aj-stein-nist]

User Story:

As an OSCAL tool developer, to best support users in their assessment of an information system, I would like the NIST OSCAL developers to design and recommend a standardized API for the exchange of OSCAL data to and from a security assessment tool. Such a standardized API surface would be incredibly useful for automated portions of assessment and/or continuous monitoring (in the RMF 800-37 and 800-53 sense for the latter). Such functionality would allow security tool developers to standardize on a push or pull interface to input data about one of more information systems to test (i.e. push or pull of an inventory from a SSP, or SAP, existing SAR, or existing POA&M) or to embed its own results from analysis into OSCAL data so OSCAL tool developers can ingest the results into their own system and present it appropriately (i.e. scan result information as part of SAR).

NOTE: NIST OSCAL devs and the community have already discussed a standard API surface with a HTTP REST API to retrieve OSCAL catalogs, profiles, system-security-plans, components with a standard API surface. This design work is different but related: this API design would be a "level above" and be used to communicate intent and push/pull data between services, potentially leveraging those REST APIs for certain data elements as needed.

Goals:

{A clear and concise description of what you want to happen. This should be outcome focused. Include concise description of any alternative solutions or features you've considered. Feel free to include screenshots or examples about the feature request here.}

Dependencies:

{Describe any previous issues or related work that must be completed to start or complete this issue.}

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 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.}

[bradh]

@aj-stein-nist Is this API in a traditional code sense (i.e. what javadoc describes, or what you'd find in a C header, or equivalent for other languages) - like a bindings level, or more like a REST service external interface?

[bradh]

@aj-stein-nist You used the words "communicate intent", which is always fascinating. Can you expand on this? In particular, you you provide examples of what it could look like, and just as importantly, what it is not intended to mean?

[aj-stein-nist]

@aj-stein-nist Is this API in a traditional code sense (i.e. what javadoc describes, or what you'd find in a C header, or equivalent for other languages) - like a bindings level, or more like a REST service external interface?

We received some initial feedback from some users with conceptual examples that were/are more like a REST API interface a system can expose to exchange OSCAL data.

That said, I think we will definitely moving forward solicit further community feedback, so it would be interesting to hear from you, @bradh: do you have a need for a "traditional [code] programming" API? A REST external service interface? Both? If one, we would love to hear why you need or want one over the other.

[aj-stein-nist]

@aj-stein-nist You used the words "communicate intent", which is always fascinating. Can you expand on this? In particular, you you provide examples of what it could look like, and just as importantly, what it is not intended to mean?

By "communicate intent" in this context, I meant this would be an API that embeds the serialized OSCAL data models, but it is more than that and simply not an instance of a SSP, component, SAP, or SAR. There is interest in defining API endpoints to see "give me updated information about parts of the system [as part of current state inventory and check against SSP]" or "run validation procedures with assessment plan XYZ [sent via API in a prior call or maybe within this same API call] and return results for XYZ as a partial or complete assessment result." This is more than just instances of model data, you can see there are actions triggered or workflows implied with the data.

This is still very early on in the design work around this, so I do not have explicit or tangible examples yet. Does that help clarify the reasoning behind this, @bradh?

[bradh]

By "communicate intent" in this context, I meant this would be an API that embeds the serialized OSCAL data models, but it is more than that and simply not an instance of a SSP, component, SAP, or SAR. There is interest in defining API endpoints to see "give me updated information about parts of the system [as part of current state inventory and check against SSP]" or "run validation procedures with assessment plan XYZ [sent via API in a prior call or maybe within this same API call] and return results for XYZ as a partial or complete assessment result." This is more than just instances of model data, you can see there are actions triggered or workflows implied with the data.

So its more about the interface being "OSCAL semantics aware" ? A naive API would give me back the XML document, but the kind of thing you are looking at (potentially) could do profile resolution and check compliance results?

[bradh]

That said, I think we will definitely moving forward solicit further community feedback, so it would be interesting to hear from you, @bradh: do you have a need for a "traditional [code] programming" API? A REST external service interface? Both? If one, we would love to hear why you need or want one over the other.

I think there could be a case for either (and both), more interested in making sure I had the vision. I don't yet have a need for a standardised code API given the functionality offered by the tools being developed (e.g. the java bindings, or compliance trestle).

I think there might be some interesting capabilities if a component (e.g. a deployed microservice) can provide part of the component description on an embedded endpoint. Not yet sure how all that could be brought together though.

[aj-stein-nist]

By "communicate intent" in this context, I meant this would be an API that embeds the serialized OSCAL data models, but it is more than that and simply not an instance of a SSP, component, SAP, or SAR. There is interest in defining API endpoints to see "give me updated information about parts of the system [as part of current state inventory and check against SSP]" or "run validation procedures with assessment plan XYZ [sent via API in a prior call or maybe within this same API call] and return results for XYZ as a partial or complete assessment result." This is more than just instances of model data, you can see there are actions triggered or workflows implied with the data.

So its more about the interface being "OSCAL semantics aware" ? A naive API would give me back the XML document, but the kind of thing you are looking at (potentially) could do profile resolution and check compliance results?

At this point, my inclination is to answer yes. The main use case we had discussed was "hey you, system, can you check compliance results and report back?"

This has absolutely zero connection to this epic as it stands, but the embedded endpoint is very close to how it was described to me, and immediately reminded me of the goss serve functionality to emit a HTTP endpoint. At a very high-level this is how I interpret the intent of this epic of work, but only in the way this tool has an embedded health endpoint for security testing, no endorsement on our part. :-)

[aj-stein-nist]

Note: it seems systems that would expose such an API, per NISTIR 8011-1 4.2.1 are one or more collectors that make up a collection system.

[guyzyl]

@aj-stein-nist I think we can learn from the "cloud-native" approach, and look at how CloudEvents solves a similar issue.
I personally don't think there's a need to standardize the API itself, only the schema of how the data is transferred over API.
Since OSCAL already defines the content itself, all that is needed is to add the "API metadata" layer that will go along with it.

Also, this issue is related to/duplicates #324 .

[rgauss]

@aj-stein-nist I think we can learn from the "cloud-native" approach, and look at how CloudEvents solves a similar issue. I personally don't think there's a need to standardize the API itself, only the schema of how the data is transferred over API. Since OSCAL already defines the content itself, all that is needed is to add the "API metadata" layer that will go along with it.

Also, this issue is related to/duplicates #324 .

@guyzyl, OSCAL does a great job at defining the schema at the 'document' level, i.e. root OSCAL objects, but these tend to be very large (non-minified rev4 800-53 catalog is 5.36 MB!) and an approach of clients simply updating an entire OSCAL document will lead to concurrency and performance issues and wouldn't easily support the concept of relating existing objects across documents.

We've started a similar effort to start the conversation on what a REST API might look like.

[sunstonesecure-robert]

Here's my attempt at distilling a more concise set of use cases from above: * assessment, examples include: - query and CRUD inventory - query and CRUD control implementations - query and CRUD SAP elements - query and CRUD SAR elements, e.g. check compliance results * management of SSP, examples include: - query and CRUD of SSP content (too much to repeat here) but specifically: - query and CRUD control descriptions/requirements - query and CRUD parameters and parameter values - translation across OSCAL formats (eg XML <-> JSON <-> yml) and to Word+Excel for human consumption - profile resolution (not sure what this entails) * continuous monitoring, examples include: - query and CRUD of POA&M content - query and CRUD inventory Where Create and Read generally enable wholesale import and export (leaving conflicts and merging aside). From a practical perspective, for cloud native operational use cases, the main pain day-to-day is SSP maintenance to update components and SAP+SAR content for ephemeral systems (e.g. Kubernetes, microservices) where the inventory changes every few minutes. For a completely new workload, mapping the control requirements to a new microservice or data flow might happen at most every couple of months for us but I could imagine a large multi-tenant system where that might happen daily. For ConMon, ingesting assessment results as OSCAL would be nice - we are working in the Kubernetes Policy WG to map controls -> assessment requirements -> assessment results. We aligned our assessment report outputs with OSCAL to make it easy to generate actual OSCAL content if/when needed (but leave that as an exercise to the developer.) As an aside, I expect that the Log4J kerfuffle is going to occur more frequently, with agencies and the PMO requiring rapid assessments of the inventory against new threats - so having an automated SAP+SAR continuous assessment pipeline capability via some form of API based tooling that can be used to generate an updated POA&M will become increasingly handy, instead of having to submit bespoke Excel files each time a new threat emerges. Hope this helps the conversation!

…

On Sun, Jan 2, 2022 at 11:37 AM Ray Gauss II ***@***.***> wrote: @aj-stein-nist <https://github.com/aj-stein-nist> I think we can learn from the "cloud-native" approach, and look at how CloudEvents <https://cloudevents.io/> solves a similar issue. I personally don't think there's a need to standardize the API itself, only the schema of how the data is transferred over API. Since OSCAL already defines the content itself, all that is needed is to add the "API metadata" layer that will go along with it. Also, this issue is related to/duplicates #324 <#324> . @guyzyl <https://github.com/guyzyl>, OSCAL does a great job at defining the schema at the 'document' level, i.e. root OSCAL objects, but these tend to be very large (non-minified rev4 800-53 catalog <https://github.com/usnistgov/oscal-content/blob/master/nist.gov/SP800-53/rev4/json/NIST_SP-800-53_rev4_catalog.json> is 5.36 MB!) and an approach of clients simply updating an entire OSCAL document will lead to concurrency and performance issues and wouldn't easily support the concept of relating existing objects across documents. We've started a similar effort to start the conversation on what a REST API might look like <https://github.com/EasyDynamics/oscal-rest>. — Reply to this email directly, view it on GitHub <#1060 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AQWTGFEGGPBO6CQLN3BH2ODUUCSQPANCNFSM5I3MFFJA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[aj-stein-nist]

@aj-stein-nist I think we can learn from the "cloud-native" approach, and look at how CloudEvents solves a similar issue. I personally don't think there's a need to standardize the API itself, only the schema of how the data is transferred over API. Since OSCAL already defines the content itself, all that is needed is to add the "API metadata" layer that will go along with it.

Thanks I will take a look, @guyzyl.

Also, this issue is related to/duplicates #324 .

I will follow up on this separately.

[aj-stein-nist]

Also, this issue is related to/duplicates #324 .

@guyzyl, I am not sure this is a 1:1 duplicate, but I do think it relates to #324. This is the point of my note here in the current form of the issue as created.

NOTE: NIST OSCAL devs and the community have already discussed a standard API surface with a HTTP REST API to retrieve OSCAL catalogs, profiles, system-security-plans, components with a standard API surface. This design work is different but related: this API design would be a "level above" and be used to communicate intent and push/pull data between services, potentially leveraging those REST APIs for certain data elements as needed.

Several members of the community (like @rgauss), as pointed out here prior, have started work on an API for the OSCAL object models. This story, as I originally drafted it, is to build an API specification for higher-level workflow tasks that represent common activities that correlate data across one or more OSCAL objects. @sunstonesecure-robert alluded to those, and I think he did a good job conveying some of the distilled use cases (I hadn't got that far yet).

Here's my attempt at distilling a more concise set of use cases from above:

• assessment, examples include:

• query and CRUD inventory
• query and CRUD SAR elements, e.g. check compliance results

Does that help clarify? This work is not in sprint yet and we are not actively working on it (yet), but I am glad to interest pick up!

[IvanDrag0]

For reference, EasyDynamics has developed an OpenAPI representation of OSCAL:

https://github.com/EasyDynamics/oscal-rest.git

The STIX related TAXII server might also present a good model/representation of a communication protocol:

https://oasis-open.github.io/cti-documentation/taxii/intro

[aj-stein-nist]

For reference, EasyDynamics has developed an OpenAPI representation of OSCAL:

https://github.com/EasyDynamics/oscal-rest.git

They have presented their work and it is on my radar. How this is slightly different I allude to in #1060 (comment). But, yes, it will not be ignored when this work is started.

The STIX related TAXII server might also present a good model/representation of a communication protocol:

https://oasis-open.github.io/cti-documentation/taxii/intro

I have not had a chance to dig into STIX and TAXII as their I different domain in security, I had not considered them actively. Now that I think about it, it is worth considering. So I add it to the list. :-)

[brian-comply0]

We've recently refactored our open-source OSCAL REST API spec to focus on org-to-org exchange of OSCAL content.

The new spec includes:

• XML and JSON handling
• Attachments
• Snapshots
• Resolved Profiles
• Resolved Profile Snapshots

It is also designed to be OSCAL "import" friendly. Meaning any OSCAL file's import statement can point to any other OSCAL file via the REST API GET syntax.

Please take a look:
https://editor.swagger.io/?url=https://raw.githubusercontent.com/EasyDynamics/oscal-rest/RefactorRestAPI/basicRestapi.yaml

We call this the "Basic" spec because we intend to eventually have a comprehensive version that builds on this to handle commonly used data query needs.

[aj-stein-nist]

This work should go back to user research and discovery, so this will be moved back to DEFINE Research Needed. After that, if it is returned to development as-is, we should consider refinement being needed as this epic, as previously used it, is too large re upcoming #1688 reorganization and needs to be broken down into manageable pieces.