Usage Scenarios

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.

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.

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

"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"
      }
   ]
}

2. 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)

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

"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"
                }
            ],
}

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

{
    "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.

1. 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.)
2. 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.
   • Each implementation is free to determine if they wish to convert to all formats upon receipt or convert upon request.
   • If converting upon request, the server should implement a 202 response with a URL that the client can use to monitor for completion.
     c. The server returns the requested OSCAL content in the requested format.
   • Response: 200
   • Payload: keycloak-component.definition.xml
   • HTTP Header: Content-type: application/xml (May be application/json or application/yaml if either of those formats were requested.)

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.

1. Client modified the content it retrieved in 1B above, and is ready to return the modified version to the server.

2. 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)

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

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

1. 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.)
2. Client presents list of component definitions to the SSP author.
3. Author selects Keycloak component definition.
4. 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)
5. Server responds with
   b. Server -> Client: oscal_keycloak_component.xml (delivers the OSCAL Component Definition in XML format)

{
    "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" : ""
        }
    ]
}

-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

1. Client optionally inserts an external identifier into the metadata before sending it to the server. (For details, see Scenario 1A above.)

2. 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)

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

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

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

6. Client repeats step #2 as necessary for each additional attachment defined int the SSP's back-matter.

{
    "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.

1. 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)

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

3. 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)

4. 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:

1. 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).
2. Client presents list of SSPs to the assessor.
3. Assessor selects the relevant SSP.
4. 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
5. 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
   4. Server verifies the access token has read permission for the SSP
   5. Server -> Client: Boundary.pdf
6. 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