Usage Scenarios

Scenarios

• Find and Acquire Component Definitions
• Deliver an SSP With Attachments
• Add a New Attachment to an SSP
• Retrieve an SSP With Attachments

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

Find and Acquire Component Definitions

A System Security Plan (SSP) author has elected to use Keycloak for identity management and wishes to include information about Keycloak in their SSP.

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

1. Client queries the OSCAL Content Registry for a list of available component definition files.
   1. Client -> Server: GET https://example.com/component-definition
   2. Server -> Client: List of component definitions that includes file-id, title, version, last-modified and other metadata (JSON)
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 XML format.
   1. Client -> Server: GET https://example.com/component-definition/abc-123 (HTTP Header: Accept: application/xml)
   2. Server -> Client: oscal_keycloak_component.xml (delivers the OSCAL Component Definition in XML format)

Deliver an SSP With Attachments

An SSP author delivers an OSCAL-based 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 2ba7db9b-4603-4574-8eb2-93a447dbcd29l

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

1. Client sends the SSP to the CISO's GRC Repository
   1. Client -> Server: POST https://example.com/system-security-plan (HTTP Headers: Access Token, Content-type: application/json)(Payload: oscal_ssp.json)
   2. Server verifies the access token was create-new permissions.
   3. Server assigns a unique file identifier ("file-id": "ssp-8675309").
   4. Server stores the SSP and associates the file-id with it
   5. Server -> Client: SSP list entry that includes file-id, title, version, last-modified and other metadata (JSON).
2. Client uploads SSP attachments.
   1. Client -> Server: PUT https://example.com/system-security-plan/ssp-8675309/attachment/2ba7db9b-4603-4574-8eb2-93a447dbcd29 (Boundary.pdf is the payload)(HTTP Header: Access Token)
   2. Server verifies the access token has write permissions to the SSP.
   3. Server stores the attachment and revises the rlink/href value to https://example.com/system-security-plan/ssp-8675309/attachment/2ba7db9b-4603-4574-8eb2-93a447dbcd29
   4. Server returns status 200 with no payload.
3. Client repeats step #2 as necessary for each additional attachment defined int the SSP's back-matter.

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

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

1. Client sends SSP attachment.
   1. Client -> Server: POST https://example.com/system-security-plan/{file-id}/attachment (Payload: CM_plan.pdf)
   2. Server generates a v4 or v5 UUID value for the attachment. (e6b48e1e-b94d-4fbf-9599-1becd4b11144)
   3. Server stores the attachment and associates the UUID with the attachment.
   4. Server creates a new back-matter resource in the SSP and assigns it the same UUID value.
   5. Server -> Client: The newly created resource entry (JSON), which includes the UUID value above.
2. Client sends updated resource content with title, properties, and remarks.
   1. Client -> Server: PUT https://example.com/system-security-plan/ssp-8675309/attachment/e6b48e1e-b94d-4fbf-9599-1becd4b11144/resource (Payload: updated resource content)(JSON)

Retrieve 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:

Client: OSCAL-based Assessment Planning Tool
Server: CISO's GRC Repository

1. The assessor's tool retrieves a list of SSPs from the CISO's GRC Repository:
   1. Client -> Server: GET https://example.com/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 file-id, 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/system-security-plan/ssp-8675309 (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 rlink/href value from the OSCAL SSP.
   2. Client -> Server: GET https://example.com/system-security-plan/ssp-8675309/attachment/2ba7db9b-4603-4574-8eb2-93a447dbcd29 (HTTP Header: Access Token)
   3. Server verifies the access token has read permission for the SSP
   4. Server -> Client: Boundary.pdf