Merge pull request #1399 from IBM/develop

chore: Trestle release
oscal-compass · Jun 26, 2023 · c3c28de · c3c28de
2 parents 0aa4930 + 9380cc8
commit c3c28de
Show file tree

Hide file tree

Showing 36 changed files with 2,448 additions and 90 deletions.
diff --git a/.github/workflows/python-test.yml b/.github/workflows/python-test.yml
@@ -92,14 +92,27 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: [3.8, 3.9]
         include:
         - os: ubuntu-latest
           path: ~/.cache/pip
         - os: macos-latest
           path: ~/Library/Caches/pip
         - os: windows-latest
           path: ~\AppData\Local\pip\Cache
-        python-version: [3.7, 3.8, 3.9]
+        # optional 3.7 test
+        - os: ubuntu-latest
+          path: ~/.cache/pip
+          python-version: 3.7
+        # optional 3.7 test
+        - os: macos-latest
+          path: ~/Library/Caches/pip
+          python-version: 3.7.16
+        # optional 3.7 test
+        - os: windows-latest
+          path: ~\AppData\Local\pip\Cache
+          python-version: 3.7
+
     steps:
     - name: Don't mess with line endings
       run: |
@@ -122,16 +135,16 @@ jobs:
       run: |
         make develop
     - name: Pytest Fast
-      if: ${{ !(matrix.os == 'ubuntu-latest' && matrix.python-version == '3.7') }}
+      if: ${{ !(matrix.os == 'ubuntu-latest' && matrix.python-version == '3.8') }}
       run: |
         make test
     - name: Pytest Cov
-      if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.7' }}
+      if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.8' }}
       run: |
         make test-cov
 
     - name: Upload artifact
-      if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.7' }}
+      if: ${{ matrix.os == 'ubuntu-latest' && matrix.python-version == '3.8' }}
       uses: actions/upload-artifact@v2
       with:
         name: coverage
@@ -154,7 +167,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v2
       with:
-        python-version: 3.7
+        python-version: 3.8
     - uses: actions/cache@v2
       with:
         path: ~/.cache/pip
@@ -178,7 +191,7 @@ jobs:
           -Dsonar.python.coverage.reportPaths=coverage.xml
           -Dsonar.tests=tests/
           -Dsonar.sources=trestle/ 
-          -Dsonar.python.version=3.7
+          -Dsonar.python.version=3.8
           -Dsonar.projectKey=compliance-trestle
           -Dsonar.organization=compliance-trestle
           -Dsonar.cpd.exclusions=trestle/oscal/*.py

diff --git a/MAINTAINERS.md b/MAINTAINERS.md
@@ -1,23 +1,15 @@
 Trestle was designed and open sourced by a team based at [IBM Research](https://www.research.ibm.com/) and others around the world.  The list includes:
 
-Christopher Butler - [butler54](https://github.com/butler54)
-
-Bruno Marques - [brunomarq](https://github.com/brunomarq)
+Alejandro Jose Leiva Palomo [AleJo2995](https://github.com/AleJo2995)
 
-Lenin Mehedy - [leninmehedy](https://github.com/leninmehedy)
+Christopher Butler [butler54](https://github.com/butler54)
 
-Simon Metson - [drsm79](https://github.com/drsm79)
+Lou Degenaro [degenaro](https://github.com/degenaro)
 
-Frank Suits - [fsuits](https://github.com/fsuits)
+Frank Suits [fsuits](https://github.com/fsuits)
 
-Jeff Tan - [jeffdmgit](https://github.com/jeffdmgit)
+Jennifer Power [jpower432](https://github.com/jpower432)
 
-Nebula Alam - [aNebula](https://github.com/aNebula)
+Manjiree Gadgil [mrgadgil](https://github.com/mrgadgil)
 
 Vikas Agarwal [vikas-agarwal76](https://github.com/vikas-agarwal76)
-
-Lou Degenaro [degenaro](https://github.com/degenaro)
-
-Ekaterina Nikonova [enikonovad](https://github.com/enikonovad)
-
-Alejandro Jose Leiva Palomo [AleJo2995](https://github.com/AleJo2995)
diff --git a/README.md b/README.md
@@ -88,23 +88,33 @@ Compliance trestle is currently stable and is based on NIST OSCAL version 1.0.4,
 ## Community call
 
 We would like to share development in progress for compliance trestle, coming soon and get feedback from community on what features would they like to see in compliance trestle.\
-The community call will happen every 2 week(s) on Tuesday at 10am EST.\
+The community call will happen every 2 week(s) on Tuesday at 10.00am EST.\
 Meeting information:
 
 ```
+You have been invited to Attend at the following event :
 Compliance Trestle Community Call
-Hosted by MANJIREE GADGIL
-
-https://ibm.webex.com/ibm/j.php?MTID=m46740e85f87f290d0848c6941c489b0a
-Tuesday, May 16, 2023 10:30 AM | 30 minutes | (UTC-04:00) Eastern Time (US & Canada)
-Occurs every 2 week(s) on Tuesday effective 5/16/2023 from 10:30 AM to 11:00 AM, (UTC-04:00) Eastern Time (US & Canada)
-
-Join by phone
-1-844-531-0958 United States Toll Free
-1-669-234-1178 United States Toll
-1-669-234-1178 United States Toll
-Host access code 979 191 85
-Attendee access code 979 379 85
+Every 2nd week on Tuesday; from June 27th, 2023 at 10:00 am EST for 0.5 hour
+
+To join, select from the following options: 
+
+1) Web Browser
+    a) https://primetime.bluejeans.com/a2m/live-event/dcwuavtj
+
+2) Laptop paired with room system (Best Experience)
+    a) Dial: meet@bjn.vc or 104.238.247.247 in the room system.
+    b) Go to https://primetime.bluejeans.com/a2m/live-event/dcwuavtj/room-system/
+    c) Enter the pairing code displayed on your room system's screen into your browser.
+
+3) Room System
+    a) Dial: meet@bjn.vc or 104.238.247.247 in the room system.
+    b) Enter Meeting ID : 499830564  and Passcode :  8231
+
+4) Joining via a mobile device?
+    a) Open this link : https://primetime.bluejeans.com/a2m/live-event/dcwuavtj 
+    b) Download the app if you don’t have it already 
+    c) Enter event ID : dcwuavtj
+
 ```
 
 ## Contributing to Trestle

diff --git a/docs/api_reference/trestle.tasks.oscal_catalog_to_csv.md b/docs/api_reference/trestle.tasks.oscal_catalog_to_csv.md
@@ -0,0 +1,2 @@
+::: trestle.tasks.oscal_catalog_to_csv
+handler: python
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:
@@ -613,15 +628,17 @@ CLI evocation:
 
 > trestle author ssp-filter
 
-The `ssp-filter` sub-command takes a given SSP and filters its contents based on a given profile, list of components, and/or control implementation status.
+The `ssp-filter` sub-command takes a given SSP and filters its contents based on a given profile, list of components, control implementation status and/or control origination.
 
 If filtering by profile, the SSP is assumed to contain a superset of controls needed by the profile, and the filter operation generates a new SSP with just the controls needed by that profile.  If the profile references a control not in the SSP, the routine fails with an error.
 
-If filtering by components, a colon-delimited list of components should be provided, with `This system` as the default name for the overall required component for the entire system.  Case and spaces are ignored in the component names, so the names could be specified as `--components "this system: my component"`.  The resulting, filtered ssp will have updated implementated requirements with filtered by_components on each requirement, and filtered by_components on each statement.
+If filtering by components, a colon-delimited list of components should be provided, with `This system` as the default name for the overall required component for the entire system.  Case and spaces are ignored in the component names, so the names could be specified as `--components "this system: my component"`.  The resulting, filtered ssp will have updated implemented requirements with filtered by_components on each requirement, and filtered by_components on each statement.
+
+If filtering by control implementation status, a comma-delimited list of implementation status values should be provided. These values must comply with the OSCAL SSP format references's allowed values, which are as follows: implemented, partial, planned, alternative, and not-applicable.
 
-If filtering by control implementation status, a comma-demilited list of implementation status values should be provided. These values must comply with the OSCAL SSP format references's allowed values, which are as follows: implemented, partial, planned, alternative, and not-applicable.
+If filtering by control origination, a comma-delimited list of control origination values should be provided. These values must comply with the OSCAL SSP format references's allowed values for the control origination property, which are as follows: system-specific, inherited, organization, customer-configured, and customer-provided.
 
-You may filter by a combination of a profile, list of component names, and implementation statuses.
+You may filter by a combination of a profile, list of component names, implementation statuses, and control origination values.
 
 As with the other related author commands, if an existing destination file already exists, it is not updated if no changes would be made.
 

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.
@@ -1010,13 +1056,13 @@ If you do not specify component-defintions during assembly, the markdown should
 
 <summary>trestle author ssp-filter</summary>
 
-Once you have an SSP in the trestle directory you can filter its contents with a profile, list of components, or list of implementation status values by using the command `trestle author ssp-filter`.  The SSP is assumed to contain a superset of the controls needed by the profile if a profile is specified, and the filter operation will generate a new SSP with only those controls needed by the profile.  If a list of component names is provided, only the specified components will appear in the system implementation of the ssp. If a list of implementation statuses is provided, controls with implementations including those statuses will appear in the control implementation of the ssp.
+Once you have an SSP in the trestle directory you can filter its contents with a profile, list of components, list of implementation statuses, or list control origination values by using the command `trestle author ssp-filter`.  The SSP is assumed to contain a superset of the controls needed by the profile if a profile is specified, and the filter operation will generate a new SSP with only those controls needed by the profile.  If a list of component names is provided, only the specified components will appear in the system implementation of the ssp. If a list of implementation statuses is provided, controls with implementations including those statuses will appear in the control implementation of the ssp. Similarly, if a list of control origination values is provided, implemented requirements with a control origination property value included in the provided values will appear in the control implementation of the ssp.
 
 The filter command is invoked as:
 
-`trestle author ssp-filter --name my_ssp --profile my_profile --components comp_a:comp_b --implementation-status "planned,partial" --output my_culled_ssp`
+`trestle author ssp-filter --name my_ssp --profile my_profile --components comp_a:comp_b --implementation-status "planned,partial" --control-origination "customer-configured" --output my_culled_ssp`
 
-The SSP must be present in the trestle workspace and, if filtering by profile, that profile must also be in the trestle workspace. This command will generate a new SSP in the workspace. If the profile makes reference to a control not in the SSP then the routine will fail with an error message.  Similarly, if one of the components is not present in the ssp the routine will also fail. The implementation statuses must be one of the allowed values as defined in the OSCAL SSP JSON format reference. Those include the following: implemented, partial, planned, alternative, and not-applicable. If an invalid value is provided, an error is returned.
+The SSP must be present in the trestle workspace and, if filtering by profile, that profile must also be in the trestle workspace. This command will generate a new SSP in the workspace. If the profile makes reference to a control not in the SSP then the routine will fail with an error message.  Similarly, if one of the components is not present in the ssp the routine will also fail. The implementation statuses must be one of the allowed values as defined in the OSCAL SSP JSON format reference. Those include the following: implemented, partial, planned, alternative, and not-applicable. If an invalid value is provided, an error is returned. The control origination values also must be one of the allowed values as defined in the OSCAL SSP JSON format reference. Those include the following: system-specific, inherited, customer-configured, customer-provided, and organization. If an invalid value is provided, an error is returned.
 
 </details>
 

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
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -167,6 +167,7 @@ nav:
       - csv_to_oscal_cd: api_reference/trestle.tasks.csv_to_oscal_cd.md
       - ocp4_cis_profile_to_oscal_catalog: api_reference/trestle.tasks.ocp4_cis_profile_to_oscal_catalog.md
       - ocp4_cis_profile_to_oscal_cd: api_reference/trestle.tasks.ocp4_cis_profile_to_oscal_cd.md
+      - oscal_catalog_to_csv: api_reference/trestle.tasks.oscal_catalog_to_csv.md
       - oscal_profile_to_osco_profile: api_reference/trestle.tasks.oscal_profile_to_osco_profile.md
       - osco_result_to_oscal_ar: api_reference/trestle.tasks.osco_result_to_oscal_ar.md
       - tanium_result_to_oscal_ar: api_reference/trestle.tasks.tanium_result_to_oscal_ar.md