Merge pull request #49 from mitre/userClassUpdates10-2023

Sweep through user class for updates
mitre · Nov 1, 2023 · 03f0aa6 · 03f0aa6
2 parents 033e307 + b1f40aa
commit 03f0aa6
Show file tree

Hide file tree

Showing 25 changed files with 100 additions and 58 deletions.
diff --git a/assets/img/Heimdall_Click_ComparisonView.png b/assets/img/Heimdall_Click_ComparisonView.png
diff --git a/assets/img/Heimdall_Filter_Failure.png b/assets/img/Heimdall_Filter_Failure.png
diff --git a/assets/img/Heimdall_Inputs_NGINXDefault.png b/assets/img/Heimdall_Inputs_NGINXDefault.png
diff --git a/assets/img/Heimdall_NGINX_Inputs.png b/assets/img/Heimdall_NGINX_Inputs.png
diff --git a/assets/img/Heimdall_NGINX_Vanilla_Default_Inputs.png b/assets/img/Heimdall_NGINX_Vanilla_Default_Inputs.png
diff --git a/assets/img/Heimdall_NGINX_Vanilla_With_Inputs.png b/assets/img/Heimdall_NGINX_Vanilla_With_Inputs.png
diff --git a/assets/img/Heimdall_NotReviewed_Filter.png b/assets/img/Heimdall_NotReviewed_Filter.png
diff --git a/assets/img/Heimdall_Select_Menu.png b/assets/img/Heimdall_Select_Menu.png
diff --git a/assets/img/Heimdall_TreeMap_Failures.png b/assets/img/Heimdall_TreeMap_Failures.png
diff --git a/assets/img/SAF-CLI.png b/assets/img/SAF-CLI.png
diff --git a/assets/img/SAF_Goals.png b/assets/img/SAF_Goals.png
diff --git a/assets/img/SAF_Home.png b/assets/img/SAF_Home.png
diff --git a/assets/img/SAF_Site_Harden.png b/assets/img/SAF_Site_Harden.png
diff --git a/assets/img/SAF_Site_Validate.png b/assets/img/SAF_Site_Validate.png
diff --git a/courses/user/02.md b/courses/user/02.md
@@ -5,24 +5,28 @@ author: Aaron Lippold
 headerDepth: 3
 ---
 
-## 2. Traditional Security Validation Lifecycle
-
-### 2.1 Consider your current status
-- How frequently does the software get assessed?
-- How long does it takes to assess?
-- What is the biggest struggle for assessment?
-- What would be your dream for changing the process you use to do security assessments?
-- What are you hoping to get out of this course today?
-
-### 2.2 The goals of the SAF
-#### 1. Accelerate ATO
+## 2.1 The Goal of the SAF
+### 1. Accelerate ATO
 - Automate tailored security configuration testing in every build
 - Aggregate all security assessment results in a single dashboard to show security status
-#### 2. Build Security In
+### 2. Establish Security Requirements
+- Align security tests to requirements
+- Write STIG-ready content for software components
+### 3. Build Security In
 - Automate security control assessment aligned to common standards
 - Implement security requirements within existing DevSecOps pipelines
-#### 3. Continuous Assessment
+### 4. Assess/Monitor Vulnerabilities
 - Visualize results of all ongoing assessments to understand risk over time
 - Enable ongoing or continuous authorization to operate (cATO)
 
 ![Alt text](../../assets/img/SAF_Goals.png)
+
+## 2.2 The Road to Security Automation
+
+As you can see from the picture below, the process for developing automated security tests starts with requirements documents like SRGs, STIGs or CIS Benchmark that are written in regular, human language and then implemented as code. We need that code to record test results in a standardized format so that we can easily export our security data somewhere people can use it to make decisions (like the Heimdall visualization app).
+
+This challenge is what the [MITRE Security Automation Framework](https://saf.mitre.org) or MITRE SAF was developed to simplify -- to make the journey from a Requirement Document to an automated test profile and back again a little easier to navigate.
+
+
+
+![Alt text](../../assets/img/saf-lifecycle.png)
diff --git a/courses/user/03.md b/courses/user/03.md
@@ -16,7 +16,7 @@ The main pillars are
 - Normailze
 - Visualize
 
-We help teams plan what guidance will help them keep their software secure. We also provide libraries and tools for automatically hardening and validating software based on that guidance, normalize other security data, and visualize all the information to properly inform teams of risk and vulnerabilities. 
+The SAF helps teams plan what guidance will help them keep their software secure. It also provide libraries and tools for automatically hardening and validating software based on that guidance, normalize other security data, and visualize all the information to properly inform teams of risk and vulnerabilities. 
 :::
 
 ::: details 2. Is SAF a tool? Why or why not?
@@ -25,7 +25,7 @@ Nope!
 SAF, the Security Automation Framework, is a Framework and uses a COLLECTION of tools, techniques, applications, and libraries to streamline security automation. Since teams operate in different environments with different components, not everyone's security journey will look the same.
 
 
-Among the provided tools, some notable tools within the Security Automation Framework are Vulcan, the SAF CLI, and Heimdall.
+Some notable tools within the Security Automation Framework are Vulcan, the SAF CLI, and Heimdall.
 ![Alt text](../../assets/img/SAF_Capabilities_SAF_Tools.png)
 :::
 
@@ -36,7 +36,7 @@ HDF data can be easily visualized in [Heimdall](https://heimdall-lite.mitre.org/
 :::
 
 ::: details 4. Which of the following is NOT a tool that SAF provides to help in the security automation process? (eMASS Client, InSpec, SAF CLI, Heimdall, Vulcan)
-InSpec is more than a tool - it is a language developed by Chef that MITRE and other security community members use to write InSpec profiles which are sets of controls for automating security validation. You can view InSpec profiles on the [validation section of the SAF site](https://saf.mitre.org/#/validate). You can see more information on how to run InSpec profiles on the [getting started section](https://saf.mitre.org/#/getstarted). The available tools are found under the "How We Support It" section of the [site](https://saf.mitre.org/).
+InSpec is more than a tool - it is a language developed by Chef that MITRE and other security community members use to write InSpec profiles which are sets of controls for automating security validation. You can view InSpec profiles on the [validation section of the SAF site](https://saf.mitre.org/#/validate). You can see more information on how to run InSpec profiles on the [getting started section](https://saf.mitre.org/#/getstarted). The available tools are found under the "The MITRE SAF© Open Source Toolset" section of the [site](https://saf.mitre.org/).
 :::
 
 <!-- ### 2.1. Identifying your stack and checking for a profile using the saf site

diff --git a/courses/user/05.md b/courses/user/05.md
@@ -24,7 +24,7 @@ The idea of using Test Driven Development (in other words, having the code drive
 
 This process starts with a FAILING test. Then, the minimal amount of change required is done to fix the code so that the test passes. Once the test passes, the code can be refactored to be cleaner, more readable, etc. This is a cycle, and returns to the top to create a new failing test. As development continues, all tests should be run to confirm that all tests still pass! These tests can be put in an automated suite to validate the code set whenever there are changes overall.
 
-The SAF team values this methodology and helps teams implement security compliance tests using InSpec so they can understand the state of the system and the goal state of a secured system, using automated tests to get this information easier, quicker, and more often!
+The SAF team values this methodology and helps teams implement security compliance tests using InSpec so they can understand the state of the system and the goal state of a secured system, using automated tests to get this information easier, quicker, and more often.
 ![Alt text](../../assets/img/TestDrivenDevelopment.png)
 :::
 
@@ -33,6 +33,11 @@ The SAF team values this methodology and helps teams implement security complian
 
 The SAF uses InSpec profiles to test software components against a security baseline. These automated tests produce data showing what security controls passed or failed, or were skipped or not reviewed and gives the reason and more information to fix it if not passing.
 
+::: note What is an InSpec profile?
+The term __InSpec profile__ refers a collection of security tests written in InSpec (the programming language). 
+To learn more, look at the Beginner Developer's section on [What is an InSpec Profile](../beginner/02.md/#what-is-an-inspec-profile) and test your understanding in [this comprehension check](../beginner/02.md/#check-in).
+:::
+
 ## 5.2 Examples of InSpec profiles
 Let's review the READMEs for each profile for more information and specific run instructions. The README is the first document in the GitHub repository, and contains the following information:
 1. The name of the profile
@@ -42,14 +47,13 @@ Let's review the READMEs for each profile for more information and specific run
 
 ### 5.2.1 RHEL8 baseline profile
 
-Let's take the [RHEL8 baseline profile](https://github.com/CMSgov/redhat-enterprise-linux-8-stig-baseline) as an example  
-![Alt text](../../assets/img/SAF_Rhel8.png)
+Let's take the [RHEL8 baseline profile](https://github.com/CMSgov/redhat-enterprise-linux-8-stig-baseline) as an example. You can find this InSpec profile at the provided link or through the [validation library of the SAF site](https://saf.mitre.org/libs/validate).  
 
 ![Alt text](../../assets/img/Github_Rhel8.png)
 
 ### 5.2.2 NGINX baseline profile
 
-Let's take the [NGINX baseline profile](https://github.com/mitre/nginx-stigready-baseline) as an example  
-![Alt text](../../assets/img/SAF_nginx.png)
+Let's take the [NGINX baseline profile](https://github.com/mitre/nginx-stigready-baseline) as an example. You can find this InSpec profile at the provided link or through the [validation library of the SAF site](https://saf.mitre.org/libs/validate).  
+ 
 
 ![Alt text](../../assets/img/Github_nginx.png)
diff --git a/courses/user/06.md b/courses/user/06.md
@@ -48,6 +48,29 @@ inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx
 ```
 
 In the above example, we are testing an NGINX server. We get the InSpec profile (all of the tests) from GitHub by stating `https://github.com/mitre/nginx-stigready-baseline`. We use the NGINX target that is running via docker in our Codespace environment by stating `docker://nginx`, we do not put any extra flags in this example, and lastly, we only report the results to the terminal (in other words, cli output). Later we will refine this command and talk through it in more detail.
+
+_Note: The first time you run InSpec, it will likely ask you to accept Chef's license like this:_
+
+```sh
++---------------------------------------------+
+            Chef License Acceptance
+
+Before you can continue, 1 product license
+must be accepted. View the license at
+https://www.chef.io/end-user-license-agreement/
+
+License that need accepting:
+  * Chef InSpec
+
+Do you accept the 1 product license (yes/no)?
+
+>
+```
+
+You can type `yes` and press enter. This will only happen one time.
+
+If you are using InSpec in a pipeline, you can silently accept the license. Reference [Chef's documentation](https://docs.chef.io/chef_license_accept/) for more information.
+
 :::
 
 ::: details Transports - Advanced Examples
@@ -81,6 +104,6 @@ Note that if you do not provide one of the required flags in the InSpec exec com
 :::
 
 ### 6.3 How to Deploy InSpec
-It is intended and recommended that InSpec be installed on a "runner" host (such as a DevOps orchestration server, an administrative management system, or a developer's workstation/laptop) and run against the target remotely. However, InSpec may be deployed in [various ways](https://saf.mitre.org/#/faq#runners) depending on the needs of the user:
+It is intended and recommended that InSpec be installed on a "runner" host (such as a DevOps orchestration server, an administrative management system, or a developer's workstation/laptop) and run against the target remotely. However, InSpec may be deployed in [various ways](https://saf.mitre.org/faq/7) depending on the needs of the user:
 
 ![Alt text](../../assets/img/runner.png)
diff --git a/courses/user/07.md b/courses/user/07.md
@@ -12,22 +12,26 @@ Every InSpec profile on the SAF site is written to comply with some security gui
 To accomodate for these kinds of differences, InSpec profiles utilize inputs. In the previous section, we ran the InSpec profile on the NGINX component without specifying any inputs. This means that it just used the defaults. Now, let's review these variables and decide which inputs we want to change for our environment.
 
 ::: tip Best Practice
-It is best practice to always run profiles with inputs so that the profile is properly tailored to your environment!
+It is best practice to always run profiles with inputs so that the profile is properly tailored to your environment.
 :::
 
 ## 7.1 Profile Inputs (see `inspec.yml` file)
 
 This profile uses InSpec Inputs to make the tests more flexible. You are able to provide inputs at runtime either via the cli or via YAML files to help the profile work best in your deployment.
 
-#### **_Do not change the inputs in the `inspec.yml` file_**
+::: danger 
+**DO NOT** change the inputs in the `inspec.yml` file. This is where the variables and their defaults are defined.
 
-The `inputs` configured in the `inspec.yml` file are **profile definition and defaults for the profile** and not for the user. InSpec provides two ways to adjust the profile's inputs at run-time that do not require modifiying `inspec.yml` itself. This is because automated profiles like this one are frequently run from a script, inside a pipeline or some kind of task scheduler. Such automation usually works by running the profile directly from its source (i.e. this repository), which means the runner will not have access to the `inspec.yml`.
+**DO** create a separate file (often named `inputs.yml`) or pass values via the command line to overwrite default values to tailor the profile.
+:::
+
+The `inputs` configured in the `inspec.yml` file are **profile definition and defaults for the profile** and not for the user. Automated InSpec scans are frequently run from a script, inside a pipeline or some kind of task scheduler where the runner will often not have access to the `inspec.yml`. However, those scripts or pipelines can easily pass an inputs file or command line arguments to modify the default values defined in the `inspec.yml` file.
 
 To tailor the tested values for your deployment or organizationally defined values, **_you may update the inputs_**.
 
 More information about InSpec inputs can be found in the [InSpec Inputs Documentation](https://docs.chef.io/inspec/inputs/).
 
-## 7.2 Using an --input-file to tailor specifics
+## 7.2 Use an --input-file to tailor an InSpec profile
 
 For the NGINX example, we are going to add the following inputs. Make a new file called `inputs.yml` in your lab environment:
 1. Right click near the file list on the left side
@@ -52,6 +56,8 @@ In your codespaces, it should look like this:
 Start by checking the README on the GitHub repository for that InSpec profile. Most of the profiles have a "Tailoring to Your Environment" section that leads you through what variables are available as inputs. 
 
 To determine the value itself, you should think about the environment, talk to your assessor, and explore the target to see if you can find the necessary information.
+
+If the profile does not have a "Tailoring to Your Environment" section in their README, then you can reference the `inspec.yml` file to see what inputs are defined and available and what their default values are. However, remember not to modify the `inspec.yml` file itself.
 :::
 
 ::: info What is the difference between tailoring an InSpec profile with inputs vs. overlays?

diff --git a/courses/user/08.md b/courses/user/08.md
@@ -42,10 +42,7 @@ Enter the command from the previous step in your terminal and press enter. It wi
 You should see output similar to that below. The whole profile should execute in only a couple minutes.
 ```sh
 inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx --input-file inputs.yml --reporter cli json:./results/nginx_vanilla_results.json
-  [2022-09-22T17:30:11+00:00] WARN: URL target https://github.com/mitre/nginx-stigready-baseline transformed to https://github.com/mitre/nginx-stigready-baseline/archive/master.tar.gz. Consider using the git fetcher
-
-  Top level ::CompositeIO is deprecated, require 'multipart/post' and use `Multipart::Post::CompositeReadIO` instead!
-  Top level ::Parts is deprecated, require 'multipart/post' and use `Multipart::Post::Parts` instead!
+[2023-11-01T02:41:29+00:00] WARN: URL target https://github.com/mitre/nginx-stigready-baseline transformed to https://github.com/mitre/nginx-stigready-baseline/archive/master.tar.gz. Consider using the git fetcher
   ...
      ×  is expected not to be nil
      expected: not nil
@@ -60,8 +57,8 @@ inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx
   ✔  V-56033: The web server must install security-relevant software updates within
     the configured time period directed by an authoritative source (e.g., IAVM,
     CTOs, DTMs, and STIGs).
-     ✔  NGINX version v1.23.1 installed is not more then one patch level behind v1.23.0 is expected to cmp >= "1.23.0"
-     ✔  NGINX version v1.23.1 installed is greater then or equal to the organization approved version v1.21.5 is expected to cmp >= "1.21.5"
+     ✔  NGINX version v1.25.3 installed is not more then one patch level behind v1.25.2 is expected to cmp >= "1.25.2"
+     ✔  NGINX version v1.25.3 installed is greater then or equal to the organization approved version v1.23.1 is expected to cmp >= "1.23.1"
   ✔  V-56035: The NGINX web server must display a default hosted application web page, not
     a directory listing, when a requested web page cannot be found.
      ✔  The root directory /usr/share/nginx/html should include the default index.html file.
@@ -71,8 +68,8 @@ inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx
      ↺  This test is NA because the ssl_ciphers directive has not been configured.
 
 
-Profile Summary: 29 successful controls, 24 control failures, 36 controls skipped
-Test Summary: 131 successful, 89 failures, 56 skipped
+Profile Summary: 27 successful controls, 26 control failures, 36 controls skipped
+Test Summary: 137 successful, 91 failures, 55 skipped
 ```
 
 You see that many of the tests pass, while others fail and may require investigation.

diff --git a/courses/user/09.md b/courses/user/09.md
@@ -24,14 +24,14 @@ This will allow you to view the InSpec results in the Heimdall viewer.
 
 Your visualization should look similar to the following:
 
-![Alt text](../../assets/img/Heimdall_NGINX_Vanilla_Default_Inputs.png)
+![Alt text](../../assets/img/Heimdall_NGINX_Vanilla_With_Inputs.png)
 
 ### 9.3 Explore Heimdall
 
 Heimdall can allow you to see a lot of different information based on the available data. See if you can find the following information from your uploaded results!
 
 ::: details What is the overall compliance level?
-In this example, the overall compliance is 50%. As you can see, the compliance formula is written in the GUI. This is the number of passed controls divided by the total passed, failed, not reviewed, and errors. Not Applicable controls are not included in the overall compliance total.
+In this example, the overall compliance is 46.77%. As you can see, the compliance formula is written in the GUI. This is the number of passed controls divided by the total passed, failed, not reviewed, and errors. Not Applicable controls are not included in the overall compliance total.
 :::
 
 ::: details Can you filter to just the failures?
@@ -64,5 +64,5 @@ To protect the integrity of the data that is being captured in the
 
 ::: details How can you see information about the results file, such as the run date or the platform this scan was run on?
 You can view file information by clicking "File Info" on the top of the application where the file name is listed. This can show you things like the platform that this scan was completed on, how long it took, the date of the scan, and more. If you click on the "Inputs" tab, this will show what values were used for different variables in the profile's automated tests. This will show the inputs that we specified in the inputs file, and the default values for any variables that we did not put in the inputs file.
-![Alt text](../../assets/img/Heimdall_Inputs_NGINXDefault.png)
+![Alt text](../../assets/img/Heimdall_NGINX_Inputs.png)
 :::