feat: add profile-inherit command (#1392)

* test: adds testdata for profile init tests Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * feat(cli): adds profile-seed command Adds profile-seed as author subcommand Adds profile-seed unit test Adds SSP testdata Closes #1388 Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * chore: updates flag wording in profile.py Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * test: adds test case for profile-seed Adds additional test case to check for ids output when all controls are filtered out Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * test: updates description leveraged ssp testdata Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * docs: updates author and tutorial docs with information on profile-seed command Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * chore: updates command to profile-inherit in docs and code Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * feat: adds excluded controls to the profile-inherit generated profile Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * docs: adds JSON example of profile-inherit import to website docs Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> * chore: adds PR feedback on styling Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com> --------- Signed-off-by: Jennifer Power <barnabei.jennifer@gmail.com>
oscal-compass · Jun 16, 2023 · 3bd53ff · 3bd53ff
1 parent 5f59a7f
commit 3bd53ff
Show file tree

Hide file tree

Showing 13 changed files with 1,259 additions and 3 deletions.
diff --git a/docs/trestle_author.md b/docs/trestle_author.md
@@ -591,6 +591,21 @@ CLI evocation:
 
 The `profile` author commands allow you to edit additions made by a profile to its imported controls that end up in the final resolved profile catalog.  Only the additions may be edited or added to the generated markdown control files - and those additions can then be assembled into a new version of the original profile, with those additions.  For more details on its usage please see [the profile authoring tutorial](https://ibm.github.io/compliance-trestle/tutorials/ssp_profile_catalog_authoring/ssp_profile_catalog_authoring).
 
+### Profile generation with inheritance
+
+CLI evocation:
+
+> trestle author profile-inherit
+
+The `profile-inherit` sub-command takes a given parent profile and filters its imported controls based inherited controls from a given SSP.
+
+The leveraged SSP is evaluated based on whether provided and responsibility statements for all `by-component` fields are set for each applicable control, as well as the implementation status.
+All components must have exported provided statements, no exported responsibility statements, and an implementation status of `implemented` in order for a control to be filtered from the output profile (i.e. controls delta profile).
+
+As with the other related author commands, if an existing destination file already exists, it is not updated if no changes would be made.
+
+For more details on its usage please see [the ssp-filter tutorial](https://ibm.github.io/compliance-trestle/tutorials/ssp_profile_catalog_authoring/ssp_profile_catalog_authoring).
+
 ### SSP authoring
 
 CLI evocation:

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
@@ -27,6 +27,7 @@ The author commands are:
 1. `catalog-generate` converts a control Catalog to individual controls in markdown format for addition or editing of guidance prose and parameters, with parameters stored in a yaml header at the top of the markdown file.  `catalog-assemble` then gathers the prose and parameters and updates the controls in the Catalog to make a new OSCAL Catalog.
 1. `profile-generate` takes a given Profile and converts the controls represented by its resolved profile catalog to individual controls in markdown format, with sections corresponding to the content that the Profile adds to the Catalog, along with both the current values of parameters in the resolved profile catalog - and the values that are being modified by the given profile's SetParameters.  The user may edit the content or add more, and `profile-assemble` then gathers the updated content and creates a new OSCAL Profile that includes those changes.
 1. `profile-resolve` is special as an authoring tool because it does not involve markdown and instead it simply creates a JSON resolved profile catalog from a specified JSON profile in the trestle directory.  There are options to specify whether or not parameters get replace in the control prose or not, along with any special brackets that might be desired to indicate the parameters embedded in the prose.
+1. `profile-inherit` takes a given parent profile and filters its contents based on the inherited controls included in a given ssp to be include in the final profile.
 1. `component-generate` takes a given ComponentDefinition file and represents all the controls in markdown in separate directories for each Component in the file.  This allows editing of the prose on a per-component basis.  `component-assemble` then assembles the markdown for all controls in all component directories into a new, or the same, ComponentDefinition file.
 1. `ssp-generate` takes a given Profile and an optional list of component-definitions, and represents the individual controls as markdown files with sections that prompt for prose regarding the implementation response for items in the statement of the control, with separate response sections for each component.  `ssp-assemble` then gathers the response sections and creates an OSCAL System Security Plan comprising the resolved profile catalog and the implementation responses for each component.  The list of component-definitions is optional, but without them the SSP will only have one component: `This System`.  Rules, parameters and status associated with the implemented requirements are stored in the SetParameters and Properties of the components in the component definitions and represented in the markdown, allowing changes to be made to the parameter values and status.  These edits are then included in the assembled SSP.  Note that the rules themselves may not be edited and strictly correspond to what is in the component definitions.
 1. `ssp-filter` takes a given ssp and filters its contents based on the controls included in a provided profile, or in a list of components to be included in the final ssp.
@@ -524,6 +525,51 @@ Similar options apply to the `jinja` authoring commands.
 
 <details markdown>
 
+<summary>trestle author profile-inherit</summary>
+
+The `trestle author profile-inherit` command is different from the `generate/assemble` commands because it doesn't involve markdown and instead
+it takes an parent profile and ssp and creates child profile in `JSON` format.
+
+When utilizing a process with leveraged authorizations, use the command `trestle author profile-inherit` to create a profile with initial content using a parent profile and SSP with inheritable controls. The provided and responsibility statements for all `by-component` fields, as well as the implementation status, will be used to evaluate the leveraged SSP.
+To be filtered from the output profile (i.e. controls delta profile), all components must have exported provided statements, no exported responsibility statements, and an implementation status of `implemented`.
+
+The filter command is invoked as:
+
+`trestle author profile-inherit --profile my_parent --ssp my_leveraged_ssp --output controls_delta_profile`
+
+Both the parent profile and the SSP must be present in the trestle workspace. This command produces a new workspace profile that imports the parent profile and filters the inherited controls from the SSP using the `exclude-controls` and `include-controls` fields in the profile import.
+
+<details markdown>
+
+<summary>Example imports generated from profile-inherit</summary>
+
+```json
+  "imports": [
+      {
+        "href": "trestle://profiles/controls_delta/profile.json",
+        "include-controls": [
+          {
+            "with-ids": [
+              "ac-2"
+            ]
+          }
+        ],
+        "exclude-controls": [
+          {
+            "with-ids": [
+              "ac-1"
+            ]
+          }
+        ]
+      }
+    ]
+```
+
+</details>
+</details>
+
+<details markdown>
+
 <summary>trestle author component-generate and component-assemble</summary>
 
 The `trestle author component-generate` command takes a JSON ComponentDefinition file and creates markdown for its controls in separate directories for each of the DefinedComponents in the file.  This allows specifying the implementation response and status for each component separately in separate markdown files for a control.  In addition, the markdown captures Rules in the control that specify descriptions and parameter values that apply to the expected responses.

diff --git a/docs/tutorials/ssp_profile_catalog_authoring/ssp_profile_options.docx b/docs/tutorials/ssp_profile_catalog_authoring/ssp_profile_options.docx
diff --git a/docs/tutorials/ssp_profile_catalog_authoring/trestle_ssp_author_options.png b/docs/tutorials/ssp_profile_catalog_authoring/trestle_ssp_author_options.png