Skip to content

OSCAL REST OpenAPI Specification

Jump to bottom
Brian Ruf edited this page Mar 26, 2024 · 15 revisions
STOP - STOP - STOP - STOP - STOP - STOP - STOP - STOP - STOP - STOP
This article has been frozen and is now being maintained in the OSCAL.io Knowledge Base
https://docs.oscal.io/docs/oscal-rest-openapi

DRAFT ‐ For Public Review and Feedback

The proposed OSCAL REST OpenAPI specification is defined using the OpenAPI 3.1 standard. It addresses OSCAL XML, OSCAL JSON and OSCAL YAML content for all seven OSCAL models and provides for identity assertion.

Each OSCAL model has a primary set of REST API endpoints for the OSCAL content itself, as well as endpoints for snapshots and attachments. OSCAL profiles have an additional set of endpoints related to resolved profiles and snapshots of resolved profiles.

The proposed OSCAL REST OpenAPI specification is expressed using the OpenAPI 3.1 standard here:
https://raw.githubusercontent.com/EasyDynamics/oscal-rest/RefactorRestAPI/basicRestapi.yaml

The spec may be more easily viewed using Swagger:
https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/EasyDynamics/oscal-rest/RefactorRestAPI/basicRestapi.yaml

Please Provide Feedback

This is a DRAFT specification. Feedback is welcome and encouraged!

The best way to express feedback or request changes about this DRAFT specification is by opening a new GitHub issue or by commenting on an existing issue if one already exists on the topic.

Conventions and Organization

In the content below, all endpoint syntax is provided as:

METHOD /{model-name}
METHOD /{model-name}/{identifier}
METHOD /{model-name}/{identifier}/snapshot
METHOD /{model-name}/{identifier}/snapshot/{identifier}
METHOD /{model-name}/{identifier}/attachment
METHOD /{model-name}/{identifier}/attachment/{identifier}

The {model-name} is always one of the seven root-level OSCAL model names exactly as they are defined in the OSCAL syntax. Simply replace {model-name} with any one of the following:

  • catalog
  • profile
  • component-definition
  • system-security-plan
  • assessment plan
  • assessment-results
  • plan-of-action-and-milestones

Further, the REST API specification requires implementation-assigned unique identifiers, indicated in the endpoint syntax with {identifier}. Implementers should consider the use of RFC-4122 compliant v4 or v5 UUIDs to identify OSCAL files and snapshots.

The remaining sections of this document are organized as follows:

  • Primary Endpoints – endpoints that interact with the working copy of the OSCAL files themselves.
  • Snapshot Endpoints – endpoints that allow the creation and management of snapshots for OSCAL content, providing for version history.
  • Attachment Endpoints – endpoints that allow the management of attachments to OSCAL content, and handle any file type.
  • Profile Resolution Endpoints – endpoints that perform live profile resolution as well as the management of snapshot-in-time profile resolution.

Primary Endpoints

The following methods apply to every defined OSCAL model.

Method Description
GET /{model-name} Lists all items of that model type for which the user has access, including each item's ID and Title.
POST /{model-name} Adds a new item of that model type.
GET /{model-name}/{identifier} Gets a specific item of that model type by its identifier.
PUT /{model-name}/{identifier} Replaces a specific item of that model type by its identifier.
DELETE /{model-name}/{identifier} Removes a specific item of that model type by its identifier.

NOTES:

  • The first GET method returns a list of accessible content with the implementation-assigned identifiers.
  • The implementation assigns and returns an identifier following a POST method.
  • RFC-4122 compliant v4 or v5 UUIDs are highly encouraged, but not required.
    • NOTE: RFC-4122 requires only lower-case characters for hex values a through f in UUID values.
  • OSCAL import and href values should reference other files within the repository using the OSCAL REST OpenAPI GET endpoints.
    • Example: A profile's import catalog statement would reference a catalog within the repository using:
      "href" : "https://api.example.com/catalog/a81f0611-3404-40d9-9d97-fcb067989af8"
    • If the catalog is public/read-only or the user has access, this would resolve by any OSCAL tool that can reach the server.

Snapshot Endpoints

The following methods are available for making and managing point-in-time snapshots of an OSCAL file.

Method Description
GET /{model-name}/{identifier}/snapshot Lists all snapshots of the identified item, including snapshot ID and date created.
POST /{model-name}/{identifier}/snapshot Creates a new snapshot of the identified item.
GET /{model-name}/{identifier}/snapshot/{identifier} Gets a specific snapshot.
PUT /{model-name}/{identifier}/snapshot/{identifier} Adds to or replaces details about the snapshot
DELETE /{model-name}/{identifier}/snapshot/{identifier} Removes the identified snapshot.

Attachment Endpoints

The following methods are available for managing attachments associated with an OSCAL file.

Method Description
GET /{model-name}/{identifier}/attachment Lists all the attachments of the identified OSCAL file stored within the repository.
POST /{model-name}/{identifier}/attachment Adds a new attachment to the repository, scoped to the identified OSCAL file and assigns an attachment ID to it.
GET /{model-name}/{identifier}/attachment/{UUID} Gets a specific attachment.
PUT /{model-name}/{identifier}/attachment/{UUID} Replaces a specific attachment with the file provided.
PUT /{model-name}/{identifier}/attachment/{UUID}/resource Replaces the back-matter resource details about the attachment.
DELETE /{model-name}/{identifier}/attachment/{UUID} Removes a specific attachment.

EXAMPLE:

An SSP's authorization boundary diagram exists as a PDF attachment. (boundary.pdf)

  • The calling client uploads the boundary.pdf diagram into the repository using:
    POST /system-security-plan/{ssp-uuid-value}/attachment
  • The implementation assigns an attachment identifier and returns that identifier to the calling client. ( attachment-uuid-value )
  • The calling client then sets or updates the reference to the attachment in the SSP using PUT /{model-name}/{identifier}/attachment/{UUID}/resource

Profile Resolution Endpoints

For OSCAL profiles, there are also resolved profile methods.

One method resolves a profile on demand and returns the resulting resolved profile catalog. The remaining methods allow for capturing and managing a snapshot in time of a resolved profile catalog. Profile snapshots are designed to capture the resolution at a point in time, such as to demonstrate the control definitions in effect at the time of an assessment.

Today, the result of profile resolution is very static. As OSCAL reaches its full potential there will be differences in resolution results depending on when a profile is resolved. This is due to more complex layering of profiles and more dynamic updates to overlay profiles and referenced catalogs.

The following profile resolution methods are available.

Method Description
GET /profile/{identifier}/resolved-catalog Returns a resolved profile catalog based on current content.
POST /profile/{identifier}/resolved-snapshot Caches a resolved profile catalog at a point in time.
GET /profile/{identifier}/resolved-snapshot Retrieves the list of cached resolved profile catalogs, including their ID and resolution timestamp.
GET /profile/{identifier}/resolved-snapshot{identifier} Retrieves a specific resolved profile catalog snapshot.
DELETE /profile/{identifier}/resolved-snapshot{identifier} Removes a specific resolved profile catalog snapshot.

NOTES:

  • Usage Example: At the time of an assessment, snapshots can be taken of both the SSP and the resolved profile catalog. The SSP snapshot can then be patched to import the resolved profile snapshot as a means of preserving the state of control definitions at the time of assessment.

FORMAT SPECIFICATION

Client Requests OSCAL Files From Server

The OSCAL specification allows OSCAL content to exist as XML, JSON, or YAML. While the OSCAL REST OpenAPI specification uses JSON for most interactions, the following method/endpoint combinations must honor the Accept HTTP header for JSON, XML, and YAML:

  • GET /{model-name}/{Identifier}
  • GET /{model-name}/{Identifier}/snapshot/{Identifier}
  • GET /profile/{Identifier}/resolved-catalog
  • GET /profile/{Identifier}/resolved-snapshot/{Identifier}

When Accept is set to:

  • application/json or application/oscal+json return the OSCAL content in JSON format;
  • application/xml (preferred by RFC 7303) or text/xml (deprecated by RFC 7303) or application/oscal+xml return the OSCAL content in XML format; or
  • application/yaml or text/yaml return the OSCAL content in YAML format.

When returning the OSCAL content, the implementation must set the Content-type header to:

  • application/json when returning the OSCAL content in JSON format;
  • application/xml when returning the OSCAL content in XML format; or
  • application/yaml when return the OSCAL content in YAML format.

Client Sends OSCAL Files To Server

Similarly, XML, JSON or YAML OSCAL files may be used with the following method/endpoint combinations:

  • POST /{model-name}
  • PUT /{model-name}/{Identifier}

In these cases, the client must include the Content-type HTML header and set it to one of the following:

  • application/json when sending an OSCAL file in JSON format;
  • application/xml when sending an OSCAL file in XML format; or
  • application/yaml when sending an OSCAL file in YAML format.

The implementation must accept all three OSCAL formats. OSCAL content sent to the server in any one of the three formats must be made available in all three formats for the relevant GET method/endpoint combinations.

SUPPORTING INFORMATION

Specification Versioning

The OSCAL REST OPEN API Specification uses Semantic Versioning 2.0, which is summarized on the web site as follows:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Identifying Specification Version in Syntax

Methods for identifying the specification version number as part of the REST API syntax are being considered as part of this issue. Please review the issue and provide feedback on this important topic area.

Consistent with REST API best practices, candidate options include:

  • URI Versioning: Including the version as part of the endpoint definition, such as GET {base-url}/1.0.0/catalog/{identifier}
  • Header Versioning: Including the version in the HTTP headers.
  • Body Versioning: Included in the request itself.

BASE Uniform Resource Locator (URL)

Consistent with REST API principles, the endpoints defined in the specification appended to the end of a base URL, which is defined by the implementation. A base URL may include just a host name, or a combination of host name and path.

The following are examples of valid base URLs:

  • https://api.example.gov (Example: The complete syntax to fetch a list of catalogs would be GET https://api.example.gov/catalog)
  • https://www.example.gov/api (Example: The complete syntax to fetch a list of catalogs would be GET https://www.example.gov/api/catalog)

Note that if URI Versioning is selected, the examples above would instead be GET https://api.example.gov/1.0.0/catalog and GET https://www.example.gov/api/1.0.0/catalog respectively.

SECURITY CONSIDERATIONS

TLS 1.3 or Higher

Any server implementation of the API specification should enforce TLS 1.3 or higher for communication with API clients to ensure confidentiality of sensitive security information, as well as to ensure the integrity of all information exchanged. As of January 1, 2024, NIST SP 800-52r2 requires TLS 1.3 for U.S. Federal government systems.

TLS should be implemented using FIPS 140-2 or 140-3 validated cryptographic modules. This is required for U.S. Federal government systems.

Access Control

The implementation must enforce access control based on an asserted identity or access token as described in the OpenAPI Guide's Authentication and Authorization section, and only responds with content to which the asserted identity has access.

For example, if a user only has access to two out of six SSPs within the implementation, the GET /system-security-plan endpoint will only return the two SSP to which the user is granted access. The other SSPs are not included in the list. If the user attempts to directly GET an SSP for which they do not have access, the implementation would return either 401 Unauthorized or 404 Not Found , but would not return the unauthorized content.

NOTE: The decision as to whether this use case would return 401 or 404 is implementation specific. While 401 is the correct response, a common security practice is to return a 404 error so that a malicious user cannot know the difference between content that doesn't exist and content for which the user is not authorized.

Clone this wiki locally