Manage Resolved Profile Snapshot Tagging

[brian-ruf-ezd]

Description

As a developer issuing OSCAL REST API calls to manage resolved snapshots, I want resolved snapshots to be tagged with certain information, and I want to be able to manage that information.

Specifically, I want resolved snapshots to include properties in the metadata (metadata/props) to address:

• Snapshot Time Stamp: Required timestamp indicating when the snapshot was created. There is no mechanism for setting this. It is assigned automatically by the implementation at the time the snapshot is created.
• Snapshot Description: Optional user-assigned description of the snapshot.
• Snapshot Label: Optional user-assigned label for the snapshot. There may be more than one.
• Snapshot Type: Indicates the type of snapshot, such as to represent a formal, published version of the OSCAL content or an informal working copy, as well as to indicate whether the snapshot was automatically or manually created. There may be more than one.

I want to be able to provide this information when creating a resolved snapshot and manage it after the snapshot is created.

Acceptance Criteria

Expand the REST specification to include the following:

• Update GET /{model-name}/{id}/resolved-snapshot as follows:

  • [ ] The return content list items must include a resolved-snapshot node as defined below
  • [ ] Change the top level node name from catalog-snapshot-list to resolved-snapshot-list, since the return content for this includes data not appropriate for the catalog-list schema.
  • [x] The summary and description for GET /{model-name}/{id}/resolved-snapshot is also updated as described in issue #88

• Update POST /{model-name}/{id}/resolved-snapshot as follows:

  • [ ] The summary is revised to say, "Resolves the profile and saves the result."
  • [ ] The description is revised with the content shown below.
  • [ ] This payload allows JSON as defined below.
  • [ ] The method return content is updated as follows:
    • [ ] Change the top level node name from resolved-list to resolved-snapshot-list, which is the same as GET. The only difference is that this should always have exactly one item in the list and GET can have 0 or more elements in the list.
    • [ ] include a "snapshot" node as described below.

• [ ] Add PUT /{model-name}/{id}/resolved-snapshot/{id} to the specification

  • [ ] The summary should say, "Modifies the snapshot description, types and label."
  • [ ] The description should be included as shown below.
  • [ ] The payload allows JSON as described below.
  • [ ] The method returns the following status codes (consistent with other PUT methods):
    • [ ] 204 Successful update
    • [ ] 400, 401, 403, 404, 409, 410, 415, 422

Description Content

Description for POST /{model-name}/{id}/resolved-snapshot

Processes the profile and creates a snapshot as a resolved profile catalog. The implementation _must_ assign and track a unique identifier for the snapshot, by which the snapshot may be referenced later. The implementation _must_ add the `snapshot-created` property and a `snapshot-type` set to `resolved-profile` in the OSCAL document's `metadata` as follows:

- **Resolved Snapshot Created** Property [**Exactly 1 (REQUIRED)**]: 
  - `"name" : "snapshot-created"`
  - `"value" : "2024-03-24T16:10:42.251Z"` (date-time-with-timezone)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`

- **Resolved Snapshot Type** Property [**1 or more**]: 
  - `"name" : "snapshot-type"`
  - `"value" : "resolved-profile"` 
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`

The implementation implementation _may_ set a `snapshot-description` property, as well as `snapshot-label` and additional `snapshot-type` properties to the OSCAL document's `metadata` as follows when included in the payload from the client: 

- **Resolved Snapshot Description** Property [**0 or 1 (OPTIONAL)**]: 
  - `"name" : "snapshot-description"`
  - `"value" : "na"` (`value` is required by OSCAL, but not needed for this property. It can include any string.)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`
  - `"remarks" : "An optional resolved snapshot description."` (markup-multiline)

- **Snapshot Label** Property [**0 or more (OPTIONAL)**]: 
  - `"name" : "snapshot-label"`
  - `"value" : "v1.2.3"` (token)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`

- **Resolved Snapshot Type** Property [**1 or more**]: 
  - `"name" : "snapshot-type"`
  - `"value" : "resolved-profile"` (token)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`

All of the above properties are OSCAL extensions and must include the namespace (`ns`) information.

Description for PUT /{model-name}/{id}/resolved-snapshot/{id}

Modifies the resolved snapshot description, as well as the resolved snapshot type and label tags. The implementation must ensure the `snapshot-created` property and the `snapshot-type` property indicating `resolved-profile` are immutable.  The following properties may be added, changed, or removed by this method. 

- **Snapshot Description** Property [**0 or 1 (OPTIONAL)**]: 
  - `"name" : "snapshot-description"`
  - `"value" : "na"` (Value is required by OSCAL, but not needed for this property. It can include any string.)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`
  - `"remarks" : "An optional snapshot description."` (markup-multiline)

- **Snapshot Label** Property [**0 or more (OPTIONAL)**]: 
  - `"name" : "snapshot-label"`
  - `"value" : "v1.2.3"` (token)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`

- **Snapshot Type** Property [**0 or more (OPTIONAL)**]: 
  - `"name" : "snapshot-type"`
  - `"value" : "published"` (token)
  - `"ns" : "http://oscal.io/ns/oscal/1.0.0"`

All of the above properties are OSCAL extensions and must include the namespace (`ns`) information.

Payload

The payload for POST /{model-name}/{id}/resolved-snapshot and PUT /{model-name}/{id}/resolved-snapshot/{id}` is specified as follows:

{
    "snapshot" : {
    	"description" : "markup-multiline",
    	"labels": ["token"],
    	"types" : ["token"]
	}
}

• labels have a cardinality of 0 or more
• types have a cardinality of 0 or more
• description has a cardinality of 0 or 1

Return Content

Each list item in the resolved-snapshot-list JSON object must be expanded to include a snapshot node with the following child-nodes:

• [ ] "created" field (date-time-with-timezone) cardinality of exactly 1
• [ ] "description" field (markup-multiline) cardinality of 0 or 1
• [ ] "types" array of tokens with cardinality of 0 or more
• [ ] "labels" array of tokens with cardinality of 0 or more

{
  "resolved-snapshot-list": [
    {
      "file-id": "BDDd1907-b362-5B1E-Bb0a-6E88CC4Bd6Bd",
      "title": "string",
      "published": "2024-03-24T16:10:42.251Z",
      "last-modified": "2024-03-24T16:10:42.251Z",
      "version": "Rv;XFD:(`%n&.EuD6/.& 09Y[B6>$'3d:0",
      "oscal-version": "{",
      "document-ids": {
        "document-ids": [
          {
            "document-id": {
              "scheme": "asGkkAK6e1wzlYsqYe8XshSdhF4Mwzmaxov-J4pc53DpP5LiDB-Pfdcn9Ki7AdUmd.IeHl9tKKypZOKJNjURt559ut4KexB:0K/:('*fXiU-%4Mb",
              "identifier": "string"
            }
          }
        ]
      },
      "markings": [
        "string"
      ],
      "status": "string",
      "remarks": "string",

     "comment" : "-------------------------------------------------------------------------------- (remove this)",

      "snapshot" : {
         "created" : "2024-03-24T16:10:42.251Z",
         "description" : "markup-multiline",
         "labels": ["token"],
         "types" : ["token"]
	},

     "comment" : "-------------------------------------------------------------------------------- (remove this)",

    }
  ]
}

[brian-ruf-ezd]

~80% complete. Handled linting issues. Expect to complete remaining 20% plus testing in sprint 68.

[brian-ruf-ezd]

Reviewed 2024-05-22. LGTM