Scenarios

Scenario 1

Using Content Identifiers

Scenario 1A: Initial Delivery of a Component Definition
Scenario 1B: Acquiring a Component Definition Using a Content Identifier
Scenario 1C: Updating an Existing Component Definition
Scenario 1D: Discovering and Acquiring Additional Component Definitions

Scenario 2

Using Attachments

Scenario 2A: Delivering an SSP With Attachments
Scenario 2B: Adding a New Attachment to an SSP
Scenario 2C: Acquiring an SSP With Attachments

All scenarios use https://example.com/v1 as the root URL for the server.

Scenario 1: Using Content Identifiers

Client: OSCAL-based Component Authoring Tool
Server: OSCAL Content Registry

Content Identifiers are crucial to the successful operation of an OSCAL REST OpenAPI implementation. This scenario walks through the lifecycle of content as it is first prepared and introduced into a repository, assigned a content identifier, later retrieved, modified, and re-submitted into the repository. Finally, this scenario will demonstrate how to search and acquire similar artifacts using the content identifier.

POST a Component Definition

Scenario 1A: Initial Delivery of a Component Definition

A user creates an OSCAL component definition file in JSON for Keycloak and wishes to add it to the OSCAL Content Registry for the first time.

POST a Component Definition

Client optionally inserts an external identifier into the metadata before sending it to the server.
a. Client generates a v4 or v5 UUID and inserts it into the OSCAL content's //metadata/document-ids array using http://oscal.io/oscal/identifier/externaluuid for the scheme value. (This example is JSON; however, the OSCAL content may be XML, JSON or YAML, and the inserted document ID must match the native format of the content.)
b. If the organization sends the same component definition to three different repositories, it should have the same external identifier in all three.
c. The external identifier is tracked and managed by the sending organization.

External Document Identifier Added (May be XML, JSON, or YAML)

"metadata": {
   "title" : "Keycloak Docker Image",
   "last-modified" : "2024-11-11T00:00:00Z",
   "oscal-version" : "1.1.2"
   "document-ids": [
      {
         "identifier": "11111111-3333-4000-8000-000000000001",
         "scheme": "http://oscal.io/oscal/identifier/externaluuid"
      }
   ]
}

Partial Structure for Illustrative Purposes Only

Client uses the REST POST method to send the Component Definition File to the OSCAL Content Registry.
a. Client -> Server: POST https://example.com/v1/component-definition
b. Payload: my-component-definition.json (may be XML, JSON, or YAML)
c. HTTP Header: access token
d. HTTP Header: Content-type: application/json
(or application/xml or application/yaml as appropriate)
The OSCAL Content Registry receives and processes the file.
a. The server verifies the access token has write access to the repository.
b. The server verifies the content has valid syntax based on the content's declared OSCAL version (oscal-version).
c. The server optionally stores a snapshot of the original content, exactly as it was received.
d. The server checks for the existence of a content identifier and finds none.
e. The server generates a v4 or v5 UUID and inserts it into the content's //metadata/document-ids array using http://oscal.io/oscal/identifier/contentuuid for the scheme value.
f. The server stores the modified version of the file as the working version.

Content Document Identifier Added (May be XML, JSON, or YAML)

"metadata": {
   "title" : "Keycloak Docker Image",
   "last-modified" : "2024-11-11T00:00:00Z",
   "oscal-version" : "1.1.2"
   "document-ids": [
                {
                    "identifier": "11111111-3333-4000-8000-000000000001",
                    "scheme": "http://oscal.io/oscal/identifier/externaluuid"
                },
                {
                    "identifier": "22222222-3333-4000-8000-000000000001",
                    "scheme": "http://oscal.io/oscal/identifier/contentuuid"
                }
            ],
}

Partial Structure for Illustrative Purposes Only

The server responds to the client to indicate success and report the identifier to be used.
a. Server -> Client:
- Response: 201 Successfully created!
- Payload: component-definition-list object in JSON with exactly one element in it.

Content Document Identifier (May be XML, JSON, or YAML)

{
    "component-definition-list" : [
        {
            "content-uuid": "22222222-3333-4000-8000-000000000001",
            "title" : "Keycloak Docker Image",
            "last-modified" : "2024-11-11T00:00:00Z",
            "oscal-version": "1.1.2",
             "document-ids": [
                {
                    "identifier": "11111111-3333-4000-8000-000000000001",
                    "scheme": "http://oscal.io/oscal/identifier/externaluuid"
                },
                {
                    "identifier": "22222222-3333-4000-8000-000000000001",
                    "scheme": "http://oscal.io/oscal/identifier/contentuuid"
                }
            ],
            "markings" : [],
            "remarks" : ""
        }
    ]
}

Scenario 1B: Acquiring a Component Definition Using a Content Identifier

This scenario addresses the use case where the user wishes to retrieve the Keycloak component definition from the registry in XML format for modification.

GET a Component Definition

Client uses the content-uuid value returned in the JSON response of the Scenario 1A above to formulate a GET request.
a. GET https://example.com/v1/component-definition/22222222-3333-4000-8000-000000000001
b. HTTP Headers:
- access token (not required if the content is publicly available)
- HTTP Header: Accept: application/xml (See the GET /{model-name}/{content-uuid} for the list of accepted MIME types for each OSCAL format.)
The server uses the content UUID value and HTTP Accept Header to identify the requested content in the requested format.
a. The server finds the OSCAL content in it's content repository using the content UUID value 22222222-3333-4000-8000-000000000001 that was assigned in 1A above.
b. If the server does not have the requested OSCAL format available, it converts the content.

Scenario 1C: Updating an Existing Component Definition

After the client in 1B acquires the Keycloak component definition and makes modifications, it then must return the updated file to the server, and elects to use XML format.

PUT a Component Definition

Client modified the content it retrieved in 1B above, and is ready to return the modified version to the server.
Client uses the REST PUT method to replace the Keycloak component definition file in the OSCAL Content Registry with the updated version.
a. Client -> Server: PUT https://example.com/v1/component-definition/22222222-3333-4000-8000-000000000001
b. Payload: my-modified-component-definition.xml (May be XML, JSON, or YAML)
c. HTTP Header: access token
d. HTTP Header: Content-type: application/xml
(or application/json or application/yaml as appropriate)
The Server receives and processes the file.
a. The server verifies the access token has write-access to the repository.
b. The server verifies the content has valid syntax based on the content's declared OSCAL version (oscal-version).
c. The server checks for the existence of the server's working copy of the content using the content identifier and finds it.
d. The server optionally makes a snapshot of the server's working copy.
e. The server replaces its working copy with the content received from the client.
The server responds to the client to indicate success and report the identifier to be used.
a. Server -> Client:
- Response: 204 Success! No Content Returned
- Payload: None

Scenario 1D: Discovering and Acquiring Additional Component Definitions

A System Security Plan (SSP) author is searching for a Keycloak component definition to import into their SSP.

Discovering and Acquiring Component Definitions

The client queries for the list of component definitions

The client discovers the Keycloak component definition and uses its content-uuid value to request it in YAML format

Client queries the OSCAL Content Registry for a list of available component definition files.
a. Client -> Server: GET https://example.com/v1/component-definition
b. Server -> Client: List of component definitions that includes content-uuid, title, version, last-modified and other metadata. (Always in JSON format.)
Client presents list of component definitions to the SSP author.
Author selects Keycloak component definition.
Client imports the component definition file for Keycloak in YAML format.
a. Client -> Server: GET https://example.com/v1/component-definition/ (HTTP Header: Accept: application/xml)
Server responds with
b. Server -> Client: oscal_keycloak_component.xml (delivers the OSCAL Component Definition in XML format)

Payload: Component Definition List

{
    "component-definition-list" : [
        {
            "content-uuid": "22222222-3333-4000-8000-000000000001",
            "title": "First Component Definition",
            "last-modified": "2024-02-01T13:57:28.355446-04:00",
            "version": "20231012",
            "oscal-version": "1.1.2",
             "document-ids": [
                {
                    "identifier": "11111111-3333-4000-8000-000000000001",
                    "scheme": "http://oscal.io/oscal/identifier/externaluuid"
                },
                {
                    "identifier": "22222222-3333-4000-8000-000000000001",
                    "scheme": "http://oscal.io/oscal/identifier/contentuuid"
                }
            ],
            "markings" : [],
            "remarks" : ""
        },
                {
            "content-uuid": "22222222-3333-4000-8000-000000000002",
            "title": "Second Component Definition",
            "last-modified": "2024-02-01T13:57:28.355446-04:00",
            "version": "20231012",
            "oscal-version": "1.1.2",
             "document-ids": [
                {
                    "identifier": "11111111-3333-4000-8000-000000000002",
                    "scheme": "http://oscal.io/oscal/identifier/externaluuid"
                },
                {
                    "identifier": "22222222-3333-4000-8000-000000000002",
                    "scheme": "http://oscal.io/oscal/identifier/contentuuid"
                }
            ],
            "markings" : [],
            "remarks" : ""
        }
    ]
}

Payload: OSCAL Component Definition in YAML Format

-component-definition:
   -metadata
   -component
   -back-matter

Scenario 2: Using Attachments

Client: OSCAL-based SSP Authoring Tool
Server: CISO's GRC Repository

Managing attachments becomes critical when dealing with System Security Plans, Assessment Plans, Assessment Results, and Plans of Action of Milestones. Further, attachments can be quite large and often are not necessary when retrieving OSCAL content. The OSCAL REST OpenAPI Specification enables clients to handle each attachment individually as needed, while maintaining synchronicity with the core OSCAL artifact.

This scenario walks through the lifecycle of delivering an SSP with attachments, later adding additional attachments, acquiring an SSP without attachments, later acquiring some of the attachments.

Scenario 2A: Delivering an SSP With Attachments

An SSP author delivers an OSCAL System Security Plan (SSP) to the ISSO's office for adjudication. The SSP is in OSCAL JSON format. It includes a boundary diagram attachment (Boundary.pdf) in the resources.

with a UUID value of 11111111-2222-4000-8000-001000000001

Delivering an SSP and Attachments

First, the client sends the OSCAL SSP to the server.

Then, the client sends each SSP attachment to the server.

Client optionally inserts an external identifier into the metadata before sending it to the server. (For details, see Scenario 1A above.)
Client uses the REST POST method to send the System Security Plan to the OSCAL Content Registry.
a. Client -> Server: POST https://example.com/v1/system-security-plan
b. Payload: my-system-security-plan.json (may be XML, JSON, or YAML)
c. HTTP Header: access token
d. HTTP Header: Content-type: application/json
(or application/xml or application/yaml as appropriate)
The CISO's GRC Repository receives and processes the file.
a. The server verifies the access token has write access to the repository.
b. The server verifies the content has valid syntax based on the content's declared OSCAL version (oscal-version).
c. The server optionally stores a snapshot of the original content, exactly as it was received.
d. The server checks for the existence of a content identifier and finds none.
e. The server generates a v4 or v5 UUID and inserts it into the content's //metadata/document-ids array using http://oscal.io/oscal/identifier/contentuuid for the scheme value. (For details, see Scenario 1A above.)
f. The server stores the modified version of the file as the working version.
The server responds to the client to indicate success and report the identifier to be used.
a. Server -> Client:
- Response: 201 Successfully created!
- Payload: system-security-plan-list object in JSON with exactly one element in it.
- For details, see Scenario 1A above.
- For the uploaded SSP, the server returns a content UUID value of 11111111-2222-4000-8000-000000000000
Client uploads each SSP attachment.
a. Prior to upload, the SSP had the boundary diagram attached as a resource with a UUID value of 11111111-2222-4000-8000-001000000001
b. Using the content UUID received in step #4 and knowing the resource UUID of the boundary diagram from the SSP that was just uploaded, the client formulates a PUT request.
- Client -> Server: PUT https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000/attachment/11111111-2222-4000-8000-001000000001
- Payload: Boundary.pdf
- HTTP Header: Access Token
  c. The server verifies the access token has write permissions to the SSP.
  d. The server stores the attachment and revises the rlink/href value to https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000/attachment/11111111-2222-4000-8000-001000000001
  e. Server returns status 204 Success
Client repeats step #2 as necessary for each additional attachment defined int the SSP's back-matter.

Content Document Identifier (May be XML, JSON, or YAML)

{
    "system-security-plan-list" : [
        {
            "content-uuid": "22222222-2222-4000-8000-000000000001",
            "title" : "System Security Plan for My System",
            "last-modified" : "2024-11-11T00:00:00Z",
            "oscal-version": "1.1.2",
             "document-ids": [
                {
                    "identifier": "11111111-2222-4000-8000-000000000001",
                    "scheme": "http://oscal.io/oscal/identifier/externaluuid"
                },
                {
                    "identifier": "22222222-2222-4000-8000-000000000001",
                    "scheme": "http://oscal.io/oscal/identifier/contentuuid"
                }
            ],
            "markings" : [],
            "remarks" : ""
        }
    ]
}

Scenario 2B: Adding a New Attachment to an SSP

An SSP author wishes to add a new attachment to the SSP delivered above. The new attachment is a configuration management plan (CM_plan.pdf) that is not yet defined in the SSP's back-matter. The author wishes to include a title, version, date, and attachment type in the resource entry.

Adding a New Attachment

First, the client sends the new attachment.

Then, the client sends any details for the OSCAL SSP's resource.

Client uses the content uuid from above to send the new SSP attachment.
1. Client -> Server: POST https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000/attachment
- (Payload: CM_plan.pdf)
The CISO's GRC Repository receives and processes the file.
a. The server verifies the access token has write access to the repository.
b. Server generates a v4 or v5 UUID value for the attachment. (11111111-2222-4000-8000-001000000002)
c. Server stores the attachment and associates the UUID with the attachment.
d. Server creates a new back-matter resource in the SSP and assigns it the same UUID value.
The server returns the resource
a. Server -> Client: The newly created resource entry (JSON), which includes the UUID value generated in step 2.b. above. (11111111-2222-4000-8000-001000000002)
The client is then able to send additional resource content, including the title, properties (props), and remarks.
1. Client -> Server: PUT https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000/attachment/11111111-2222-4000-8000-001000000002/resource
- Payload: updated resource content (Always in JSON format)

Scenario 2C: Acquiring an SSP With Attachments

An Assessment Lead needs to retrieve an OSCAL-based SSP from the ISSO office's GRC repository. The SSP includes a boundary diagram attachment (Boundary.pdf) in the OSCAL-SSP's resources:

title

The assessor's tool retrieves a list of SSPs from the CISO's GRC Repository:
1. Client -> Server: GET https://example.com/v1/system-security-plan (HTTP Header: Access Token)
2. Server compiles list of SSPs to which the assessor has access based on access token.
3. Server -> Client: List of accessible SSPs, which includes content-uuid, title, version, last-modified and other metadata (JSON).
Client presents list of SSPs to the assessor.
Assessor selects the relevant SSP.
Client imports the SSP in YAML format.
1. Client -> Server: GET https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000 (HTTP Headers: Access Token, Accept: application/yaml)
2. Server verifies the access token has read-permission for the SSP
3. Server -> Client: oscal_system-security-plan.yaml
Assessor reviews SSP and wishes to see the boundary diagram.
1. Client extracts first rlink/href value from the OSCAL SSP.
2. Client -> Server: GET https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000/attachment/11111111-2222-4000-8000-001000000001
- HTTP Header: Access Token
1. Server verifies the access token has read permission for the SSP
2. Server -> Client: Boundary.pdf
Assessor now wishes to see the CM Plan.
1. Client extracts first rlink/href value from the OSCAL SSP.
2. Client -> Server: GET https://example.com/v1/system-security-plan/11111111-2222-4000-8000-000000000000/attachment/11111111-2222-4000-8000-001000000002 (HTTP Header: Access Token)
3. Server verifies the access token has read permission for the SSP
4. Server -> Client: Boundary.pdf