Common OSCAL information exchange API

[anweiss]

User Story:

As an OSCAL producer and consumer, I can send/receive OSCAL formatted information over a standard API that can be implemented by systems, system components, and/or tools. This API would also allow for discoverability of OSCAL data.

Goals:

The lack of any sort of standardized API for communicating OSCAL information between systems and humans makes it difficult to aggregate and review security control information for a given system or systems. It also becomes difficult to properly assess the risk of a system if crucial information is available, but not easily discoverable.

Existing best practices and protocols should be leveraged. Any approaches built on REST principles should be taken into consideration. Anything based on pure REST API constructs, to something more domain-specific like ROLIE, would be acceptable.

Dependencies:

None.

Acceptance Criteria

A common API for discovering and exchanging OSCAL information is developed, including its routes and resources. The implementation of the API is not in scope of this issue and would be left up to system owners and tool vendors.

[redhatrises]

@anweiss curious if you have further thoughts on this because the OSCAL format in JSON could be used for the API itself. For example:

GET /catalog
GET /catalog/title
GET /catalog/references
etc...

[anweiss]

@redhatrises spot on! that's exactly what I've had in mind. The API could very much reuse the existing OSCAL components and elements as part of the construction of the API routes and resources themselves.

[anweiss]

I've been prototyping this out using REST and OpenAPI v3. To @redhatrises's point, this is merely a natural path-based walk of the schema, and as such, one can easily automatically generate the OpenAPI definitions from the metaschemas without any data loss. In fact, the OpenAPI spec is just an extension, of sorts, to JSON schema.

On a similar note, while the original issue description mentions that we could potentially take a feed-based approach (e.g. Atom, ROLIE, etc), even on top of REST, IMO we should avoid it given that XML is the only formal representation of these feed-based standards. We ideally want flexibility in terms of the inputs/outputs provided by such an API (XML and JSON), something that which the OpenAPI spec and traditional APIs provide.

Obviously, would like to hear feedback from others.

[anweiss]

@wendellpiez per ^, take a look at https://swagger.io/docs/specification/data-models/keywords/ ... note that we can re-use a lot of the existing JSON schema production from the metaschema if we define this common API using OpenAPI.

[anweiss]

I've been prototyping this out with OpenAPI v3. Posted Gist at https://gist.github.com/anweiss/c9221445d4d519b63df9323f097fac28. While I've included the models from the existing JSON schema directly into the OpenAPI definitions for brevity, one could also simply include direct $refs to the OSCAL JSON schemas themselves.

Below is a screenshot of what the endpoints might look like for an API that exposes catalog data:

Ideally, we should define a set of standardized routes that provide meaningful but not overpowering output to clients. For example, routes that return single values e.g. /catalog/title may not add much value vs /catalog/myCatalogId?condensed=true which would provide the option to return a condensed variant of the catalog that which includes title amongst other properties.

Something to note is that while the schemas support nested recursion, the API paths themselves should be limited to one or two path parameters since it's quite cumbersome and unwieldy to have an API that supports path recursion; and frankly not usable.

[anweiss]

@bsilberberg would love your take on this as well

[anweiss]

Another interesting project that recently hit 1.0 and that could be explored for this issue is https://ballerina.io. New language designed to make the development of distributed services much easier. Per https://blog.ballerina.io/posts/annoucing-1.0.0/, it looks like the lead designer of the language is James Clark, one of the original folks behind XML, XPath, XSLT and RelaxNG. So naturally, Ballerina has strong support for XML and XSLT in its standard lib.

[iMichaela]

Do we need only an API (an interface to a logical repository of OSCAL objects) or would the community benefit more from an application protocol for exchanging OSCAL-formated information over HTTPS, especially in support of contiuous monitoring and information aggregtion and automation of assessment results?

[trevor-vaughan]

My 'microservices' thought is an API but my 'big enterprise' thought is to target an agnostic data transport (HTTPS doesn't always work well over WANs).

Given the scope, and size, of the data sets, I would probably opt for an API that can be transport agnostic to support large environments with high latency and limited bandwidth. Particularly being able to chunk and validate data would be important.

I guess, put another way: solve the edge problem and the cloud problem is easy. Solve the cloud problem and you've left a lot of your systems out in the cold.

[anweiss]

@trevor-vaughan @iMichaela great points. I'm also in the "transport-agnostic" camp, due to reasons outlined by @trevor-vaughan. With a common API, it really doesn't matter what transport is used. For constrained network scenarios, any number of binary serialization mechanisms could be used. As an aside, support for CDDL via https://github.com/usnistgov/OSCAL/issues/460 would open the door to validating CBOR-encoded OSCAL for these edge scenarios; especially since CBOR is merely a superset of JSON, a format we already support.

[anweiss]

Coming from the container/cloud-native world, here's another possible approach -> https://www.opencontainers.org/blog/2019/09/10/new-oci-artifacts-project. The new OCI Artifacts project is designed to allow one to exchange/store deployment artifacts (e.g. Kubernetes manifests, Helm Charts, etc) alongside your container images via the OCI distribution specification. Could be interesting to extend it to support OSCAL.