search

usnistgov / OSCAL

Open Security Controls Assessment Language (OSCAL)
https://pages.nist.gov/OSCAL/
Other
670 stars 182 forks source link

[EPIC] OSCAL Exchange Protocol #1060

Open aj-stein-nist opened 2 years ago

aj-stein-nist commented 2 years ago

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

{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 commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

@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 commented 2 years ago

@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 commented 2 years ago

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

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 https://github.com/usnistgov/OSCAL/issues/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 https://github.com/usnistgov/OSCAL/issues/1060#issuecomment-1003764445, 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 commented 2 years ago

@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 commented 2 years ago

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 usnistgov/OSCAL#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 commented 2 years ago

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 commented 2 years ago

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 https://github.com/usnistgov/OSCAL/issues/1060#issuecomment-1004151325. 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 commented 1 year ago

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:

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 commented 1 year ago

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.