From 0245cf03e4ff6b54f1cdd42921cd57cfc0df5ed3 Mon Sep 17 00:00:00 2001 From: Shivani Karikar Date: Sun, 1 Dec 2024 23:04:58 -0500 Subject: [PATCH] User Class Updates (#259) * Added bullet numbering and made semantic changes Signed-off-by: Shivani Karikar * Fixed typos Signed-off-by: Shivani Karikar * Corrected link and fixed typos Signed-off-by: Shivani Karikar * Added bullet number Signed-off-by: Shivani Karikar * Fixed links and typos Signed-off-by: Shivani Karikar * Testing tip Signed-off-by: Shivani Karikar * Testing tip again Signed-off-by: Shivani Karikar * Addressed comments and fixed link Signed-off-by: Shivani Karikar * copilot suggestions - stage 1 Signed-off-by: Aaron Lippold * Enhancements Signed-off-by: Shivani Karikar * copilot suggestions - 8 Signed-off-by: Aaron Lippold * copilot suggestions - 9 Signed-off-by: Aaron Lippold * Corrected flag and acronyms Signed-off-by: Shivani Karikar * Standardized code blocks Signed-off-by: Shivani Karikar * Enhancements Signed-off-by: Shivani Karikar * fixed section numbering and section 6.3 Signed-off-by: Aaron Lippold * Added link + Grammar fixes Signed-off-by: Shivani Karikar * fixed more numbering issues 8 - 16 Signed-off-by: Aaron Lippold * Grammar fixes Signed-off-by: Shivani Karikar * typo in section title Signed-off-by: Will * small fix to 15 Signed-off-by: Aaron Lippold * wordsmithing in section 6 Signed-off-by: Will * Bump the vuepress group with 2 updates Bumps the vuepress group with 2 updates: [@vuepress/plugin-markdown-image](https://github.com/vuepress/ecosystem/tree/HEAD/plugins/plugin-markdown-image) and [@vuepress/plugin-markdown-tab](https://github.com/vuepress/ecosystem/tree/HEAD/plugins/markdown/plugin-markdown-tab). Updates `@vuepress/plugin-markdown-image` from 2.0.0-rc.60 to 2.0.0-rc.61 - [Release notes](https://github.com/vuepress/ecosystem/releases) - [Commits](https://github.com/vuepress/ecosystem/commits/v2.0.0-rc.61/plugins/plugin-markdown-image) Updates `@vuepress/plugin-markdown-tab` from 2.0.0-rc.60 to 2.0.0-rc.61 - [Release notes](https://github.com/vuepress/ecosystem/releases) - [Changelog](https://github.com/vuepress/ecosystem/blob/main/plugins/markdown/plugin-markdown-tab/CHANGELOG.md) - [Commits](https://github.com/vuepress/ecosystem/commits/v2.0.0-rc.61/plugins/markdown/plugin-markdown-tab) --- updated-dependencies: - dependency-name: "@vuepress/plugin-markdown-image" dependency-type: direct:development update-type: version-update:semver-patch dependency-group: vuepress - dependency-name: "@vuepress/plugin-markdown-tab" dependency-type: direct:development update-type: version-update:semver-patch dependency-group: vuepress ... Signed-off-by: dependabot[bot] * Bump mermaid from 11.4.0 to 11.4.1 Bumps [mermaid](https://github.com/mermaid-js/mermaid) from 11.4.0 to 11.4.1. - [Release notes](https://github.com/mermaid-js/mermaid/releases) - [Changelog](https://github.com/mermaid-js/mermaid/blob/develop/CHANGELOG.md) - [Commits](https://github.com/mermaid-js/mermaid/compare/mermaid@11.4.0...mermaid@11.4.1) --- updated-dependencies: - dependency-name: mermaid dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] * DEC Training - Guidance Course (#263) * typos, adding details, updating control in section 7 to use a more intuitive example Signed-off-by: Will * fixing navbar to show all resource pages, combining and updating resource pages, adding the STIG vendor process guide as a downloadable PDF Signed-off-by: Will * updating the screenshots to use the right component (updating examples to be based off of most recent GPOS SRG Signed-off-by: Will * updating more screenshots, removing the step numbers in 5-7 since they dont make much sense for a doc with headers like this Signed-off-by: Will * updating images to use correct SRG version, fleshing out some sections, typos/copyediting Signed-off-by: Will * section 7 too long, decided it needed to be its own section -- TODO: decide if we want more content re: adding requirements Signed-off-by: Will * updating diff viewer section Signed-off-by: Will * flow editing for STIGs Signed-off-by: Will * typos Signed-off-by: Will --------- Signed-off-by: Will * typo Signed-off-by: Will * moving section 15 to an appendix Signed-off-by: Will * forgot to save last change Signed-off-by: Will * taking the wrong numbers out of the appendices Signed-off-by: Will --------- Signed-off-by: Shivani Karikar Signed-off-by: Aaron Lippold Signed-off-by: Will Signed-off-by: dependabot[bot] Co-authored-by: Aaron Lippold Co-authored-by: Will Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: wdower <57142072+wdower@users.noreply.github.com> --- .../Appendix A - Writing Plural Resources.md | 36 ++--- .../Appendix B - Resource Examples.md | 30 ++-- .../Appendix E - More Resource Examples.md | 4 +- src/courses/user/02.md | 28 ++-- src/courses/user/03.md | 45 ++---- src/courses/user/04.md | 39 +++-- src/courses/user/05.md | 38 ++--- src/courses/user/06.md | 89 ++++++++--- src/courses/user/07.md | 79 ++-------- src/courses/user/08.md | 86 +++++------ src/courses/user/09.md | 29 ++-- src/courses/user/10.md | 23 +-- src/courses/user/11.md | 31 ++-- src/courses/user/12.md | 37 +++-- src/courses/user/13.md | 5 +- src/courses/user/14.md | 16 +- src/courses/user/15.md | 142 ++---------------- src/courses/user/16.md | 20 --- ...ning InSpec In An Airgapped Environment.md | 61 ++++++++ src/courses/user/README.md | 38 ++--- 20 files changed, 403 insertions(+), 473 deletions(-) delete mode 100644 src/courses/user/16.md create mode 100644 src/courses/user/Appendix A - Running InSpec In An Airgapped Environment.md diff --git a/src/courses/advanced/Appendix A - Writing Plural Resources.md b/src/courses/advanced/Appendix A - Writing Plural Resources.md index bb9bbe933..a2f6639d0 100644 --- a/src/courses/advanced/Appendix A - Writing Plural Resources.md +++ b/src/courses/advanced/Appendix A - Writing Plural Resources.md @@ -5,7 +5,7 @@ author: Aaron Lippold headerDepth: 3 --- -## 10. Plural Resources +## Plural Resources You might have noticed that many InSpec resources have a "plural" version. For example, `user` has a `users` counterpart, and `package` has `packages`. @@ -30,7 +30,7 @@ This test queries **all** users to confirm that the only one with a uid of zero Plural InSpec resources are created by leveraging Ruby's FilterTable module to capture system data. Let's dig into how FilterTable works so that you can write your own plural resources. -### 10.1. Using FilterTable to write a Plural Resource +### Using FilterTable to write a Plural Resource FilterTable is intended to help you author plural resources with **stucture data**. You declare a number of columns of data, attach them to a FilterTable object, and then write methods that the FilterTable can call to populate those columns. You can also define custom matchers that make sense for whatever data you are modeling (to go alongside the standard InSpec matchers like `be_in`,`include`, and `cmp`). You wind up with a queryable structure: @@ -47,11 +47,11 @@ inspec> etc_hosts.entries ``` -#### 10.1.1. May I have multiple FilterTable installations on a class? +#### May I have multiple FilterTable installations on a class? In theory, yes - that would be used to implement different data fetching / caching strategies. It is a very advanced usage, and no core resources currently do this, as far as we know. -### 10.2. FilterTable Hands-On +### FilterTable Hands-On Let's take a look at the structure of a resource that leverages FilterTable. We will write a dummy resource that models a small group of students. Our resource will describe each student's name, grade, and the toys they have. Usually, a resource will include some methods that reach out the system under test to populate the FilterTable with real system data, but for now we're just going to hard-code in some dummy data. @@ -99,7 +99,7 @@ end ``` Now we've got a nice blob of code in a resource file. Let's load this resource in the InSpec shell and see what we can do with it. -#### 10.2.1. Run the InSpec shell with a custom resource +#### Run the InSpec shell with a custom resource Invoking the InSpec shell with `inspec shell` will give you access to all the core InSpec resources by default, but InSpec does not automatically know about your locally defined resources unless you point them out. If you're testing a local resource, use the `--depends` flag and pass in the profile directory that your resource lives in. @@ -107,7 +107,7 @@ Invoking the InSpec shell with `inspec shell` will give you access to all the co inspec shell --depends /path/to/profile/root/ ``` -#### 10.2.2. Fetching Data +#### Fetching Data FilterTables organize their data into columns. Your resource will declare a number of columns using the `register_column` method. @@ -115,7 +115,7 @@ Once you declare the columns that you want in your FilterTable (`name`, `grade`, As we mentioned earlier, a real InSpec resource will include methods that will populate the resource with real system data. Take a look at the [Firewalld resource](https://github.com/inspec/inspec/blob/63a5fd26a6925b1570ee80e2953d259b58c3012e/lib/inspec/resources/firewalld.rb) for an example of a resource that does this -- note the resource is ultimately invoking a shell command (`firewall-ctl`) to populate its FilterTable. There are plenty of other InSpec resources using FilterTable that you can find in the source code if you are interested in more examples. -#### 10.2.3. Custom Matcher Examples +#### Custom Matcher Examples After we define our FilterTable's columns, we can also define custom matchers just like we do in singluar resources using `register_custom_matcher`. That function takes a block as an argument that defines a boolean expression that tells InSpec when that matcher should return `true`. Note that the matcher's logic can get pretty complicated -- that's why we're shoving all of it into a resource so we can avoid having to write complicated tests. @@ -167,7 +167,7 @@ Test Summary: 1 successful, 0 failures, 0 skipped ``` -#### 10.2.4. Custom Property +#### Custom Property We can also declare custom properties for our resource, using whatever logic we like, just like we did for our custom matchers. Properties can be referred to with `its` syntax in an InSpec test. @@ -209,7 +209,7 @@ Test Summary: 0 successful, 1 failure, 0 skipped ``` -#### 10.2.5. Suggested activity +#### Suggested activity To get a better feel for how FilterTable works, we suggest you add a few extra features to the sample given above. @@ -219,11 +219,11 @@ To get a better feel for how FilterTable works, we suggest you add a few extra f Then write some tests to see how your new matchers and properties work. -### 10.3. Predefined Methods for FilterTable +### Predefined Methods for FilterTable When you create a new FilterTable, these methods are installed automatically: `where`, `entries`, `raw_data`, `count`, and `exist?`. Each is very useful both for writing tests in and of themselves and for creating custom matchers and properties inside the resource code. -#### 10.3.1 The `where` method +#### The `where` method You may have already noticed that a bunch of our example tests are using the `where` method on the FilterTable object. This method returns a new FilterTable object created from the rows of the original table that match the query provided to `where`. If you have experience with relational databases, think of it like the `WHERE` clause in a SQL query. This method is extremely flexible; we give some examples below. @@ -255,7 +255,7 @@ You may have already noticed that a bunch of our example tests are using the `wh ``` -##### 10.3.1.1. `where` method with blocks +##### `where` method with blocks You can also call the `where` method with a block. The block is executed row-wise. If it returns truthy, the row is included in the results. Each field declared with the `register_custom_property` configuration method is available as a data accessor. @@ -272,7 +272,7 @@ You can also call the `where` method with a block. The block is executed row-wis end ``` -##### 10.3.1.2. Chaining `where` calls and Tables without re-fetching raw data +##### Chaining `where` calls and Tables without re-fetching raw data The first time `where` is called, the data fetcher method is called. `where` performs filtration on the raw data table. It then constructs a new `FilterTable::Table`, directly passing in the filtered raw data; this is then the return value from `where`. @@ -285,7 +285,7 @@ The first time `where` is called, the data fetcher method is called. `where` pe Some other methods return a Table object, and they may be chained without a re-fetch as well. -#### 10.3.2. The `entries` method +#### The `entries` method The other `register_filter_method` call enables a pre-defined method, `entries`. `entries` is much simpler than `where` - in fact, its behavior is unrelated. It returns an encapsulated version of the raw data - a plain array, containing Structs as row-entries. Each struct has an attribute for each time you called `register_column`. @@ -319,7 +319,7 @@ If you call `entries` without chaining it after `where`, calling entries will tr end ``` -#### 10.3.3. The `exist?` matcher +#### The `exist?` matcher This `register_custom_matcher` call: ```ruby @@ -342,7 +342,7 @@ As when you are implementing matchers on a singular resource, the only thing tha end ``` -#### 10.3.4. The `count` property +#### The `count` property This `register_custom_property` call: ```ruby @@ -363,7 +363,7 @@ causes a new method to be defined on both the resource class and the Table class end ``` -#### 10.3.5. The `raw_data` method +#### The `raw_data` method Unlike `entries`, which wraps each row in a Struct and omits undeclared fields, `raw_data` simply returns the actual raw data array-of-hashes. It is not `dup`'d. People _definitely_ use this out in the wild, even though it returns a rougher data structure. @@ -377,7 +377,7 @@ Unlike `entries`, which wraps each row in a Struct and omits undeclared fields, end ``` -### 10.4 FilterTable Examples +### FilterTable Examples FilterTable is a very flexible and powerful class that works well when designing plural resources. As always, if you need to write a plural resource, we encourage you to examine existing resources in the InSpec source code to see how other developers have implemented it. Some good examples include: - [FirewallD](https://github.com/inspec/inspec/blob/63a5fd26a6925b1570ee80e2953d259b58c3012e/lib/inspec/resources/firewalld.rb) diff --git a/src/courses/advanced/Appendix B - Resource Examples.md b/src/courses/advanced/Appendix B - Resource Examples.md index 961444a97..fc975296e 100644 --- a/src/courses/advanced/Appendix B - Resource Examples.md +++ b/src/courses/advanced/Appendix B - Resource Examples.md @@ -7,8 +7,9 @@ headerDepth: 3 As an example we will go through a few custom resources that were built and approved. -### 14.1. IPv6 resource -#### 14.1.1. docs/resources/ip6tables.md.erb +### The IPv6 resource + +#### docs/resources/ip6tables.md.erb ```ruby --- title: About the ip6tables Resource @@ -86,7 +87,7 @@ The `have_rule` matcher tests the named rule against the information in the `ip6 it { should have_rule('RULE') } ``` -#### 14.1.2. lib/inspec/resources.rb +#### lib/inspec/resources.rb ```ruby require "inspec/resources/iis_site" require "inspec/resources/inetd_conf" @@ -97,7 +98,7 @@ require "inspec/resources/kernel_module" require "inspec/resources/kernel_parameter" ``` -#### 14.1.3. lib/inspec/resources/ip6tables.rb +#### lib/inspec/resources/ip6tables.rb ```ruby require "inspec/resources/command" @@ -184,7 +185,7 @@ end While submitting PR it may be possible to extend existing test elements from current resources to perform integration and unit testing such is seen in this example, the ipv6 resource extends the testing for [iptables](https://www.inspec.io/docs/reference/resources/iptables/) resource ::: -#### 14.1.4. test/integration/default/controls/ip6tables_spec.rb +#### test/integration/default/controls/ip6tables_spec.rb ```ruby case os[:family] when 'ubuntu', 'fedora', 'debian', 'suse' @@ -211,7 +212,7 @@ when 'redhat', 'centos' end ``` -#### 14.1.5. test/unit/resources/ip6tables_test.rb +#### test/unit/resources/ip6tables_test.rb ```ruby require "helper" require "inspec/resource" @@ -247,8 +248,8 @@ describe "Inspec::Resources::Ip6tables" do end ``` -### 14.2. NGINX resource -#### 14.2.1. docs/resources/nginx.md.erb +### The NGINX resource +#### docs/resources/nginx.md.erb ```ruby --- title: The Nginx Resource @@ -324,7 +325,7 @@ where end ``` -#### 14.2.2. lib/inspec/resource.rb +#### lib/inspec/resource.rb ```ruby require 'resources/mysql' require 'resources/mysql_conf' @@ -335,7 +336,7 @@ require 'resources/npm' require 'resources/ntp_conf' ``` -#### 14.2.3. lib/resources/nginx.rb +#### lib/resources/nginx.rb ```ruby # encoding: utf-8 # author: Aaron Lippold, lippold@gmail.com @@ -436,7 +437,7 @@ module Inspec::Resources end ``` -#### 14.2.4. test/unit/resources/nginx_test.rb +#### test/unit/resources/nginx_test.rb ```ruby # encoding: utf-8 # author: Aaron Lippold, lippold@gmail.com @@ -534,10 +535,11 @@ describe 'Inspec::Resources::Nginx' do end ``` -### 14.3. Additional examples -#### 14.3.1. PAM resource currently open PR +### Additional examples + +#### PAM resource currently open PR - [PAM Resource](https://github.com/simp/inspec-profile-disa_stig-el7/blob/master/libraries/pam.rb) - [PAM PR](https://github.com/inspec/inspec/pull/3993) -#### 14.3.2. Customizing an already existing resource (windows registry) +#### Customizing an already existing resource (windows registry) - [https://github.com/mitre/microsoft-windows-2012r2-memberserver-stig-baseline/blob/master/libraries/windows_registry.rb](https://github.com/mitre/microsoft-windows-2012r2-memberserver-stig-baseline/blob/master/libraries/windows_registry.rb) diff --git a/src/courses/advanced/Appendix E - More Resource Examples.md b/src/courses/advanced/Appendix E - More Resource Examples.md index e30a5956b..f60c761ed 100644 --- a/src/courses/advanced/Appendix E - More Resource Examples.md +++ b/src/courses/advanced/Appendix E - More Resource Examples.md @@ -5,7 +5,7 @@ author: Aaron Lippold headerDepth: 3 --- -### 11.1. File +### The File Resource ```ruby # copyright: 2015, Vulcano Security GmbH @@ -371,7 +371,7 @@ module Inspec::Resources end ``` -### 11.3. etc_hosts +### The etc_hosts Resource ```ruby require "inspec/utils/parser" require "inspec/utils/file_reader" diff --git a/src/courses/user/02.md b/src/courses/user/02.md index 6dbcd582a..714deced6 100644 --- a/src/courses/user/02.md +++ b/src/courses/user/02.md @@ -7,25 +7,33 @@ headerDepth: 3 --- ## 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 + +- Automate tailored security configuration testing in every build. +- Aggregate all security assessment results in a single dashboard to show security status. + ### 2. Establish Security Requirements -- Align security tests to requirements -- Write STIG-ready content for software components + +- 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 + +- Automate security control assessment aligned to common standards. +- Implement security requirements within existing DevSecOps pipelines. + ### 4. Assess/Monitor Vulnerabilities -- Visualize results of all ongoing assessments to understand risk over time -- Enable ongoing or continuous authorization to operate (cATO) + +- Visualize results of all ongoing assessments to understand risk over time. +- Enable ongoing or continuous authorization to operate (cATO). ![The Goals of the SAF](../../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). +As illustrated in the picture below, the process for developing automated security tests starts with requirements documents like SRGs, STIGs, or CIS Benchmarks, which are written in human-readable language. These documents are 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 to a platform where it can be used to make informed decisions (such as 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. +This challenge is what the [MITRE Security Automation Framework](https://saf.mitre.org) (MITRE SAF) was developed to address. It simplifies the journey from a Requirement Document to an automated test profile and back again, making it easier to navigate. ![The SAF Lifecycle](../../assets/img/saf-lifecycle.png) diff --git a/src/courses/user/03.md b/src/courses/user/03.md index 9a0a52653..397ca69fe 100644 --- a/src/courses/user/03.md +++ b/src/courses/user/03.md @@ -6,56 +6,37 @@ author: Aaron Lippold headerDepth: 3 --- -## 3. SAF Scavenger Hunt +## 3.1 SAF Scavenger Hunt + Explore the [SAF homepage](https://saf.mitre.org/) to find the answers to this scavenger hunt and familiarize yourself with the topics of this course. When you are done, check your answers! ::: details 1. What are the main pillars of the SAF? -The main pillars are +The main pillars are: + - Plan - Harden - Validate -- Normailze +- Normalize - Visualize -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. +The SAF helps teams plan what guidance will help them keep their software secure. It also provides libraries and tools for automatically hardening and validating software based on that guidance, normalizing other security data, and visualizing all the information to properly inform teams of risk and vulnerabilities. ::: ::: details 2. Is SAF a tool? Why or why not? -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. +No. +SAF, the Security Automation Framework, is a framework that 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. Some notable tools within the Security Automation Framework are Vulcan, the SAF CLI, and Heimdall. -![Alt text](../../assets/img/SAF_Capabilities_SAF_Tools.png) +![SAF Tools](../../assets/img/SAF_Capabilities_SAF_Tools.png) ::: -::: details 3. What is HDF? -[HDF](https://saf.mitre.org/#/normalize), or Heimdall Data Format, is a common format to represent normalized security data. HDF files record vital security data about a completed validation test, such as the test code, description, attributes, and outcome. This allows for the aggregation and analysis of test results from a wide range of validation tools at once. +::: details 3. What is OHDF? +[OHDF](https://saf.mitre.org/#/normalize), or the OASIS Heimdall Data Format, is a common format to represent normalized security data. OHDF files record vital security data about a completed validation test, such as the test code, description, attributes, and outcome. This allows for the aggregation and analysis of test results from a wide range of validation tools at once. -HDF data can be easily visualized in [Heimdall](https://heimdall-lite.mitre.org/), the SAF's visualization application. +OHDF data can be easily visualized in [Heimdall](https://heimdall-lite.mitre.org/), the SAF's visualization application. ::: ::: 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 "The MITRE SAF© Open Source Toolset" 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/). ::: - - diff --git a/src/courses/user/04.md b/src/courses/user/04.md index a56a05df3..5c982cece 100644 --- a/src/courses/user/04.md +++ b/src/courses/user/04.md @@ -6,26 +6,32 @@ author: Aaron Lippold headerDepth: 3 --- -## 4. Start with Planning -The SAF's main pillars are Plan, Harden, Validate, Normalize, and Visualize. First, it is necessary to plan what components will be in your system and identify the security guidance available for those components. +## 4.1 Start with Planning + +The SAF's main pillars are Plan, Harden, Validate, Normalize, and Visualize. First, it is necessary to plan which components are/will be in your system and identify the security guidance available for those components. ![The Plan Capability](../../assets/img/SAF_Capabilities_Plan.png) -### 4.1 Identify your stack of components for the system -Your software system is composed of multiple components. i.e., Cloud Services, Virtualization Platforms, Operating Systems, Databases, Application Logic, and Web Servers. +## 4.2 Identify Your Stack of Components for the System + +Your software system is composed of multiple components, such as Cloud Services, Virtualization Platforms, Operating Systems, Databases, Application Logic, and Web Servers. + +The first step of any assessment is identifying the components of the system you are assessing. -The first step of any assessment is identifying the components for the system you are assessing. - +## 4.3 What is the Guidance? -### 4.2 What is the guidance? -There could be Security Technical Implementation Guides (STIGs), Security Requirements Guides (SRGs), Center for Internet Security (CIS) Benchmarks, or vendor guidance written for the components in your software stack. Being aware of these can help inform which profile to use. Additionally, note here any specific requirements for your organization that might differ from the specific published guidance. This will inform how to tailor the profiles later on. +There could be Security Technical Implementation Guides (STIGs), Security Requirements Guides (SRGs), Center for Internet Security (CIS) Benchmarks, or vendor guidance written for the components in your software stack. Being aware of these can help inform which profile to use. -### 4.3. Content libraries for software components +::: tip Note +Outline any specific requirements for your organization that might differ from the specific published guidance. This will inform how to tailor the profiles later on. +::: + +## 4.4 Content Libraries for Software Components -As you saw in the previous section's [SAF Site scavenger hunt](./03), the SAF website hosts links, informaiton, and tools to ease the security process. To get a better idea of what may be in your software stack and what kind of content is available for automated testing, you can peruse the SAF's hardening and validation content libraries when you are making a plan. +As you saw in the previous section's [SAF Site scavenger hunt](./03.md), the SAF website hosts links, information, and tools to ease the security process. To get a better idea of what may be in your software stack and what kind of content is available for automated testing, you can peruse the SAF's hardening and validation content libraries when you are making a plan. ::: details Go to saf.mitre.org -Go to the [SAF site](saf.mitre.org) to peruse the hardening and validation libraries. As the security community develops more automation content, we update this site as a landing page for all of the content. The site will look like this: +Go to the [SAF site](https://saf.mitre.org) to explore the hardening and validation libraries. As the security community develops more automation content, we update this site as a landing page for all of the content. The site will look like this: ![The SAF Homepage](../../assets/img/SAF_Home.png) ::: @@ -35,11 +41,12 @@ Navigate to the [Harden page](https://saf.mitre.org/#/harden) to find library co ::: ::: details Peruse Validation Content -Navigate to the [Validate page](https://saf.mitre.org/#/validate) to find library content for validating different software components against security guidance. Validation content is software used to test whether the component is configured to some security guidance. We will be looking more at the Validation library in a moment. +Navigate to the [Validate page](https://saf.mitre.org/#/validate) to find library content for validating different software components against security guidance. Validation content is software used to test whether the component is configured according to security guidance. We will be looking more at the Validation library in a moment. ![Validation](../../assets/img/SAF_Site_Validate.png) ::: -### 4.4. What if there is no content for a software component? -- First, reach out to the SAF team at [saf@groups.mitre.org](mailto:saf@groups.mitre.org) to find out if there is a profile in development or otherwise available but not listed that could meet your needs. -- Second, if there is still no profile available, identify the security guidance to which the profile should comply and reach out to find out how to best create that profile. We help teams do this and provide training courses on that as well! -- Third, if there is no guidance available for your particular component, talk with us about developing the guidance using [MITRE's Vulcan application](https://vulcan.mitre.org/). Reference the [training class](../guidance) on security guidance development. \ No newline at end of file +## 4.5 What if There is No Content for a Software Component? + +1. First, reach out to the SAF team at [saf@groups.mitre.org](mailto:saf@groups.mitre.org) to find out if there is a profile in development or otherwise available but not listed that could meet your needs. +2. Second, if there is still no profile available, identify the security guidance to which the profile should comply and reach out to find out how to best create that profile. We help teams do this and provide training courses on that as well! +3. Third, if there is no guidance available for your particular component, talk with us about developing the guidance using [MITRE's Vulcan application](https://vulcan.mitre.org/). Reference the [training class](../guidance) on security guidance development. diff --git a/src/courses/user/05.md b/src/courses/user/05.md index d267b931f..a950b36e1 100644 --- a/src/courses/user/05.md +++ b/src/courses/user/05.md @@ -6,55 +6,57 @@ author: Aaron Lippold headerDepth: 3 --- -## 5. From "Plan" to "Validate" +## 5.1 From "Plan" to "Validate" -After identifying software components for your environment and knowing what security guidance exists for those components, a great next step is validation, or in other words, testing. +After identifying software components for your environment and knowing what security guidance exists for those components, the next step is validation, or in other words, testing. ![The Validation Capability](../../assets/img/SAF_Capabilities_Validate.png) ::: info WAIT! But what about the "Harden" pillar? Why would we focus on testing that a software component is secure before we secure it? -Actually, starting with the tests, rather than the changes to be tested, can level-set the expectations and see what the current state of the software is while giving a clear understanding of the goal or measurement of success. +Actually, starting with the tests, rather than the changes to be tested, can level-set the expectations and see what the current state of the software is while giving a clear understanding of the goal or measurement of success. When using this mindset in software development, this kind of development can be referred to as Test Driven Development. ::: ::: details A note on Test Driven Development (TDD) -The idea of using Test Driven Development (in other words, having the code driven by tests and therefore, the requirements) helps the humans confirm that the software does exactly what it is supposed to do - not more and not less. +The idea of using Test Driven Development (TDD), where the code is driven by tests and therefore the requirements, helps confirm that the software does exactly what it is supposed to do - not more and not less. -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. +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. ![Test-Driven Development](../../assets/img/TestDrivenDevelopment.png) ::: -## 5.1 What is InSpec? -"Chef [InSpec](https://www.chef.io/downloads/tools/inspec) is an infrastructure security and compliance testing framework with a human- and machine-readable language for comparing actual versus desired system state." +## 5.2 What is InSpec? -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. +"Chef [InSpec](https://www.chef.io/downloads/tools/inspec) is an infrastructure security and compliance testing framework with a human- and machine-readable language for comparing actual versus desired system state." + +The SAF uses InSpec profiles to test software components against a security baseline. These automated tests produce data showing what security controls passed, failed, were skipped, or were not reviewed, and provide reasons and more information to fix issues if they are 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). +The term __InSpec profile__ refers to 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: +## 5.3 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 -2. The security guidance that the profile is based on (ex: a DISA STIG) +2. The security guidance that the profile is based on (e.g., a DISA STIG) 3. Available inputs for tailoring to your environment 4. Instructions for running the profile -### 5.2.1 RHEL8 baseline profile +### 5.3.1 RHEL8 baseline profile -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). +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). ![The Red Hat 8 Profile](../../assets/img/Github_Rhel8.png) -### 5.2.2 NGINX baseline profile +### 5.3.2 NGINX baseline profile -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). - +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). ![The NGINX Profile](../../assets/img/Github_nginx.png) diff --git a/src/courses/user/06.md b/src/courses/user/06.md index 04d17888f..85b3ad753 100644 --- a/src/courses/user/06.md +++ b/src/courses/user/06.md @@ -6,39 +6,76 @@ author: Aaron Lippold headerDepth: 3 --- -## 6. How to Run InSpec +## 6.1 How to Run InSpec -In this section, we will talk about how to run InSpec. In [Section 8](./08.md), you will put this into practice! +In this section, we will discuss how to run InSpec. In [Section 8](./08.md), you will put this into practice! + +## 6.2 Requirements -### 6.1 Requirements To run InSpec, you must have: -1. **InSpec** - you must have InSpec downloaded on whatever machine is running the scans. This does not have to be the same machine that is being tested! _(We will run InSpec from the GitHub codespaces lab environment. Inspec is already downloaded in the GitHub codespaces lab environment after running the `./lab-setup.sh` script)_ Check out the [Installation Tab](../../installation) for more information on installing InSpec in a different environment. -2. **A Target** - you have to have something to test! _In the GitHub codespaces in the lab environment, we have two Docker containers running to test._ -3. **An InSpec Profile** - you have to have the tests themselves! This is the code itself that will be run with all of the controls, or tests, against the target. You may have this code stored locally on your runner machine, or you may get it from GitHub if your system has access to the internet. We will look at both of those examples. -### 6.2 The InSpec Command Formula -You run InSpec from the command line. There are many different options for this command, but let's break down the simple formula based on the requirements above. +1. **The InSpec Executable** - InSpec's exectuable must be installed on the machine running the scans. This does not have to be the same machine that is being tested! _(We will run InSpec from the GitHub Codespaces lab environment. InSpec is already downloaded in the GitHub Codespaces lab environment after running the install script using `source build-lab.sh`.)_ Check out the [Installation Tab](../../installation) for more information on installing InSpec in a different environment. +2. **A Target** - You need something to test! _In the GitHub Codespaces lab environment, we have two Docker containers running to test._ +3. **An InSpec Profile** - You need the tests themselves! This is Ruby code containing all of the controls, or tests, that we intend to run against the target. You may have this code stored locally on your runner machine, or you may get it from any accessible network location -- GitHub is an excellent example. We will practice running profiles from local files and from a GitHub repository. + +## 6.3 The InSpec Command Formula + +To validate a system, we need to run InSpec from the command line. There are many different options we can use with the InSpec exectuable to run our tests. Let's break down the simple formula based on the requirements above. + +```sh +inspec exec -t --more-flags ... --reporter +``` + +```sh +inspec exec WHERE_IS_THE_PROFILE # 6.3.1 & 6.3.2 +-t WHAT_IS_THE_TARGET # 6.3.3 +--more-flags EXTRA_STUFF # 6.3.4 +--reporter WHAT_SHOULD_INSPEC_DO_WITH_THE_RESULTS # 6.3.5 +``` + +### 6.3.1 Start with `inspec exec` (required) ```sh -inspec exec WHERE_IS_THE_PROFILE -t WHAT_IS_THE_TARGET --more-flags EXTRA_STUFF --reporter WHAT_SHOULD_INSPEC_DO_WITH_THE_RESULTS +inspec exec ``` -#### Start with inspec exec -You need to start with `inspec exec` so that your terminal knows what it is trying to do in the first place. +We'll start with `inspec exec` so that the InSpec exectuable knows what we are asking it to do -- in this case, `inspec exec` tells InSpec to execute an existing profile. (There are other options, like `inspec shell` and `inspec profile init`, but they are not our focus right now. We'll look at some of them during other MITRE SAF training classes.) + +### 6.3.2 WHERE_IS_THE_PROFILE (required) + +```sh +inspec exec WHERE_IS_THE_PROFILE +``` -#### WHERE_IS_THE_PROFILE -Then, you can give the location of the InSpec profile, in other words, the code for the tests themselves. If the InSpec profile is stored locally, you can write a path to that file location, such as `/root/path/to/InSpecProfiles/nginx-profile`. If you are hoping to directly access the profile from GitHub, you can enter the url of the GitHub profile, such as `https://github.com/mitre/nginx-stigready-baseline`. +Then, you must give the _location_ of the InSpec profile. In other words, we need to show the InSpec exectuable where to find the code for the tests themselves. If the InSpec profile is stored locally, you can simply write out the path to that file location, such as `/root/path/to/InSpecProfiles/nginx-profile`. If you wish to run a profile directly from GitHub or some other location on the Internet or other network, you can enter the URL of the profile instead, such as `https://github.com/mitre/nginx-stigready-baseline`. -#### WHAT_IS_THE_TARGET -Next, you need to tell your computer what the target is. You add this information after the `-t` flag. You could test against your local machine (which is less common), you could test a Virtual Machine, you could test a Docker container, or more. You could connect to that machine via SSH, WinRM, or more. We will talk more about these options later. +### 6.3.3 WHAT_IS_THE_TARGET (default: local machine) -#### EXTRA_STUFF -There are MANY more options that you can specify when running the InSpec command. The next most common one is specifying inputs for your profile, for example `--input-file /path/to/inputs.yml` where you can add inputs that tailor the profile to your environmnent's needs. You can find more information on inputs in the [Tailoring Inputs](./07) section. +```sh +-t WHAT_IS_THE_TARGET # 6.3.3 +``` -#### WHAT_SHOULD_INSPEC_DO_WITH_THE_RESULTS -And of course you probably want to see the results. You can specify where those results are displayed or saved based on what you enter after the `--reporter` flag at the end of your command. For example, the following would print the results on the command line and save it to a file (by creating or overwriting) the file at /path/to/results.json: `--reporter cli json:/path/to/results.json`. If you do not add this information, the command will default to providing results on the command line, but it will not save those into a file unless you specify the `--reporter` flag like the example. +Next, you need to tell your computer what the target is -- or rather, what system we are trying to test. You add this information using the `-t` flag. -Each profile's README should give an example of running the InSpec command for that profile, however, you can always reference the complete documentation on the InSpec command options [here](https://docs.chef.io/inspec/cli/). +Without the `-t` flag, by default, InSpec will execute the selected profile against your local system. However, we are often trying to run tests against a remote target. You could test a bare metal server, a virtual machine, a Docker container, or many other options. You could also specify different protocols to connect to your remote system via SSH, WinRM, or more. For example, we could connect to a system using `-t ssh://user-name@host-name:port` or `-t docker://instance-id`. We will talk more about these options later. + +### 6.3.4 EXTRA_STUFF (optional) + +```sh +--more-flags EXTRA_STUFF # 6.3.4 +``` + +There are many more options that you can specify when running the InSpec command. The next most common one is specifying inputs for your profile using the `--inputs` or `--input-file` flags. For example, `--input-file /path/to/inputs.yml` allows you to add inputs that tailor your test profile to your environment's particular configuration. You can find more information on inputs in the [Tailoring Inputs](./07) section. + +### 6.3.5 WHAT_SHOULD_INSPEC_DO_WITH_THE_RESULTS (default: cli) + +```sh +--reporter WHAT_SHOULD_INSPEC_DO_WITH_THE_RESULTS # 6.3.5 +``` + +And of course, once our test has completed, you probably want to see the results! You can specify where those results are displayed or saved based on what you enter after the `--reporter` flag at the end of your command. For example, the following would print the results on the command line and save it to a file (by creating or overwriting) the file at /path/to/results.json: `--reporter cli json:/path/to/results.json`. If you do not add this information, the command will default to providing results on the command line, but it will not save those into a file unless you specify the `--reporter` flag like the example. + +Each profile's README should give an example of running the InSpec command for that profile; however, you can always reference the complete documentation on the InSpec command options [here](https://docs.chef.io/inspec/cli/). :::details Want to give it a try? @@ -48,7 +85,7 @@ We will go more in depth on this example in the next two sections, but if you wa inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx --reporter cli ``` -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. +In the above example, we are testing an NGINX server. We get the InSpec profile (all 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:_ @@ -70,15 +107,16 @@ 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. +If you are using InSpec in a pipeline, you can silently accept the license. Refer to [Chef's documentation](https://docs.chef.io/licensing/accept/) for more information. ::: ::: details Transports - Advanced Examples -The `-t` flag (or `--target` flag in long form) specifies **what** target you want InSpec to scan. **How** you connect to that target is via a transport. Transports use standard ports and protocols. Some examples are SSH, WinRM, AWS SSM, Docker, and Kubernetes. +The `-t` flag (or `--target` flag in long form) specifies **what** target you want InSpec to scan. **How** you connect to that target is via a transport. Transports use standard ports and protocols. Some examples are SSH, WinRM, AWS SSM, Docker, and the Kubernetes API. ### Containers (docker transport) + ```sh inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://instance_id @@ -87,12 +125,14 @@ inspec exec https://github.com/mitre/nginx-stigready-baseline ``` ### SSH Transport + ```sh inspec exec https://github.com/mitre/nginx-stigready-baseline -t ssh://Username:Password@IP --input-file --reporter json: ``` + ::: :::tip Defaults @@ -104,7 +144,8 @@ Note that if you do not provide one of the required flags in the InSpec exec com | No --reporter flag | Prints results to the terminal on the InSpec runner machine | ::: -### 6.3 How to Deploy InSpec +## 6.4 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/7) depending on the needs of the user: ![Running InSpec](../../assets/img/runner.png) diff --git a/src/courses/user/07.md b/src/courses/user/07.md index 00b09e0c0..7e10116ff 100644 --- a/src/courses/user/07.md +++ b/src/courses/user/07.md @@ -6,40 +6,41 @@ author: Aaron Lippold headerDepth: 3 --- -## 7. What are inputs and why do I need them? +## 7.1 What are inputs and why do I need them? -Every InSpec profile on the SAF site is written to comply with some security guidance. However, every team's environment may be just a little bit different. For example, the path to a file may be different in different environments, or the list of permitted users for a certain system may vary with the environment. +Every InSpec profile on the SAF site is written to comply with specific security guidance. However, every team's environment may be slightly different. For example, the path to a file may vary between environments, or the list of permitted users for a certain system may differ. -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. +To accommodate these 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. ::: -## 7.1 Profile Inputs (see `inspec.yml` file) +## 7.2 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. +This profile uses InSpec Inputs to make the tests more flexible. You can provide inputs at runtime either via the CLI or via YAML files to help the profile work best in your deployment. -::: danger +::: danger **DO NOT** change the inputs in the `inspec.yml` file. This is where the variables and their defaults are defined. **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. +The `inputs` configured in the `inspec.yml` file are **profile definitions and defaults for the profile** and not for tailoring. 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 Use an --input-file to tailor an InSpec profile +## 7.3 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 + +1. Right-click near the file list on the left side. 2. Click "New File..." 3. Copy the code below into your `inputs.yml` file. -```yml +```yaml --- key_file_path: /etc/ssl/nginx-selfsigned.pem org_allowed_nginx_version: 1.23.1 @@ -54,63 +55,15 @@ In your codespaces, it should look like this: ![NGINX Input File](../../assets/img/Codespaces_InputFile_NGINX.png) ::: tip How do I find the values that should be in the input file? -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. +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 guides 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. +To determine the value itself, you should consider the environment, consult with your assessor, and explore the target to 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. +If the profile does not have a "Tailoring to Your Environment" section in its README, 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? -**Inputs** are meant to tailor the profile while _still complying_ to the guidance document for which the profile is based. +**Inputs** are meant to tailor the profile while _still complying_ with the guidance document on which the profile is based. -**Overlays** are used in the case that the organization requirements _differ_ from the security guidance. For example, if there are additional controls required or some controls not available for the organization's requirements. +**Overlays** are used when the organization's requirements _differ_ from the security guidance. For example, if there are additional controls required or some controls are not applicable to the organization's requirements. ::: - - diff --git a/src/courses/user/08.md b/src/courses/user/08.md index f19cd1edc..872486c07 100644 --- a/src/courses/user/08.md +++ b/src/courses/user/08.md @@ -1,46 +1,46 @@ --- order: 8 next: 09.md -title: 8. Running InSpec +title: 8. Running InSpec (NGINX Example) author: Aaron Lippold headerDepth: 3 --- -## 8. Run InSpec - NGINX Example +## 8.1 Example Running an InSpec Profile Directly from GitHub +In this module, we use NGINX for learning purposes. If you're interested in NGINX specifically, you may be interested in the [MITRE nginx-stigready-baseline](https://github.com/mitre/nginx-stigready-baseline) profile on GitHub. - -### 8.1. Example running an InSpec profile directly from Github - -In this module, we use NGINX for learning purposes. If you're interested in NGINX specifically, you may be interested in the [MITRE nginx-stigready-baseline](https://github.com/mitre/nginx-stigready-baseline) profile on GitHub. - -::: details Alternative profiles +::: details Alternative Profiles Alternatively, you may also check out the [DevSec Nginx Baseline](https://supermarket.chef.io/tools/nginx-baseline) profile on Chef Supermarket. To execute the Chef Supermarket profile on your target system, run this `inspec supermarket exec` command. -Sometimes, there are multiple profiles available for the same software component. This could be because there are different people or teams who both wrote automation content, or it could be because one profile is based on one set of guidance (such as a DISA STIG) and another profile could be based on different guidance (such as a CIS Benchmark). +Sometimes, there are multiple profiles available for the same software component. This could be because different people or teams wrote automation content, or because one profile is based on one set of guidance (such as a DISA STIG) and another profile is based on different guidance (such as a CIS Benchmark). -If you see multiple profiles available and are unsure what to use, read the READMEs in each to see what guidance they are based on to understand what is most useful for your situation. You can also run multiple profiles and compare the results to see which is more informative for your assessment. Lastly, you can always reach out to saf@groups.mitre.org if you have more questions. +If you see multiple profiles available and are unsure which to use, read the READMEs in each to see what guidance they are based on to understand what is most useful for your situation. You can also run multiple profiles and compare the results to see which is more informative for your assessment. Lastly, you can always reach out to if you have more questions. ::: -### 8.2 Forming the InSpec Command -- Since we are using the profile from GitHub, we will use the GitHub link `https://github.com/mitre/nginx-stigready-baseline` to specify the profile. -- Because we are using a Docker container that is running in our lab environment, we can specify the target as `-t docker://nginx`. -- We can chose to output the results to the command line and to a file like this `--reporter cli json:./results/nginx_vanilla_results.json` -- We can add the inputs file that we created so the profile is tailored to our environment like this `--input-file inputs.yml` +## 8.2 Forming the InSpec Command + +- Since we are using the profile from GitHub, we will use the GitHub link `https://github.com/mitre/nginx-stigready-baseline` to specify the profile. +- Because we are using a Docker container that is running in our lab environment, we can specify the target as `-t docker://nginx`. +- We can choose to output the results to the command line and to a file like this: `--reporter cli json:./results/nginx_vanilla_results.json` +- We can add the inputs file that we created so the profile is tailored to our environment like this: `--input-file inputs.yml` -To execute this command to run the GitHub profile on your target system, run this `inspec exec` command. +To execute this command to run the GitHub profile on your target system, run this `inspec exec` command: ```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 ``` -### 8.3 Run the Command -Enter the command from the previous step in your terminal and press enter. It will take a moment to start running. +## 8.3 Run the Command + +Enter the command from the previous step in your terminal and press enter. It will take a moment to start running. + +### 8.3.1 CLI (Command Line) Results -#### 8.3.1 CLI (Command Line) Results 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 [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 @@ -59,7 +59,7 @@ inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx the configured time period directed by an authoritative source (e.g., IAVM, CTOs, DTMs, and STIGs). ✔ 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" + ✔ NGINX version v1.25.3 installed is greater than 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. @@ -75,59 +75,54 @@ Test Summary: 137 successful, 91 failures, 55 skipped You see that many of the tests pass, while others fail and may require investigation. - - +### 8.3.2 Results saved to a file -#### 8.3.2 Results saved to a file -You should also see your results in a JSON file located in `/results` folder with the name that you specified in the command, for example `nginx_vanilla_results.json`. If you are using the lab environment GitHub codespaces, you should see it on the top left of your screen under files. Right click that file and click "Download" so that you have this file locally for the next steps. +You should also see your results in a JSON file located in `/results` folder with the name that you specified in the command, for example `nginx_vanilla_results.json`. If you are using the lab environment GitHub codespaces, you should see it on the left of your screen under files. Right-click that file and click "Download" so that you have this file locally for the next steps. ![The Results Folder](../../assets/img/ResultsFolder.png) +::: details More on `--reporter` Options -::: details More on --reporter Options -#### Different --reporter Options -InSpec allows you to output your test results to one or more reporters. You can configure the reporter(s) using either the --json-config option or the --reporter option. While you can configure multiple reporters to write to different files, only one reporter can output to the screen(stdout). +#### Different `--reporter` Options -``` -$ inspec exec /root/my_nginx -t ssh://TARGET_USERNAME:TARGET_PASSWORD@TARGET_IP --reporter cli json:baseline_output.json +InSpec allows you to output your test results to one or more reporters. You can configure the reporter(s) using either the `--config` option or the `--reporter` option. While you can configure multiple reporters to write to different files, only one reporter can output to the screen (stdout). + +```sh +inspec exec /root/my_nginx -t ssh://TARGET_USERNAME:TARGET_PASSWORD@TARGET_IP --reporter cli json:baseline_output.json ``` #### Syntax -You can specify one or more reporters using the --reporter cli flag. You can also specify a output by appending a path separated by a colon. +You can specify one or more reporters using the `--reporter` CLI flag. You can also specify an output by appending a path separated by a colon. -Output json to screen. +Output JSON to screen. -``` -inspec exec /root/my_nginx --reporter json +`inspec exec /root/my_nginx --reporter json` or -inspec exec /root/my_nginx --reporter json:- -``` +`inspec exec /root/my_nginx --reporter json:-` -Output yaml to screen +Output YAML to screen -``` -inspec exec /root/my_nginx --reporter yaml +`inspec exec /root/my_nginx --reporter yaml` or -inspec exec /root/my_nginx --reporter yaml:- -``` +`inspec exec /root/my_nginx --reporter yaml:-` -Output cli to screen and write json to a file. +Output CLI to screen and write JSON to a file. `inspec exec /root/my_nginx --reporter cli json:/tmp/output.json` -Output nothing to screen and write junit and html to a file. +Output nothing to screen and write JUnit and HTML to a file. `inspec exec /root/my_nginx --reporter junit:/tmp/junit.xml html:www/index.html` -Output json to screen and write to a file. Write junit to a file. +Output JSON to screen and write to a file. Write JUnit to a file. `inspec exec /root/my_nginx --reporter json junit:/tmp/junit.xml | tee out.json` -If you wish to pass the profiles directly after specifying the reporters you will need to use the end of options flag --. +If you wish to pass the profiles directly after specifying the reporters you will need to use the end of options flag `--`. `inspec exec --reporter json junit:/tmp/junit.xml -- profile1 profile2` -Output cli to screen and write json to a file. +Output CLI to screen and write JSON to a file. ```json { @@ -159,4 +154,3 @@ The following are the current supported reporters: You can read more about [InSpec Reporters](https://www.inspec.io/docs/reference/reporters/) on the documentation page. ::: - diff --git a/src/courses/user/09.md b/src/courses/user/09.md index 4c2404fc4..d6bf090ff 100644 --- a/src/courses/user/09.md +++ b/src/courses/user/09.md @@ -6,52 +6,54 @@ author: Aaron Lippold headerDepth: 3 --- -## 9. Visualize - MITRE Heimdall +## 9.1 Visualize - MITRE Heimdall -Now we want to SEE our results in a more meaningful way! +Now we want to see our results in a more meaningful way! ![The Visualize Capability](../../assets/img/SAF_Capabilities_Visualize.png) -Navigate to the our online version of the Heimdall application, the visualization tool, [Heimdall Lite](https://heimdall-lite.mitre.org/). +Navigate to our online version of the Heimdall application, the visualization tool, [Heimdall Lite](https://heimdall-lite.mitre.org/). -### 9.1 Upload Results -Click on the button `Upload` and navigate to your json output file that you saved from your previous step and select that file then click open. +## 9.2 Upload Results -This will allow you to view the InSpec results in the Heimdall viewer. +Click on the `Upload` button, navigate to your JSON output file that you saved from the previous step, select that file, and then click open. + +This will allow you to view the InSpec results in Heimdall. ![Loading Data Into Heimdall](../../assets/img/Heimdall_Load.png) -### 9.2 Visualize Results +## 9.3 Visualize Results Your visualization should look similar to the following: ![Visualizing NGINX](../../assets/img/Heimdall_NGINX_Vanilla_With_Inputs.png) -### 9.3 Explore Heimdall +## 9.4 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! +Heimdall allows 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 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? -You can interact with many different icons to filter for the specific results you want to see. For example, you can filter on the status, you can filter from the the severity level, you can filter from the search bar at the top, or you can filter using the tree map as some ways to drill down on a particular category or control. Here is a view of filtering with for failures. +You can interact with many different icons to filter for the specific results you want to see. For example, you can filter by status, severity level, search bar at the top, or using the tree map to drill down on a particular category or control. Here is a view of filtering for failures. ![Filtering on Failed Controls](../../assets/img/Heimdall_Filter_Failure.png) ::: ::: details How do you know which NIST 800-53 control is failing? -How can expand different sections of the NIST SP 800-53 Control Tree Map to see your coverage based on the NIST controls. In this image, the filter on failed controls is still applied, but you can clear that filter to see the overall tree map for your system. +You can expand different sections of the NIST SP 800-53 Control Tree Map to see your coverage based on the NIST controls. In this image, the filter on failed controls is still applied, but you can clear that filter to see the overall tree map for your system. ![Tree Map Filtered by Failing Controls](../../assets/img/Heimdall_TreeMap_Failures.png) ::: ::: details Can you find the reason for a failure? For example, V-41670? -As you continue to scroll down, you can see the Results View Data. You can expand the results for a given control to see the individual subcontrols or subtests that were run to test the requirement. If any subtests fail, the control overall will be recorded as a failed control. In this case, we can see that a subtest looking at the permission of the `/var/log/nginx` file was more permissive than it should be to meet the security requirements. +As you continue to scroll down, you can see the Results View Data. You can expand the results for a given control to see the individual tests that were run to test the requirement. If any tests fail, the control overall will be recorded as a failed control. In this case, we can see that a test looking at the permission of the `/var/log/nginx` file was more permissive than it should be to meet the security requirements. ![Result Details](../../assets/img/Heimdall_V-41670_ResultsDetails.png) ::: ::: details Where can you find information on how to fix a failed control? For example, V-41670? You can click on the "Details" or "Code" tab to see more information about how to check or fix a particular control. In this case, the fix text is written as follows: + ``` Fix: @@ -60,10 +62,11 @@ To protect the integrity of the data that is being captured in the and the user assigned to run the web server software is granted permissions to read the log files. ``` + ![The Code Tab](../../assets/img/Heimdall_V-41670_ResultsDetails_Code.png) ::: ::: 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. +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. ![NGINX Profile Inputs in Heimdall](../../assets/img/Heimdall_NGINX_Inputs.png) ::: diff --git a/src/courses/user/10.md b/src/courses/user/10.md index e5bbdc1b8..1da66e255 100644 --- a/src/courses/user/10.md +++ b/src/courses/user/10.md @@ -6,23 +6,23 @@ author: Aaron Lippold headerDepth: 3 --- -## 10. From "Plan" to "Validate" to "Visualize" to "Harden" +## 10.1 From "Plan" to "Validate" to "Visualize" to "Harden" -Finally! We get to secure the software. After starting with a plan, then seeing the requirements and current state through validation and visualiztion, let's harden the component and revalidate it after the changes. +Finally! We get to secure the software. After starting with a plan, and then seeing the requirements and current state through validation and visualization, let's harden the component and re-validate it after the changes. ![The Harden Capability](../../assets/img/SAF_Capabilities_Harden.png) -### 10.1 Find the hardening content +## 10.2 Find the hardening content -Remember when you perused the hardening content on the SAF site when we talked about the "Plan" pillar? This is where we will find automated content for configuring a software component to some guidance. In this case, we will use the NGINX Stigready Content on the [saf hardening page](https://saf.mitre.org/#/harden). +Remember when you perused the hardening content on the SAF site when we talked about the "Plan" pillar? This is where we will find automated content for configuring a software component to some guidance. In this case, we will use the NGINX STIG-ready Content on the [SAF Hardening page](https://saf.mitre.org/#/harden). -![The SAF Hardening Page](../../assets/img/SAF_Site_Harden.png) +![The SAF Hardening page](../../assets/img/SAF_Site_Harden.png) -You could peruse this GitHub repository, including the README and inputs to find out more information, but for this training, we have put any preparation needed for running this hardening content into a pre-script. +You could peruse this [GitHub repository](https://github.com/mitre/ansible-nginx-stigready-hardening), including the README and inputs to find out more information, but for this training, we have put any preparation needed for running this hardening content into a pre-script. -### 10.2 Prepare your Codespaces to run the hardening script +## 10.3 Prepare your Codespaces to run the hardening script -Just like we saw some requirements for running an InSpec scan, there are also some requirements to run the hardening script on the NGINX container in your Codespaces. We are going to run another setup script for those. +Just like we saw some requirements for running an InSpec scan, there are also some requirements to run the hardening script on the NGINX container in your Codespaces. We are going to run another setup script for those. In your Codespace terminal from your main workspace directory, run the following commands: @@ -34,23 +34,24 @@ This command will make sure that the NGINX docker container has the required sof ![After Running the Hardening Tools Script](../../assets/img/Codespaces_Hardening_Files.png) - -### 10.3 CLI Results of Hardening Script +## 10.4 CLI Results of Hardening Script You should see the following results from the hardening script. If you run this hardening content multiple times, the numbers in the results may be different because the starting configuration will be different and the script will not have to change the same numbers of settings. -::: note +::: note Make sure you are in the ansible content's directory before running the following command. You can run the command `cd ansible-nginx-stigready-hardening` to enter the directory. That means your current working directory path will look something like `/workspaces/saf-training-lab-environment/ansible-nginx-stigready-hardening` with variation if you named your repository differently in the lab setup. ::: Run this command: + ```sh ansible-playbook -i hosts.yml hardening-playbook.yml ``` To see the following results: + ```sh ansible-playbook -i hosts.yml hardening-playbook.yml [WARNING]: Ansible is being run in a world writable directory (/workspaces/saf-training-lab-environment/ansible-nginx-stigready-hardening), ignoring diff --git a/src/courses/user/11.md b/src/courses/user/11.md index 1d43d9072..c71d2759c 100644 --- a/src/courses/user/11.md +++ b/src/courses/user/11.md @@ -6,9 +6,7 @@ author: Emily Rodriguez headerDepth: 3 --- -## 11. Comparing Results - -### 11.1 Validate the software after hardening +## 11.1 Validate the software after hardening Now that we have hardened the software, we need to run InSpec again to see the results. @@ -24,7 +22,7 @@ Now, rerun the InSpec scan with a different file name by changing the `--reporte inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx --reporter cli json:./results/nginx_hardened_results.json --input-file inputs.yml ``` -### 11.2 CLI Results +## 11.2 CLI Results After running the command, you should see different results than when we ran the vanilla InSpec scan. @@ -60,7 +58,7 @@ inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx 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.23.1 is expected to cmp >= "1.23.1" + ✔ NGINX version v1.23.1 installed is greater than 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. @@ -93,38 +91,39 @@ Profile Summary: 62 successful controls, 3 control failures, 24 controls skipped Test Summary: 303 successful, 3 failures, 24 skipped ``` -### 11.3 Download the Results File +## 11.3 Download the Results File As you did before, download the results file. ![Downloading the Results](../../assets/img/Codespaces_Download_Harden_Results.png) -#### 11.3.1 Multiple Files in Heimdall? +### 11.3.1 Multiple Files in Heimdall? If you reopened [Heimdall](https://heimdall-lite.mitre.org/) to upload your `nginx_hardened_results.json`, then there will only be one file loaded. However, if you uploaded the results to the same instance of Heimdall that you had open before, you will now see two sets of results - your vanilla results and hardened results. You can click the menu on the top left what files are loaded and select only those you wish to see. In this case, only select the hardened results so we can look more at those. ![The Heimdall Select Menu](../../assets/img/Heimdall_Select_Menu.png) ::: details Heimdall with a backend (server) -Throughout this class, we are using the [Heimdall-lite](https://heimdall-lite.mitre.org/) version of the Heimdall application. However, many organizations chose to deploy Heimdall with a backend (you can see a demo version [here](https://heimdall-demo.mitre.org/)), in other words, with a server to store data. This requires more setup than just opening up Heimdall-lite in the webpage, however, you can: +Throughout this class, we are using the [Heimdall-lite](https://heimdall-lite.mitre.org/) version of the Heimdall application. However, many organizations chose to deploy Heimdall with a backend (you can see a demo version [here](https://heimdall-demo.mitre.org/)), in other words, with a server to store data. This requires more setup than just opening up Heimdall-lite on the webpage, however, you can: + - Store files in a database - Send files to the app via an API call - Share information across multiple users -- Login via third part authenticators, like Keycloak. +- Login via third-party authenticators, like Keycloak. You can find out more details on the difference between the two versions of this application in the [Heimdall README](https://github.com/mitre/heimdall2#heimdall-lite-vs-heimdall-with-backend-server). ::: -Take some time to explore the hardened results. Filter through different statuses, checkout the alignment to NIST 800-53 controls, and more! +Take some time to explore the hardened results. Filter through different statuses, check out the alignment to NIST 800-53 controls, and more! +## 11.4 Visualize the Results in Heimdall -### 11.4 Visualize the Results in Heimdall +Another valuable view for monitoring changes and showing results is the comparison view. -Another valuable view for monitoring changes and showing results is the comparison view. -1. Make sure you have both the vanilla and hardened results uploaded into Heimdall. -2. To compare results, click on the three lines in the top, left corner and toggle the "Comparison View" on. +1. Make sure you have both the vanilla and hardened results uploaded into Heimdall. +2. To compare results, click on the three lines in the top-left corner and toggle the "Comparison View" on. 3. Explore what changed and why! -You could use the Heimdall with backend version of the application and upload security results at regular intervals to see the changes over time. There are two graphs that show compliance over time and number of failed tests by severity over time. +You could use the Heimdall with the backend version of the application and upload security results at regular intervals to see the changes over time. There are two graphs that show compliance over time and the number of failed tests by severity over time. -![Comparison View](../../assets/img/Heimdall_Click_ComparisonView.png) \ No newline at end of file +![Comparison View](../../assets/img/Heimdall_Click_ComparisonView.png) diff --git a/src/courses/user/12.md b/src/courses/user/12.md index e1ded4bb9..3969109a5 100644 --- a/src/courses/user/12.md +++ b/src/courses/user/12.md @@ -6,13 +6,13 @@ author: Emily Rodriguez headerDepth: 3 --- -## 12. Manual Attestations +## 12.1 Manual Attestations What about controls that cannot be automated and require manual review? You may have noticed that Heimdall displays controls in 4 statuses: `Passed`, `Failed`, `Not Applicable`, and `Not Reviewed`. Controls may be `Not Reviewed` for multiple reasons. One major reason is that the control requires manual review. You can explore the details of the `Not Reviewed` controls to find out more. -### 12.1 Explore the Not Reviewed Controls +## 12.2 Explore the Not Reviewed Controls Look at the hardened results again in Heimdall. Go back to the menu in the top left to toggle off "Comparison View" and select on the hardened results. @@ -24,34 +24,41 @@ Scroll down to see the details and learn why the controls were not reviewed. You can see that for various reasons, many of these controls require manual review. If someone does that manual review, how can we show that in the data? -### 12.2 Manual Attestations Using SAF CLI +## 12.3 Manual Attestations Using SAF CLI You have already seen the InSpec profiles and the Heimdall application that the SAF provides. Another feature of the SAF is the SAF CLI. This is a command line utility tool that helps with various steps in the security automation process. You can see all of the SAF CLI's capability [here](https://saf-cli.mitre.org/), but we will look more at how we can use it to add manual attestation data to our overall results. -### 12.3 Get Familiar with SAF CLI +## 12.4 Get Familiar with SAF CLI SAF CLI has been downloaded into your Codespaces lab environmnet, so it is available for you to use on the command line. Try out a few commands to see what you can do! ::: code-tabs @tab Command + ```sh saf --version ``` + @tab Output + ```sh @mitre/saf/1.2.34 linux-x64 node-v20.8.1 ``` + ::: The help command will give you the information on how to use the SAF CLI: ::: code-tabs @tab Command + ```sh saf help ``` + @tab Output + ```sh The MITRE Security Automation Framework (SAF) Command Line Interface (CLI) brings together applications, techniques, libraries, and tools developed by MITRE and the security community to streamline security automation for systems and DevOps pipelines. @@ -83,6 +90,7 @@ COMMANDS summary Get a quick compliance overview of an HDF file version ``` + ::: You can use the `-h` flag to get more information on the different topics and commands. @@ -90,11 +98,13 @@ You can use the `-h` flag to get more information on the different topics and co ::: code-tabs @tab Command + ```sh saf attest -h ``` @tab Output + ```sh [Attest] Attest to 'Not Reviewed' control requirements (that can’t be tested automatically by security tools and hence require manual review), helping to account for all requirements @@ -105,9 +115,10 @@ COMMANDS attest apply Apply one or more attestation files to one or more HDF results sets attest create Create attestation files for use with `saf attest apply` ``` + ::: -### 12.4 Create Manual Attestation Data +## 12.5 Create Manual Attestation Data After someone on your team completes the manual check that is required for your security control, record that information with the help of the SAF CLI. @@ -116,11 +127,13 @@ First, look at the flags for the `saf attest create` command. ::: code-tabs @tab Command + ```sh saf attest create -h ``` @tab Output + ```sh Create attestation files for use with `saf attest apply` @@ -142,9 +155,11 @@ EXAMPLES $ saf attest create -o attestation.xlsx -t xlsx ``` + ::: -Here is an example of an attested control that we can create based on +Here is an example of an attested control that we can create based on + 1. The results we saw in Heimdall 2. Our (hypothetical) completed manual check (Let's pretend that we did check this!) @@ -160,18 +175,20 @@ Enter a control ID or enter 'q' to exit: Now, go through and add more attestations of the Not Reviewed results. You can decide if they should pass or fail as if you hypothetically did check these controls manually. Type `q` when you are done. -### 12.5 Apply the Manual Attestation Data +## 12.6 Apply the Manual Attestation Data Use the `-h` flag to learn about applying attestations. ::: code-tabs @tab Command + ```sh saf attest apply -h ``` @tab Output + ```sh Apply one or more attestation files to one or more HDF results sets @@ -191,6 +208,7 @@ EXAMPLES $ saf attest apply -i hdf1.json hdf2.json attestation.xlsx -o outputDir ``` + ::: Apply the attestation like this: @@ -199,9 +217,10 @@ Apply the attestation like this: saf attest apply -i ./results/nginx_hardened_results.json ./results/manual_attestation_results.json -o ./results/nginx_hardened_with_manual_attestations.json ``` -### 12.6 Visualize the Results - Heimdall +## 12.7 Visualize the Results - Heimdall As we have done before, + 1. Download the `nginx_hardened_with_manual_attestations.json` file. 2. Upload this file to Heimdall. 3. Click on the top left menu and toggle on the Comparison View @@ -213,4 +232,4 @@ In the example, a few manual attestations were completed, some of which were rec You can look at the details to find the attestation information captured. Expand the details for each control to view this data. -![Details on Attestations](../../assets/img/Heimdall_WithAttestations_Details.png) \ No newline at end of file +![Details on Attestations](../../assets/img/Heimdall_WithAttestations_Details.png) diff --git a/src/courses/user/13.md b/src/courses/user/13.md index 0a1d5d364..041f2b85d 100644 --- a/src/courses/user/13.md +++ b/src/courses/user/13.md @@ -6,11 +6,12 @@ author: Emily Rodriguez headerDepth: 3 --- -## 13. RedHat Example +## 13.1 RedHat Example Now it's time to put what you have learned to the test. Can you use the NGINX example to form an InSpec command for the RedHat8 docker container that is running in the Codespace environment and add it to Heimdall? We will not harden this container, just do the validation and visualization. Try to do the following: + 1. Find the profile to run - reference the [SAF validate page](https://saf.mitre.org/#/validate) 2. Form the InSpec command using the formula from section 6 - Tip: Create an informative name for your output file @@ -19,4 +20,4 @@ Try to do the following: - Tip: You can reference the README for a section on Tailoring to Your Environment 4. Run the InSpec command 5. Download the results file -6. Add your results to your uploads in Heimdall. Toggle off comparison view and select the RedHat8 in the top left menu. \ No newline at end of file +6. Add your results to your uploads in Heimdall. Toggle off comparison view and select the RedHat8 in the top left menu. diff --git a/src/courses/user/14.md b/src/courses/user/14.md index cbdc9f3df..a1890d8a2 100644 --- a/src/courses/user/14.md +++ b/src/courses/user/14.md @@ -6,21 +6,21 @@ author: Emily Rodriguez headerDepth: 3 --- -## 14. Normalize +## 14.1 Normalize -Remember the "Normalize" pillar? We skipped over it when we were doing InSpec validation because InSpec results are automatically in HDF (or Heimdall Data Format). +Remember the "Normalize" pillar? We skipped over it when we were doing InSpec validation because InSpec results are automatically in HDF (or Heimdall Data Format). ![The Normalize Capability](../../assets/img/SAF_Capabilities_Normalize.png) However, other tools provide useful security data that is not inherently in HDF. So, to make a full picture of security, we have converters to convert third party data to HDF and HDF back into other forms. -### 14.1 Convert with SAF CLI +## 14.2 Convert with SAF CLI The SAF CLI has utilies to convert files from one output to another. Take a look at the ever-growing list of compatible file types at the [SAF CLI README](https://saf-cli.mitre.org/). -### 14.2 Convert with Heimdall +## 14.3 Convert with Heimdall -However, you Heimdall can also auto-convert uploaded files in compatible formats, giving you another way to convert data and look at the whole picture at one time. +However, you Heimdall can also auto-convert uploaded files in compatible formats, giving you another way to convert data and look at the whole picture at one time. Test this out by adding sample files of other data in Heimdall. @@ -30,9 +30,9 @@ Choose some sample data to add to the full security of a theoretical software st ![Picking a Sample](../../assets/img/Heimdall_Samples_Select.png) -### 14.3 Visualize the Big Picture +## 14.4 Visualize the Big Picture -As you add all of this data into one view, you can see how the NIST 800-53 controls are more filled out as more items are covered by different types of security scans. +As you add all of this data into one view, you can see how the NIST 800-53 controls are more filled out as more items are covered by different types of security scans. ![The Tree Map](../../assets/img/Heimdall_TreeMap_Fuller.png) @@ -44,7 +44,7 @@ And in the results details, you can see what file - in other words what scan or ![Results Details from Multiple Sources](../../assets/img/Heimdall_MultiResults.png) -### 14.4 Export Data To Other Formats +## 14.5 Export Data To Other Formats This is a two-way street! There are other places security data needs to be - maybe in Splunk, eMASS, AWS Security Hub, or even just in an easy, high level diagram to show your boss. Because of this, Heimdall can also export data into different forms using the "Export" button in the top right. Try out some of these forms on your results! diff --git a/src/courses/user/15.md b/src/courses/user/15.md index 7025e7ddd..baff33b0c 100644 --- a/src/courses/user/15.md +++ b/src/courses/user/15.md @@ -1,144 +1,22 @@ --- order: 15 -next: 16.md -title: 15. Extra Info - Running InSpec with a Local Profile -author: Mo +title: 15. Next Steps +author: Emily headerDepth: 3 --- -## 15. Example running an InSpec profile using a local archive (for air-gapped target systems) -::: tip -For more information on how to install InSpec on an airgapped system use the [chef instructions](https://docs.chef.io/install_chef_air_gap/) as guidance -::: +## 15.1 Take the Class Survey -### 15.1. Prerequisites -Since a variety of different practices are used to create an air-gapped network, this guide focuses solely on the implementation of Chef software - as such, it makes the following assumptions: +Take our 9 question SAF User Class [survey](https://forms.office.com/g/UxNr3nhtcm) to give feedback to fuel class improvement. -1) You have a way to get packages to your air-gapped machines -2) Machines on your air-gapped network are able to resolve each other using DNS -3) A server’s Fully Qualified Domain Name (FQDN) is the name that will be used by other servers to access it -4) You have a private Ruby gem mirror to supply gems as needed -5) You have an artifact store for file downloads. At a minimum, it should have the following packages available: - 1) Chef Workstation - 2) Chef Infra Client - 3) Chef Supermarket - 4) An [install script](https://docs.chef.io/install_chef_air_gap/#create-an-install-script) for Chef Infra Client +## 15.2 Take the Beginner Security Automation Developer Class -### 15.2. Required cookbooks -This guide will link to the required cookbooks for each piece of software in that software’s respective section, but this is a full list of the cookbooks required to complete the entire guide: +This class is one of a set of security automation content offered by the MITRE SAF(c) team. If you found this content interesting and you want to learn more about writing InSpec profiles of your own, we encourage you to check out the Beginner Class (shown in the table of contents on the left). You'll be writing your own automated validation tests in no time! -For Chef Supermarket: +## 15.3 Check Out the Rest of MITRE SAF(c)'s Content -- [supermarket-omnibus-cookbook](https://supermarket.chef.io/cookbooks/supermarket-omnibus-cookbook) -- [chef-ingredient](https://supermarket.chef.io/cookbooks/chef-ingredient) -- [hostsfile](https://supermarket.chef.io/cookbooks/hostsfile) +MITRE SAF(c) is a large collection of tools and techniques for security automation in addition to those discussed in this class. You can find utilities and libraries to support any step of the software development lifecycle by browsing our offerings at [saf.mitre.org](https://saf.mitre.org). Note that everything offered by MITRE SAF(c) is open-source and available to use free of charge. You can also reference all of the resources listed from the class on the [Resources Page](../../resources/README.md) -### 15.3. Required Gems -The following Ruby gems are required to install private Supermarket using the supermarket-omnibus-cookbook: - -- mixlib-install -- mixlib-shellout -- mixlib-versioning -- artifactory - -These should be accessible from your Gem mirror. - -### 15.4. Create an install script -An install script is used to install Chef Infra Client when bootstrapping a new node. It simply pulls the Chef Infra Client package from your artifact store, and then installs it. For example, on Debian-based Linux systems, it would look similar to this: - -```bash -#!/bin/bash - -cd /tmp/ -wget http://packages.example.com/chef_13.2.20-1_amd64.deb -dpkg -i chef_13.2.20-1_amd64.deb -``` - -The install script should be accessible from your artifact store. - - - - - - +## 15.4 Contact Us +The MITRE SAF(c) team can be contacted at [saf@groups.mitre.org](mailto:saf@groups.mitre.org). We support U.S. government sponsors in developing new tools for the Framework and in implementing the existing ones in DevSecOps pipelines. If you have a question about how you can use any of the content you saw in this class in your own environment, we'd be happy to help. diff --git a/src/courses/user/16.md b/src/courses/user/16.md deleted file mode 100644 index 5a848baf4..000000000 --- a/src/courses/user/16.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -order: 16 -title: 16. Next Steps -author: Emily -headerDepth: 3 ---- - -## 16. Next Steps - -### 16.1 Take the Class Survey -Take our 9 question SAF User Class [survey](https://forms.office.com/g/UxNr3nhtcm) to give feedback to fuel class improvement. - -### 16.2 Take the Beginner Security Automation Developer Class -This class is one of a set of security automation content offered by the MITRE SAF(c) team. If you found this content interesting and you want to learn more about writing InSpec profiles of your own, we encourage you to check out the Beginner Class (shown in the table of contents on the left). You'll be writing your own automated validation tests in no time! - -### 16.3 Check Out the Rest of MITRE SAF(c)'s Content -MITRE SAF(c) is a large collection of tools and techniques for security automation in addition to those discussed in this class. You can find utilities and libraries to support any step of the software development lifecycle by browsing our offerings at [saf.mitre.org](https://saf.mitre.org). Note that everything offered by MITRE SAF(c) is open-source and available to use free of charge. You can also reference all of the resources listed from the class on the [Resources Page](../../resources/README.md) - -### 16.4 Contact Us -The MITRE SAF(c) team can be contacted at [saf@groups.mitre.org](mailto:saf@groups.mitre.org). We support U.S. government sponsors in developing new tools for the Framework and in implementing the existing ones in DevSecOps pipelines. If you have a question about how you can use any of the content you saw in this class in your own environment, we'd be happy to help. diff --git a/src/courses/user/Appendix A - Running InSpec In An Airgapped Environment.md b/src/courses/user/Appendix A - Running InSpec In An Airgapped Environment.md new file mode 100644 index 000000000..0e5ce3718 --- /dev/null +++ b/src/courses/user/Appendix A - Running InSpec In An Airgapped Environment.md @@ -0,0 +1,61 @@ +--- +order: 17 +title: Appendix A - Running InSpec In An Airgapped Environment +author: Mo +headerDepth: 3 +--- + +## 15.1 Running an InSpec profile using a local archive (for air-gapped target systems) + +::: tip +For more information on how to install InSpec on an air-gapped system use the [chef instructions](https://docs.chef.io/install_chef_air_gap/) as guidance +::: + +## 15.2 Prerequisites + +Since a variety of different practices are used to create an air-gapped network, this guide focuses solely on the implementation of Chef software - as such, it makes the following assumptions: + +1) You have a way to get packages to your air-gapped machines +2) Machines on your air-gapped network are able to resolve each other using DNS +3) A server’s Fully Qualified Domain Name (FQDN) is the name that will be used by other servers to access it +4) You have a private Ruby gem mirror to supply gems as needed +5) You have an artifact store for file downloads. At a minimum, it should have the following packages available: + 1) Chef Workstation + 2) Chef Infra Client + 3) Chef Supermarket + 4) An [install script](https://docs.chef.io/install_chef_air_gap/#create-an-install-script) for Chef Infra Client + +## 15.3 Required cookbooks + +This guide will link to the required cookbooks for each piece of software in that software’s respective section, but this is a full list of the cookbooks required to complete the entire guide: + +For Chef Supermarket: + +- [supermarket-omnibus-cookbook](https://supermarket.chef.io/cookbooks/supermarket-omnibus-cookbook) +- [chef-ingredient](https://supermarket.chef.io/cookbooks/chef-ingredient) +- [hostsfile](https://supermarket.chef.io/cookbooks/hostsfile) + +## 15.4 Required Gems + +The following Ruby gems are required to install private Supermarket using the supermarket-omnibus-cookbook: + +- mixlib-install +- mixlib-shellout +- mixlib-versioning +- artifactory + +These should be accessible from your Gem mirror. + +## 15.5 Create an install script + +An install script is used to install Chef Infra Client when bootstrapping a new node. It simply pulls the Chef Infra Client package from your artifact store, and then installs it. For example, on Debian-based Linux systems, it would look similar to this: + +```sh +#!/bin/bash + +cd /tmp/ +wget http://packages.example.com/chef_13.2.20-1_amd64.deb +dpkg -i chef_13.2.20-1_amd64.deb +``` + +The install script should be accessible from your artifact store. diff --git a/src/courses/user/README.md b/src/courses/user/README.md index 9f450e8a5..298d0604b 100644 --- a/src/courses/user/README.md +++ b/src/courses/user/README.md @@ -2,45 +2,45 @@ order: 1 next: 02.md title: SAF User Class -shortTitle: SAF User Class +shortTitle: 1. SAF User Class author: Aaron Lippold headerDepth: 3 --- ## 1.1 Class Overview -The purpose of this class is to gain understanding and hands-on practical use of MITRE's Security Automation Framework with a focus on automating security validation and visualization. There is a survey at the end to give feedback on the class. +The purpose of this class is to provide an understanding and hands-on practical use of MITRE's Security Automation Framework (SAF), with a focus on automating security validation and visualization. At the end of the class, there will be a survey to gather your feedback. -## 1.2 Consider your current status +## 1.2 Consider Your Current Status ::: tip Take Inventory -How is software secured and maintained in your context? Think about your situation to paint the picture for learning throughout the class. +How is software secured and maintained in your context? Reflect on your situation to enhance your learning throughout the class. ::: 1. What is your role in the security process of your organization? -2. How frequently and for how much time does the software get assessed? -3. What is the biggest challenge for maintaining and assessing software security? +2. How frequently and for how long is the software assessed? +3. What is the biggest challenge in maintaining and assessing software security? 4. What changes would improve software assessment in your context? -5. What do you want to learn from this training? +5. What do you hope to learn from this training? -## 1.3 Class Objectives: -By the end of the SAF User Class, you should be able to achieve all of the following objectives. -- Identify and locate security guidance for a software component. -- Understand the capabilities available in the main pillars of the MITRE Security Automation Framework - Plan, Harden, Validate, Normalize, Visualize. -- Define and run an InSpec profile to validate a component against security guidance. -- Visualize InSpec results and third party security tool data. -- Automatically export checklist results from a security assessment. +## 1.3 Class Objectives + +By the end of the SAF User Class, you should be able to achieve the following objectives: + +- Identify and locate security guidance for a software component. +- Understand the capabilities available in the main pillars of the MITRE Security Automation Framework: Plan, Harden, Validate, Normalize, Visualize. +- Define and run an InSpec profile to validate a component against security guidance. +- Visualize InSpec results and third-party security tool data. +- Automatically export checklist results from a security assessment. ### 1.3.1 The Lab Environment -This class will use GitHub Codespaces for a consistent environment for all students. See instructions for setting up your own lab environment [here](../../resources/05.md). +This class will use GitHub Codespaces to create a consistent environment for all students. See instructions for setting up your own lab environment [here](../../resources/05.md). ## 1.4 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. +As illustrated in the picture below, the process for developing automated security tests starts with requirements documents like SRGs, STIGs, or CIS Benchmarks, which are written in human-readable language. These documents are 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 to a platform where it can be used to make informed decisions (such as the Heimdall visualization app). +This challenge is what the [MITRE Security Automation Framework](https://saf.mitre.org) (MITRE SAF) was developed to address. It simplifies the journey from a Requirement Document to an automated test profile and back again, making it easier to navigate. ![SAF Lifecycle](../../assets/img/saf-lifecycle.png) -