Support non-control driven field editing in SSP

[jpower432]

Issue description / feature objectives

Currently most of the support around SSP editing in markdown is for the control-implementation section. To reduce the amount of data edited through the JSON files, I propose we add support to edit non-control driven sections or fields in the SSP through a more user friendly option.

Caveats / Assumptions

This expands original project scope

Completion Criteria

• High-level design
• Clearly articulated set of issues with a forward looking plan on what fields to support. At minimum, the metadata and system-implementation fields

Proposed child Issues #1539

Community discussion about this Epic in Slack.
Relevant GitHub community discussion - #1025

[rahearn]

We would love to see this implemented to assist in the following use cases and goals:

Fields that benefit from being in easier to read formats than JSON

Many fields are extremely valuable for everyday developers to be able to read and update in the course of normal operations. These are generally the fields with mutli-line markdown format, and diagrams that can be implemented within markdown (optionally, it's how we do a lot of diagrams anyway with tools like PlantUML)

• system-characteristics
  • description
  • authorization-boundary (description & diagram)
  • network-diagrams (description & diagram)
  • data-flow-diagrams (description & diagram)

Fields that benefit from having a tool generate UUIDs and automatically link them in the various places they're referenced:

These often also benefit from having a description field that is easily read/writable by being in markdown.

• metadata
  • roles
  • people
• system-implementation
  • users
  • ports/protocols/services
  • system inventory

Deduplication benefit

Ideally (recognizing this is a giant lift to fully represent the oscal model in markdown/yaml frontmatter), if everything is out of the JSON representation, then we can move to a place where only the yaml/markdown files are checked into source control, and the full JSON model is only generated in CI. That would eliminate any confusion about having to edit markdown, then assemble, then tweak the json for certain fields, then check it all into source control.

Right now we deal with that by calling trestle author ssp-assemble followed by trestle split to break the fields into a "please edit these files" group and a "please do not edit these files and instead edit the markdown" group.

[pcsherid]

We think this makes a lot of sense to expand the trestle feature set to include editing of the SSP frontmatter. This adds to a more complete automation workflow.

[jpower432]

Adding some initial thoughts around design from #1539 and #1538.
@rahearn @pcsherid @AleJo2995 @vikas-agarwal76 Please feel free to jump in with any questions, thoughts, or ideas. I am hoping this can serve as a jumping off point for discussion.

Metadata

This could also extend to the system-implementation if in the SSP context

Behavior: *-generate commands would create a new top-level directory to edit non-control markdown. For each control markdown, metadata that could be referenced in the control-implementation can be added in the YAML header. This would initially support adding to the implemented-requirement or statement.

Example:

---
x-trestle-oscal-metadata:
  # Add or modify links to metadata
  # May add to the control or part level
  # Supported types and values can be found <ref to markdown>
  # Example
  #   - type: role
  #     token: role-id
  #     smt-part: b.
  #
  - type: role
    token: org1
  - type: role
    token: org2
    smt-part: b.
---

SSP Aggregation:
For the by-component, I think it makes sense to aggregate certain metadata from the component definitions into the metadata markdown and allow user to refine the existing roles or linked field for the SSP.

Roles or linked fields should be retained on each by-component if the roles still exists in the SSP. Reassignment could probably be out of scope initially.

Additional Considerations

With the management of this many UUIDs and to retain the idempotent nature of updates in trestle authoring commands, I am wondering if exploring deterministic UUID creation would be beneficial. OSCAL supports UUID v5. Then the UUID could, for instance, be generated using the role-id input token and a namespace. However, this might not work if inheriting UUIDs from another document so keeping the underlying in-place approach may be preferable.

There would have to be reusable metadata assembly logic possibly added to the CatalogReader as well as generation logic added to the CatalogWriter.

Proposed In Scope (for the Epic)

title
roles
locations
parties
responsible-parties
actions

Proposed Out of Scope

OSCAL Version (This should be set with the *-assemble commands)
Dates (e.g. last modified)

Diagrams

My thoughts on diagrams are less concrete, but adding some initial ideas below.

Supporting system-characteristics may be slight different. Perhaps we could support linking this in multiple ways with Markdown being one of the options. The diagrams could be authored separately and passed to trestle as links and Markdown could be generated per diagram link to allow for the description to be populated. The diagram link could be stored in the YAML header that could be assembled into the JSON.

[rahearn]

The diagrams could be authored separately and passed to trestle as links and Markdown could be generated per diagram link to allow for the description to be populated. The diagram link could be stored in the YAML header that could be assembled into the JSON.

I like that proposal. A potential improvement I'd love would be the diagram markdown file has:

1. a link to the rendered diagram in the YAML header
2. (optional) a section that is ignored during *-assemble that could contain the diagram source (specifically thinking about PlantUML diagrams here, but maybe useful for other diagramming languages as well)
3. a section that is bundled into the diagram description during *-assemble

[github-actions]

This issue has been automatically marked as stale because it has not had activity within 90 days. It will be automatically closed if no further activity occurs within 30 days.

[jpower432]

Hey folks. I am proposing the following child issues be linked or added. We could some of the design considerations above to the issue content for further discussion:

• Allow OSCAL metadata to be edited through the trestle author commands #1539
• Rendering system and component structure to a diagram #1743
• Support adding responsible role information in the control markdown #1538
• Allow system implementation to be edited through trestle ssp author commands