feat: add inheritance view to ssp-generate and ssp-assemble (#1441)

* feat: adds ability to process exports from SSP and write Markdown by component Adds ExportInterface and ExportWriter classes Adds Markdown generation to ssp-generate Add MarkdownWriter for leveraged statements Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> Signed-off-by: Alex Flom <alexander.flom@gmail.com> * feat: adds InheritanceMarkdownReader for reading leveraged statement markdown Adds InheritanceMarkdownReader for processing into a leveraging SSP context Adds persistance for components and satisified statements during updates Changes leveraging component from a single dictionary to a list Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * feat: Adds reader class for inheritance markdown Adds ExportReader class Removes ExportInterface class Adds a single ByComponentInterface class to interact with the model in terms of inheritance Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> Co-authored-by: Jennifer Power <barnabei.jennifer@gmail.com> * docs: updates documentation with usage and API references updates for inheritance Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * chore: updates AgileAuthoring class for ssp-generate arg changes Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * docs: updates returns section in InheritanceMarkdownReader docstring Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * fix: updates line length on return statement in InheritanceMarkdownReader Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * refactor: updates markdown heading and comment strip function to remove regex Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * test: adds inheritance view testing for ssp-assemble Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * chore: adds more context to ExportReader class comments Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * feat: updates ssp-generate to filter control implementation for leveraged_ssp Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * refactor: updates ExportWriter to reduce code duplication Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * fix: updates ExportReader to add new statements if present in the inheritance view Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * fix: update logging to debug in ExportReader Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * refactor: simplify code in read_exports_from_markdown Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * tests: simplify tests for ExportReader test data generation Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * refactor: reduce code duplication in ExportReader methods Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * fix: allows inheritance info to be removed when component is unmapped Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * feat: adds leveraged authorization updates to system implementation Adds SSPInheritanceAPI class for interacting with leveraged auth information Adds trestle global tags to markdown to store SSP location info Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> Co-authored-by: Alex Flom <alexander.flom@gmail.com> * docs: add docs updates for SSPInheritanceAPI class Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * chore: updates warning message for leveraged authorization with comps Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * fix: updates ssp-assemble to ensure existing leveraged comps persist Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * fix: adds fixes to address PR feedback Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * refactor: polishes SSPInheritanceAPI class to reduce complexity Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> --------- Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> Signed-off-by: Alex Flom <alexander.flom@gmail.com> Co-authored-by: Alex Flom <aflom@redhat.com> Co-authored-by: Alex Flom <alexander.flom@gmail.com>
oscal-compass · Nov 9, 2023 · 6cf498b · 6cf498b
1 parent 5ac3067
commit 6cf498b
Show file tree

Hide file tree

Showing 27 changed files with 2,964 additions and 6 deletions.
diff --git a/.gitignore b/.gitignore
@@ -49,3 +49,5 @@ site
 tmp_bin_test
 .mypy_cache
 
+/venv.trestle/
+
diff --git a/docs/api_reference/trestle.core.crm.bycomp_interface.md b/docs/api_reference/trestle.core.crm.bycomp_interface.md
@@ -0,0 +1,2 @@
+::: trestle.core.crm.bycomp_interface
+handler: python
diff --git a/docs/api_reference/trestle.core.crm.export_reader.md b/docs/api_reference/trestle.core.crm.export_reader.md
@@ -0,0 +1,2 @@
+::: trestle.core.crm.export_reader
+handler: python
diff --git a/docs/api_reference/trestle.core.crm.export_writer.md b/docs/api_reference/trestle.core.crm.export_writer.md
@@ -0,0 +1,2 @@
+::: trestle.core.crm.export_writer
+handler: python
diff --git a/docs/api_reference/trestle.core.crm.leveraged_statements.md b/docs/api_reference/trestle.core.crm.leveraged_statements.md
@@ -0,0 +1,2 @@
+::: trestle.core.crm.leveraged_statements
+handler: python
diff --git a/docs/api_reference/trestle.core.crm.ssp_inheritance_api.md b/docs/api_reference/trestle.core.crm.ssp_inheritance_api.md
@@ -0,0 +1,2 @@
+::: trestle.core.crm.ssp_inheritance_api
+handler: python
diff --git a/docs/tutorials/ssp_profile_catalog_authoring/ssp_profile_catalog_authoring.md b/docs/tutorials/ssp_profile_catalog_authoring/ssp_profile_catalog_authoring.md
@@ -1050,6 +1050,131 @@ As with all the `assemble` tools, you may optionally specify a `--name` for a co
 
 If you do not specify component-defintions during assembly, the markdown should not refer to any components other than `This System`.  Thus you may first generate markdown with `ssp-generate` and no component-definitions specified - and then you may assemble that ssp with `ssp-assemble` and no component-definitions specified - but only if there are no components other than `This System` referenced in the markdown.  You may add new component implementation details to the markdown later, but any new components must be defined in a component-defintion file, and that file must be specified when `ssp-assemble` is run.
 
+## Inheritance view
+
+The inheritance view is generated by setting the `--leveraged-ssp` flag with `trestle author ssp-generate`. It contains information relating to exported information such as inherited capabilities and customer responsibilities that can be used to populate the inheritance information in the assembled SSP. When used, a directory named "inheritance" is created within the markdown directory. This directory serves as a designated space for  mapping inherited capabilities and responsibilities onto components in the assemble SSP and authoring satisfied statements for responsibilities.
+
+Example usage for creation of the markdown:
+
+`trestle author ssp-generate --profile my_prof --compdefs "compdef_a,compdef_b" --yaml /my_yaml_dir/header.yaml --leveraged-ssp my_provider_ssp --output my_ssp`
+
+In this example the leveraged ssp has previously been imported into the trestle directory, but it can be fetched from remote location.
+
+The generated markdown output with the inheritance view will be placed in the trestle subdirectory `my_ssp/inheritance` with a subdirectory for each component in the leveraged ssp with directories separated by control and statement id below.
+
+An example of this directory structure is below.
+
+```text
+.
+├── Application
+│   ├── ac-1_stmt.a
+│   │   └── 11111111-0000-4000-9009-001001002006.md
+│   ├── ac-2.1
+│   │   └── 11111111-0000-4000-9009-001001002004.md
+│   └── ac-2_stmt.a
+│       └── 11111111-0000-4000-9009-002001002001_11111111-0000-4000-9009-002001002002.md
+└── This System
+    ├── ac-1_stmt.a
+    │   └── 11111111-0000-4000-9009-001002002001.md
+    ├── ac-2.1
+    │   └── 11111111-0000-4000-9009-001001002001.md
+    └── ac-2_stmt.a
+        └── 11111111-0000-4000-9009-002001001001.md
+```
+
+The leveraged components are used as the top level directory to allow any non-leveraged components to be easily skipped or removed. Each markdown file is named in accordance with the uuid of the exported statement to ensure statement description updates can be applied.
+
+There are three types of markdown files that can be generated from this process.
+
+The examples below demonstrate these types:
+
+<details markdown>
+
+<summary>Example of inheritance provided only markdown after ssp-generate</summary>
+
+```markdown
+---
+x-trestle-statement:
+  # Add or modify leveraged SSP Statements here.
+  provided-uuid: 11111111-0000-4000-9009-001002002001
+x-trestle-leveraging-comp:
+  # Leveraged statements can be optionally associated with components in this system.
+  # Associate leveraged statements to Components of this system here:
+  - name: REPLACE_ME
+---
+
+# Provided Statement Description
+
+Customer_appropriate description of what may be inherited.
+```
+
+</details>
+
+<details markdown>
+
+<summary>Example of inheritance customer responsibility only markdown after ssp-generate</summary>
+
+```markdown
+---
+x-trestle-statement:
+  # Add or modify leveraged SSP Statements here.
+  responsibility-uuid: 11111111-0000-4000-9009-002001001001
+x-trestle-leveraging-comp:
+  # Leveraged statements can be optionally associated with components in this system.
+  # Associate leveraged statements to Components of this system here:
+  - name: REPLACE_ME
+---
+
+# Responsibility Statement Description
+
+Leveraging system's responsibilities with respect to inheriting this capability.
+
+# Satisfied Statement Description
+
+<!-- Use this section to explain how the inherited responsibility is being satisfied. -->
+```
+
+</details>
+
+<details markdown>
+
+<summary>Example of inheritance shared responsibility markdown after ssp-generate</summary>
+
+```markdown
+---
+x-trestle-statement:
+  # Add or modify leveraged SSP Statements here.
+  provided-uuid: 11111111-0000-4000-9009-002001002001
+  responsibility-uuid: 11111111-0000-4000-9009-002001002002
+x-trestle-leveraging-comp:
+  # Leveraged statements can be optionally associated with components in this system.
+  # Associate leveraged statements to Components of this system here:
+  - name: REPLACE_ME
+---
+
+# Provided Statement Description
+
+Consumer-appropriate description of what may be inherited.
+
+# Responsibility Statement Description
+
+Leveraging system's responsibilities with respect to inheriting this capability.
+
+# Satisfied Statement Description
+
+<!-- Use this section to explain how the inherited responsibility is being satisfied. -->
+```
+
+</details>
+
+Some additional information and tips about this markdown are below:
+
+- Do not change the statement UUIDs in the YAML header. This is used in the assembled JSON to link the statements in the leveraged SSP to the components in the leveraging SSP.
+- When mapping components in the YAML header, use the component title. If you do not wish to map a component to a particular inherited capability or responsibility, just leave the file as is. Files without mapped components or that contain the default "REPLACE ME" entry will be skipped.
+- If the file exists, just the editable information will be preserved when regenerating existing inheritance view markdown. This includes the information under `Satisfied Statement Description` and the mapped components in the YAML header.
+
+After manually editing the inheritance view markdown, the `trestle author ssp-assemble` command can be run without modifications for the inheritance view use case. During assemble, the inheritance directory is detected and the information will be assembled into the SSP. The by-component assemblies will be updated or added under existing implemented requirement or statement sections with the information from the markdown.
+
 </details>
 
 <details markdown>

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -113,6 +113,12 @@ nav:
       - control_interface: api_reference/trestle.core.control_interface.md
       - control_reader: api_reference/trestle.core.control_reader.md
       - control_writer: api_reference/trestle.core.control_writer.md
+      - crm:
+        - bycomp_interface: api_reference/trestle.core.crm.bycomp_interface.md
+        - export_reader: api_reference/trestle.core.crm.export_reader.md
+        - export_writer: api_reference/trestle.core.crm.export_writer.md
+        - leveraged_statements: api_reference/trestle.core.crm.leveraged_statements.md
+        - ssp_inheritance_api: api_reference/trestle.core.crm.ssp_inheritance_api.md
       - docs_control_writer: api_reference/trestle.core.docs_control_writer.md
       - draw_io: api_reference/trestle.core.draw_io.md
       - duplicates_validator: api_reference/trestle.core.duplicates_validator.md