From e4208cad5ed6668e75faee1032996c67de336a25 Mon Sep 17 00:00:00 2001 From: Jennifer Power Date: Thu, 16 Nov 2023 18:26:09 -0500 Subject: [PATCH] Adds information about the OSCAL utilities to the developer docs Signed-off-by: Jennifer Power --- .../developer/05_tools_and_utilities.md | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/docs/manual/developer/05_tools_and_utilities.md b/docs/manual/developer/05_tools_and_utilities.md index b0b8359c917..143987d3fde 100644 --- a/docs/manual/developer/05_tools_and_utilities.md +++ b/docs/manual/developer/05_tools_and_utilities.md @@ -684,3 +684,55 @@ To run the test (assuming that the content is built) $ cd build $ ctest --output-on-failure -R test-no-new-global-applicable-rules ``` + +### `utils/oscal/build_cd_from_policy.py` – Build a Component Definition from a Policy + +This script builds an OSCAL Component Definition (version `1.0.4`) for an existing OSCAL profile from a policy. The script uses the +[compliance-trestle](https://ibm.github.io/compliance-trestle/) library to build the component definition. The component definition can be used with the `compliance-trestle` CLI after generation. + +Some assumption made by this script: + +- The script maps SSG statuses to valid OSCAL [statuses](https://pages.nist.gov/OSCAL-Reference/models/v1.1.1/system-security-plan/json-reference/#/system-security-plan/control-implementation/implemented-requirements/by-components/implementation-status) as follows: + + * `pending` - `alternative` + + * `not applicable`: `not-applicable` + + * `inherently met`: `implemented` + + * `documentation`: `implemented` + + * `planned`: `planned` + + * `partial`: `partial` + + * `supported`: `implemented` + + * `automated`: `implemented` + + * `manual`: `alternative` + + * `does not meet`: `alternative` + +- The script uses the "Section *letter*:" convention in the control notes to create statements under the implemented requirements. +- The script maps parameter to rules uses the `xccdf_variable` field under `template.vars` +- To determine what responses will mapped to the controls in the OSCAL profile the control id and label property from the resolved catalog is searched. + +It supports the following arguments: + - `-o`, `--output` — Path to write the cd to + - `-r`, `--root` — Root of the SSG project. Defaults to /content. + - `-v`, `--vendor-dir` — Path to the vendor directory with third party OSCAL artifacts + - `-p`, `--profile` — Main profile href, or name of the profile model in the trestle workspace + - `-pr`, `--product` — Product to build cd with + - `-c`, `--control` — Control to use as the source for control responses. To optionally filter by level, use the format :. + - `-j`, `--json` — Path to the rules_dir.json. Defaults to /content/build/rule_dirs.json. + - `-b`, `--build-config-yaml` — YAML file with information about the build configuration + - `-t`, `--component-definition-type` — Type of component definition to create. Defaults to service. Options are service or validation. + +An example of how to execute the script: + +```bash +$ ./build_product ocp4 +$ ./utils/rule_dir_json.py +$ ./utils/oscal/build_cd_from_policy.py -o build/ocp4.json -p fedramp_rev4_high -pr ocp4 -c nist_ocp4:high +```