Merge pull request #302 from mitre/delta-addons

Delta Additional Modification

src/.vuepress/theme.ts

@@ -80,6 +80,68 @@ export default hopeTheme({
       components: ["Badge", "VPCard"],
     },
 
+    // Use "mark: true" to allow pictures to be marked by #light or #dark
+    // suffix, letting them be displayed under the appropriate color mode
+    markdownImage: {
+      figure: true,
+      lazyload: true,
+      mark: true,
+      size: true,
+    },
+
+    markdownTab: {
+      codeTabs: true,
+      tabs: true,
+    },
+
+    // All features are enabled for demo, only preserve features you need here
+    mdEnhance: {
+      align: true,
+      attrs: true,
+      // install chart.js before enabling it
+      // chart: true,
+      component: true,
+      demo: true,
+      // install echarts before enabling it
+      // echarts: true,
+      // install flowchart.ts before enabling it
+      flowchart: true,
+      gfm: true,
+      include: true,
+      // install katex before enabling it
+      // katex: true,
+      // install mathjax-full before enabling it
+      // mathjax: true,
+      mark: true,
+      mermaid: true,
+      // plantuml: true,
+      playground: {
+        presets: ["ts", "vue"],
+      },
+      // install sandpack-vue3 before enabling it
+      // sandpack: true,
+      // spoiler: true,
+      stylize: [
+        {
+          matcher: "Recommended",
+          replacer: ({ tag }) => {
+            if (tag === "em")
+              return {
+                tag: "Badge",
+                attrs: { type: "tip" },
+                content: "Recommended",
+              };
+          },
+        },
+      ],
+      sub: true,
+      sup: true,
+      // tasklist: true,
+      vPre: true,
+      // install @vue/repl before enabling it
+      // vuePlayground: true,
+    },
+
     // install reveal.js before enabling it
     // revealjs: {
     //   plugins: ["highlight", "math", "search", "notes", "zoom"],

src/courses/delta/03.md

@@ -4,49 +4,51 @@ next: 04.md
 title: 3. Delta Process CLI Tools
 author: Daniel Medina, George Dias
 ---
+The [SAF CLI](https://saf-cli.mitre.org/) is a collection of libraries, tools developed by MITRE and the security community
+to streamline security automation for systems and DevOps pipelines. The delta process is one
+of the libraries provided by the SAF CLI.
 
 ## 3.1 CLI Tools
 
-The delta process consists of one or both of the following commands:
-
-1. Update Controls for Delta (`update_controls4delta`)
-2. Delta (`delta`)
+The delta process consists of either or both of the following commands:
+1. Updates Controls for Delta
+2. Delta
 
 ::: note About InSpec Profiles
-When referring to InSpec profiles, there are distinctions:
-
-- InSpec profile repository: Contains the controls, code, etc.
-- InSpec profile file: A JSON formatted file containing a profile summary, used as input for the delta process.
+When referring to InSpec Profiles, there are distinctions:
+InSpec profile repository: contains the controls, code, etc.
+InSpec profile file: JSON formatted file containing profile summary, used as input for the delta process.
 :::
 
 ### 3.2 Update Controls for Delta
 
-The `update_controls4delta` process is used to prepare profile controls from one [SRG](./02.md#glossary-of-terms) or [STIG/CIS](./02.md#glossary-of-terms) benchmark baseline to another. The controls are updated based on guidance provided by the appropriate Extensible Configuration Checklist Description Format ([XCCDF](./02.md#glossary-of-terms)).
+The `update_controls4delta` process is used to prepare profile controls from one [SRG](./02.md#glossary-of-terms) or [STIG/CIS](./02.md#glossary-of-terms) benchmark baseline to another. The controls are updated based on guidance provided by the appropriate Extendible Configuration Checklist Description Format ([XCCDF](./02.md#glossary-of-terms)).
 
-The `update_controls4delta` process may be the only command needed as it specifically updates existing controls from one baseline to another. Refer to [use cases for running delta](./04.html#use-cases-for-running-delta).
+The `update_controls4delta` process may be the only command needed as it specifically updates existing controls from one baseline to another, refer to [use cases for running delta](./04.html#use-cases-for-running-delta).
 
 The process of preparing controls from one baseline to another (baseline X to Y) consists of:
 
-1. Providing the directory where baseline X controls are located.
-2. Providing or generating an InSpec JSON formatted file containing all baseline X controls.
-    - The JSON file is generated using the [InSpec or Cinc-Auditor] JSON CLI command.
-3. Providing an XCCDF file containing the new baseline Y guidance. The file is obtained from the appropriate site.
-    - The baseline Y XCCDF lists all controls appropriate for the provided baseline. It often includes a field (legacy) indicating the control's previous name(s). The process uses this field to map old control names to the new controls.
-    - If no mapping is found, then the `delta` process must be invoked to convert the baselines ([see use cases](./04.html#use-cases-for-running-delta)).
-
-You can invoke the command as follows:
+1. The directory where baseline X controls are located is provided.
+2. An InSpec json formatted file containing all baseline X controls is provided or generated.
+    a - The json file is generated using the [inspec or cinc-auditor] json CLI command
+3. A XCCDF file containing the new baseline Y guidance is provided. The file is obtained from the appropriate site.
+    a - The baseline Y XCCDF lists all controls appropriate for the provided baseline. It also includes (most often) a field (legacy) where it indicates the control's previous name(s). The process uses this field to map old control names to the new controls.
+    b - If there is no mapping found, then the `delta` process must be invoked to convert the baselines ([see use cases](./04.html#use-cases-for-running-delta))
 
+You can invoke the command as such:
 ```sh
-saf generate update_controls4delta -X ./baseline_Y_xccdf_guidance_file.xml -J baseline_X_summary.json -c baseline_X_controls_directory
+saf generate update_controls4delta \
+-X ./baseline_Y_xccdf_guidance_file.xml \
+-J baseline_X_summary.json \
+-c baseline_X_controls_directory
 ```
 
 Additional capabilities can be obtained using the `-h or --help` flag on the `update_controls4delta` command as such:
-
 ```sh
 saf generate update_controls4delta --help
 ```
 
-Renaming of controls can be done either by guidance rules (rule ID, default) or using the group ID. When using rule ID legacy fields contained within the XCCDF are used for identifying the proper mapping for the controls.
+Renaming of controls can be done either by guidance rules (rule ID, default) or using the group ID. When using rule ID legacy fields contained within the XCCDF are used for identifying the proper mapping for the controls. 
 
 If there is no way to trace controls in baseline X to its corresponding controls in baseline Y, then `update_controls4delta` will not update any controls (no mapping).
 
@@ -60,24 +62,33 @@ The `delta` process extends the capabilities of the `update_controls4delta` proc
     b - For controls which a match is found, the describe block (code) within the old control is mapped over to the new control
 3. Detailed logging
     a - report file (.md), mapping statistics (CliProcessOutput.log)
+<br>
 
 You can invoke the command as such:
-
 ```sh
-saf generate delta -X ./baseline_Y_xccdf_guidance_file.xml -J baseline_X_summary.json -o new_baseline_Y_controls_directory -M -c baseline_X_controls_directory
+saf generate delta \
+-X ./baseline_Y_xccdf_guidance_file.xml \
+-J baseline_X_summary.json \
+-o new_baseline_Y_controls_directory \
+-M -c baseline_X_controls_directory
 ```
+<br>
 
 ::: tip Optional Fuzzy Matching Flags
 The `-M` and `-c` flags can be removed if not using fuzzy matching feature.
 :::
 
 Additional capabilities can be obtained using the `-h or --help` flag on the `delta` command as such:
-
 ```sh
 saf generate delta --help
 ```
 
 For more information on these commands, refer to the following documentation:
 
 - [update_controls4delta](https://saf-cli.mitre.org/#delta-supporting-options)
-- [saf generate delta](https://saf-cli.mitre.org/#delta)
+- [saf generate delta](https://saf-cli.mitre.org/#delta)
+<br>
+
+::: warning Delta Process Limitations
+The Delta process has been tested using DISA XCCDF STIG Benchmark Guidances only.
+:::

src/courses/delta/04.md

@@ -19,13 +19,14 @@ There are several situations that warrant the use of the delta process. These ar
 
 ### 4.1.1 Use Case 1
 
-Updated guidances sometimes modifies the control identification (ID) values of a given control. To make these modifications from baseline X to baseline Y, use the update controls process with the provided XCCDF STIG guidance file. The process checks if the new guidance changes the control numbers and updates the internal metadata if necessary.
+Updated guidances sometimes modifies the control identification (ID) values of a given control. To make these modifications from baseline X to baseline Y, use the update controls process with the provided XCCDF STIG guidance file. The process checks if the new guidance changes the control numbers and updates the internal metadata if necessary (testing code is retained).
 
 Suppose we want to update our [Windows Server 2019 inspec profile repository](https://github.com/mitre/microsoft-windows-server-2019-stig-baseline/) from [version 1 release 3](https://github.com/mitre/microsoft-windows-server-2019-stig-baseline/releases/tag/1.3.0) to version 3 release 2.
 
 #### Step 1: Collect necessary files:
 1. Download or clone the Windows Server 2019 profile repository to your system.
 2. Download the [latest STIG](https://public.cyber.mil/stigs/downloads/) place the XCCDF XML file into your working directory.
+
 ![File directory containing an inspec profile and an XCCDF XML file](../../assets/img/Delta_Class/Delta_Files_1.png)
 
 #### Step 2: Generate a profile summary
@@ -35,8 +36,11 @@ Use the `inspec json` command to generate a profile summary of the inspec profil
 
 #### Step 3: Run Update Controls
 Use the `update_controls4delta` method using the profile summary file, the STIG guidance file, and the controls directory for the inspec profile as inputs.
-```
-saf generate update_controls4delta -X ./windows-server-2019-v3r2-xccdf.xml -J ./profile.json -c ./microsoft-windows-server-2019-stig-baseline/controls
+```sh
+saf generate update_controls4delta \
+-X ./windows-server-2019-v3r2-xccdf.xml \
+-J ./profile.json \
+-c ./microsoft-windows-server-2019-stig-baseline/controls
 ```
 ![Running the Update Controls command](../../assets/img/Delta_Class/use_case_1-2.gif)
 
@@ -45,10 +49,10 @@ The output should look like this:
 ![Update Controls Output](../../assets/img/Delta_Class/use_case_1-3.png)
 
 From these results we can gather that:
-1. 31 controls were skipped, because they are not present in the STIG guidance. This indicates that these controls were deleted in the recent revision.
-2. 272 controls have had their control IDs updated. Any metadata changes have also been made to the controls as well.
-3. 0 controls were found to have the correct identification. This indicated that the STIG guidance renamed all mapped controls.
-4. 1 new control was found in the STIG guidance. It is important to note that `update_controls4delta` does not generate this control for you.
+1. Thirty-one (31) controls were skipped, because they are not present in the STIG guidance. This indicates that these controls were deleted in the recent revision.
+2. Two-hundred-seventy-two (272) controls have had their control IDs updated. Any metadata changes have also been made to the controls as well.
+3. Zero (0) controls were found to have the correct identification. This indicated that the STIG guidance renamed all mapped controls.
+4. One (1) new control was found in the STIG guidance. It is important to note that `update_controls4delta` does not generate this control for you.
 
 **Process:** Run `update_controls4delta`
 
@@ -61,26 +65,38 @@ New guidance often contains new controls that weren't previously defined. In thi
 Suppose we want to update our [RedHat Enterprise Linux 8 STIG Baseline](https://github.com/mitre/redhat-enterprise-linux-8-stig-baseline) from [Version 1 Release 14](https://github.com/mitre/redhat-enterprise-linux-8-stig-baseline/releases/tag/v1.14.1) to version 2 release 1.
 
 #### Step 1: Collect necessary files
+
 ![File directory containing an inspec profile, and XCCDF XML file, and a generated profile summary JSON](../../assets/img/Delta_Class/use_case_2_1.png)
+
 This include the profile summary JSON file generated used `cinc-auditor json redhat-enterprise-linux-8-stig-baseline > profile.json`
 
 #### **OPTIONAL**: Run update_controls4delta
 Running the update controls command on this profile can give us information on what needs to be updated:
-`saf generate update_controls4delta -X rhel_8_xccdf.xml -J profile.json -c ./redhat-enterprise-linux-8-stig-baseline/controls`
+```sh
+saf generate update_controls4delta \
+-X rhel_8_xccdf.xml \
+-J profile.json \
+-c ./redhat-enterprise-linux-8-stig-baseline/controls
+```
 
 ![update_controls4delta output](../../assets/img/Delta_Class/use_case_2-2.png)
 
 From this we can gather:
 1. No existing controls needed to be renamed in the new STIG guidance (366 controls with correct identification, 0 processed files).
-2. 9 controls were removed in the updated STIG guidance (9 skipped files).
-3. 1 new control was found in the updated STIG guidance. 
+2. Nine (9) controls were removed in the updated STIG guidance (9 skipped files).
+3. One (1) new control was found in the updated STIG guidance. 
 
 From this output, we know that the Delta command needs to be run, because Delta is able to generate files for new controls and make any changes needed to the other controls.
 
 #### Step 2: Run Delta
 
 Use the `delta` command to perform a delta on the profile and the STIG guidance file:
-`saf generate delta -X ./rhel_8_V2R1_xccdf.xml -J ./profile.json -r ./report.md -o ./redhat-8-updated/`
+```sh
+saf generate delta \
+-X ./rhel_8_V2R1_xccdf.xml \
+-J ./profile.json \
+-r ./report.md -o ./redhat-8-updated/
+```
 In this case, we will be outputting a report file to `report.md` and the updated inspec profile to the `./redhat-8-updated/` directory.
 
 You should receive the following output:
@@ -89,10 +105,13 @@ You should receive the following output:
 The `["+","SV-268322"]` indicates that a new control was created with the ID SV-258322.
 
 After running the command, you should see the following:
+
 ![Generated files and folders from delta](../../assets/img/Delta_Class/use_case_2-4.png)
 
 1. `redhat-8-updated` directory: A folder container the updated inspec profile.
+
     ![Updated profile output directory](../../assets/img/Delta_Class/use_case_2-5.png)
+
     a. A `controls` directory containing all of the updated and new controls in the STIG guidance file. This does NOT contain removed controls so no further modifications need to be done.
     b. A delta.json file containing a JSON formatted summary of the delta process.
 2. `report.md`: Markdown report containin formatted version of delta.json summary results.
@@ -114,7 +133,13 @@ In this use case, we will be mapping the Windows Server 2019 STIG profile using
 #### Step 2: Run the delta command with fuzzy matching
 
 To enable fuzzy matching, use the `-M` flag and specify the controls directory using the `-c` flag:
-`saf generate delta -X ./windows-server-2022-v2r2-xccdf.xml -J ./profile.json -r ./report.md -o ./windows-server-2022-stig-baseline -M -c ./microsoft-windows-server-2019-stig-baseline/controls`
+```sh
+saf generate delta \
+-X ./windows-server-2022-v2r2-xccdf.xml \
+-J ./profile.json -r ./report.md \
+-o ./windows-server-2022-stig-baseline \
+-M -c ./microsoft-windows-server-2019-stig-baseline/controls
+```
 
 The output is long, but what's important is the results and statistics section:
 ![Delta fuzzy matching command output](../../assets/img/Delta_Class/use_case_3-2.png)

src/courses/delta/06.md

@@ -180,8 +180,8 @@ The current available commands for testing are:
 ```sh
   bundle exec rake [inspec or cinc-auditor]:check # validate the inspec profile
   bundle exec rake lint                           # Run RuboCop
-  bundle exec rake lint:autocorrect               # Autocorrect RuboCop offenses (only when it's safe)
-  bundle exec rake lint:autocorrect_all           # Autocorrect RuboCop offenses (safe and unsafe)
+  bundle exec rake lint:auto_correct               # Autocorrect RuboCop offenses (only when it's safe)
+  bundle exec rake lint:auto_correct_all           # Autocorrect RuboCop offenses (safe and unsafe)
   bundle exec rake pre_commit_checks              # Ensure the controls are ready to be committed into the repo
 ```
 

src/courses/delta/07.md

@@ -8,11 +8,13 @@ author: Daniel Medina, George Dias
 
 ### 7.1.1 Update Controls Process
 
-![Update Controls Process Diagram](../../assets/img/update_controls4delta_diagram.png)
+![Update Controls Process Diagram](../../assets/img/update_controls4delta_diagram_light.png#light)
+![Update Controls Process Diagram](../../assets/img/update_controls4delta_diagram_dark.png#dark)
 
 ### 7.1.2 Delta Process
 
-![Delta Workflow Process Diagram](../../assets/img/delta_diagram.png)
+![Delta Workflow Process Diagram](../../assets/img/delta_diagram_light.png#light)
+![Delta Workflow Process Diagram](../../assets/img/delta_diagram_dark.png#dark)
 
 ### 7.2 Scope of Changes by Delta
 

src/courses/delta/README.md

@@ -19,3 +19,12 @@ By the end of this class, you should be able to:
 - Use the delta fuzzy matching system to map controls between two profiles
 - Identify and review delta process history with generated logs and artifacts
 - Format InSpec profile controls appropriately before and/or after executing delta commands
+
+### 1.3 Delta Demystify
+Cyber security, the practice of protecting computer systems, networks, and data is an ongoing effort
+that demands vulnerability vigilance (current and future) trough continuous monitoring and notification.
+
+To effectively established an ongoing monitoring process, we need to know what to check for, and
+update the content being checked as vulnerabilities are identified. The MITRE training class [Beginner Security Automation Developer Class](../beginner/) provides an insight on how to use InSpec Profiles (a collection of automated tests) to conduct testes based on some security guidances.
+
+As long as the testes are based on valid security guidances all is well, but the moment the security guidances change, the tests become obsolete and require new tests or existing tests to be updated, that is where the `delta` process comes into the rescue.