404
Page not found
How did we get here?
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).
',12),m={href:"https://saf.mitre.org",target:"_blank",rel:"noopener noreferrer"},f=e("figure",null,[e("img",{src:i,alt:"The SAF Lifecycle",tabindex:"0",loading:"lazy"}),e("figcaption",null,"The SAF Lifecycle")],-1);function _(p,g){const a=r("ExternalLinkIcon");return o(),n("div",null,[d,e("p",null,[t("This challenge is what the "),e("a",m,[t("MITRE Security Automation Framework"),l(a)]),t(" 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.")]),f])}const x=s(h,[["render",_],["__file","02.html.vue"]]);export{x as default}; diff --git a/assets/02.html-H7TT4yNP.js b/assets/02.html-H7TT4yNP.js new file mode 100644 index 000000000..8b7cba9fc --- /dev/null +++ b/assets/02.html-H7TT4yNP.js @@ -0,0 +1 @@ +import{_ as o}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as s,o as n,c,d as a,e,b as h,f as t}from"./app-PAvzDPkc.js";const i={},d=t('The repository and profile are organized into two primary branches: main and TBD. The repository has a set of tags representing iterative releases of the STIG from one Benchmark major version to the next. It also has a set of releases for fixes and updates to the profile between STIG Benchmark Releases.
main branchThe main branch contains the most recent code for the profile. It may include bugs and is typically aligned with the latest patch release for the profile. This branch is primarily used for development and testing workflows for the various testing targets. For production validation, use the latest stable patch release.
v{x}r{xx} branchesReleases use Semantic Versioning (SemVer), aligning with the STIG Benchmark versioning system of Major Version and Release. The SemVer patch number is used for updates, bug fixes, and code changes between STIG Benchmark Releases for the given product. STIG Benchmarks use a Version and Release tagging pattern v{x}r{xx} - like V1R12 - and we mirror that pattern in our SemVer releases.
We don't use a specific current or latest tag. The current/latest tag for the profile and repository will always be the latest major tag of the benchmark. For example, if v1.12.3 is the latest Benchmark release from the STIG author, then the tag v1.12 will point to the v1.12.3 release of the code.
To use the current main, point directly to the GitHub repo.
Major tags point to the latest patch release of the benchmark. For example, v1.3 and v1.3.0 represent the first release of the Red Hat Enterprise Linux 8 STIG V1R3 Benchmark. The v1.12.xx tag(s) would represent the V1R12 Benchmark releases as we find bugs, fixes, or general improvements to the testing profile. This tag will point to its v{x}r{xx} counterpart.
The latest patch release always points to the major release for the profile.
For example, after releasing v1.12.0, we will point v1.12 to that patch release: v1.12.0. When an issue is found, we will fix, tag, and release v1.12.1. We will then 'move' the v1.12 tag so that it points to tag v1.12.1. This way, your pipelines can choose if they want to pin on a specific release of the InSpec profile or always run 'current'.
InSpec organizes its code into profiles. A profile is a set of automated tests that usually relates directly back to a Security Requirements Benchmark -- such as a CIS Benchmark or a Defense Information Security Agency (DISA) Security Technical Implementation Guide (STIGs) - and provides an organized structure to articulate that set of requirements using tests in code.
Profiles have two (2) required elements:
inspec.yml filecontrols directoryand four (4) optional elements:
libraries directoryfiles directoryinputs.yml fileREADME.md fileWe will be going over each of these during our class.
$ tree nginx
+ nginx
+ └── profile
+ ├── README.md
+ ├── inputs.yml
+ ├── controls
+ │ ├── V-2230.rb
+ │ └── V-2232.rb
+ ├── files
+ │ └── services-and-ports.yml
+ ├── inspec.yml
+ └── libraries
+ └── nginx_helper.rb
+control "V-13727" do
+ title "The worker_processes StartServers directive must be set properly."
+
+ desc "These requirements are set to mitigate the effects of several types of
+ denial of service attacks. Although there is some latitude concerning the
+ settings themselves, the requirements attempt to provide reasonable limits
+ for the protection of the web server. If necessary, these limits can be
+ adjusted to accommodate the operational requirement of a given system."
+
+ impact 0.5
+ tag "severity": "medium"
+ tag "gtitle": "WA000-WWA026"
+ tag "gid": "V-13727"
+ tag "rid": "SV-36645r2_rule"
+ tag "stig_id": "WA000-WWA026 A22"
+ tag "nist": ["CM-6", "Rev_4"]
+
+ tag "check": "To view the worker_processes directive value enter the
+ following command:
+ grep ""worker_processes"" on the nginx.conf file and any separate included
+ configuration files
+ If the value of ""worker_processes"" is not set to auto or explicitly set,
+ this is a finding:
+ worker_processes auto;
+ worker_processes defines the number of worker processes. The optimal value
+ depends on many factors including (but not limited to) the number of CPU
+ cores, the number of hard disk drives that store data, and load pattern. When
+ one is in doubt, setting it to the number of available CPU cores would be a
+ good start (the value “auto” will try to autodetect it)."
+
+ tag "fix": "Edit the configuration file and set the value of
+ ""worker_processes"" to the value of auto or a value of 1 or higher:
+ worker_processes auto;"
+
+ describe nginx_conf(NGINX_CONF_FILE).params['worker_processes'] do
+ it { should cmp [['auto']] }
+ end
+end
+Remember that a profile is a set of automated tests that usually relates directly back to a Security Requirements Benchmark.
Profiles have two (2) required elements:
inspec.yml filecontrols directoryand optional elements such as:
libraries directoryfiles directoryinputs.yml fileREADME.md fileInSpec can create the profile structure for you using the following command:
$ inspec init profile my_inspec_profile
+This will give you the required files along with some optional files.
$ tree my_inspec_profile
+
+ my_inspec_profile
+ ├── README.md
+ ├── controls
+ │ └── example.rb
+ └── inspec.yml
+Let's take a look at the default ruby file in the controls directory.
This example shows two tests. Both tests check for the existence of the /tmp directory. The second test provides additional information about the test. Let's break down each component.
control (line 9) is followed by the control's name. Each control in a profile has a unique name.impact (line 10) measures the relative importance of the test and must be a value between 0.0 and 1.0.title (line 11) defines the control's purpose.desc (line 12) provides a more complete description of what the control checks for.describe (lines 13 — 15) defines the test. Here, the test checks for the existence of the /tmp directory.As with many test frameworks, InSpec code resembles natural language. Here's the format of a describe block.
describe < entity > do
+ it { < expectation > }
+end
+| inspec.yml | inputs.yml |
|---|---|
| Required | Optional |
| Should not be renamed | Can be renamed |
| Needs to be at the root of the profile | Can be anywhere |
Automatically used during executioninspec exec profile1 | Needs to be passed in during executioninspec exec profile1 --input-file <path> |
| Purpose is to define default input values and profile metadata | Purpose is to override default input values with parameters for the local environments |
| Defined by the author of the profile | Defined by the user of the profile |
Before we go further, let's discuss what we mean by "security guidance" and some of its characteristics that matter to us as security (and automation!) practitioners.
Security guidance is documentation that defines what constitutes a secure configuration for a software component or category of components. It includes organizational requirements for security, best practices, and instructions on how to fix problems. It answers the important question that all developers and engineers ask when they want to secure their software -- "What counts as 'secure' for my system in the first place?"
Most software projects will (or at least should) align themselves to a particular source for security guidance and follow it as a baseline that answers this question. For example, many commercial companies (and even some civilian government agencies) use the Center for Internet Security Benchmarks (CIS Benchmarks) as their baseline, while software deployed by the US Department of Defense is required to comply with the Defense Information Systems Agency's Security Technical Implementation Guides (STIGs), broadly speaking.
There are many different types of guidance documentation available to software developers. Software vendors often publish best practices guides, administration guides, or business requirements documents to instruct their userbase on how to best make use of the product. Security guidance is ultimately just another type of guidance document for effectively using a piece of software.
Other Guidance Sources
Have you used security guidance documents from other sources besides the ones mentioned here?
Security Requirements Are Functional Requirements!
Software developers have a historical tendency to consider security as a completely separate activity from the basic process of building a software product. In a DevSecOps environment, however, security is just another functional requirement of your code.
You cannot ship code if it does not meet a functional requirement. Likewise, you cannot ship code that does not meet a security requirement!
This class content will be giving heavy focus to STIGs, since Vulcan was originally created to address pain points in the authorship process for STIG documents (which we will describe in detail a little later). We assume that most of the students who engage with this content will be working on government projects that require securing systems to "STIG standard," or that the students work for software vendors who need to write such guidance. However, the principles behind what makes a quality STIG can be applied to security guidance of all kinds, and we hope you can take the lessons here and apply them to whatever guidance you create for your software.
Many organizations that use popular secrity guidance documents as their baselines have their own specific organizational security policies which conflict with that baseline. For example, let's say that the STIG for the Red Hat 8 operating system specifies that users should have, at minimum, 15 characters in their passwords, but your company's security policy requires a minimum of 20.
Consequently, many government agencies use baseline security guidance as foundations to create their own tailored content for in-house use. In addition to Vulcan's usual workflow for creating new baselines, you can use it to ingest a published baseline document and conduct this tailoring process to create security guidance tailored to your organization.
',11),d={class:"hint-container tip"},p=e("p",{class:"hint-container-title"},"Automating Overlay Validation",-1),f={href:"https://mitre.github.io/saf-training/courses/beginner/10.html#profile-dependencies-overlays",target:"_blank",rel:"noopener noreferrer"},m=e("h2",{id:"_2-2-finding-security-guidance-documentation-baselines",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#_2-2-finding-security-guidance-documentation-baselines","aria-hidden":"true"},"#"),t(" 2.2 Finding Security Guidance Documentation Baselines")],-1),y=e("p",null,"Commonly-used security guidance is often available on the open Internet.",-1),g={href:"https://www.cisecurity.org/cis-benchmarks",target:"_blank",rel:"noopener noreferrer"},b={href:"https://public.cyber.mil/stigs/downloads/",target:"_blank",rel:"noopener noreferrer"},w=e("ul",null,[e("li",null,"DISA distributes STIGs as a set of PDFs describing metadata like a changelog and cover sheets, where the underlying STIG itself is stored as an XML document.")],-1),_=e("p",null,'Your first question when planning for securing your software component should always be "is there already published guidance documentation available for it?"',-1),v=e("h3",{id:"_2-2-1-what-do-i-do-if-there-isn-t-already-published-guidance-documentation-available-for-it",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#_2-2-1-what-do-i-do-if-there-isn-t-already-published-guidance-documentation-available-for-it","aria-hidden":"true"},"#"),t(" 2.2.1 What Do I Do If There Isn't Already Published Guidance Documentation Available For It?")],-1),S=e("p",null,[t("Similarly, if you need to secure a software component that "),e("em",null,"does not"),t(" have a published guidance document already, your best strategy is to find the next-closest guidance document and use it to inform the content you create. You can think of the process of writing security guidance as an open-book test; you should feel free to borrow the best ideas other from other baselines!")],-1),I={href:"https://public.cyber.mil/stigs/faqs/#toggle-id-11",target:"_blank",rel:"noopener noreferrer"},k=o('Therefore, where no guidance exists, use the closest reasonable baseline.
Then use Vulcan to make some. Good news; you're already reading the instructions on how to do that.
One of the overall goals of the Security Automation Framework is to get people writing quality security automation content, not just any old hardening scripts and test suites.
In formal government assessment settings, you will need to prove that you are covering particular categories of security controls with your activities. You can only do that if you build your automation content around a well-built security guidance document that itself heavily references all of your upstream requirements.
Therefore, the Planning capability of the SAF -- dealing with the selection and creation of security baselines for automation -- is a critical component of the overall framework, even though it itself is not automated.
The Plan capability comes first in the list because every other capability needs to refer back to it!
',9);function q(T,x){const a=s("ExternalLinkIcon");return r(),c("div",null,[h,e("div",d,[p,e("p",null,[t("You can check out the "),e("a",f,[t("Beginner Security Automation Developer Class"),i(a)]),t(" for examples of how to write automated validation code with InSpec that is tailored from a baseline.")])]),m,y,e("ul",null,[e("li",null,[t("CIS publishes its popular "),e("a",g,[t("Benchmarks"),i(a)]),t(" for free with registration (in PDF form, other formats require a subscription to CIS's SecureSuite)")]),e("li",null,[t("DISA publishes all STIGs (and all the rest of its security documentation materials) for free on the "),e("a",b,[t("DOD Cyber Exchange"),i(a)]),t(" public web page. "),w])]),_,v,S,e("p",null,[t("In the case of STIGs, DISA's official guidance (as per their "),e("a",I,[t("FAQ"),i(a)]),t(") states to check for a STIG for an earlier version of the same software and modify it as necessary.")]),k])}const G=n(u,[["render",q],["__file","02.html.vue"]]);export{G as default}; diff --git a/assets/03.html-3gTCNJob.js b/assets/03.html-3gTCNJob.js new file mode 100644 index 000000000..a954cbc45 --- /dev/null +++ b/assets/03.html-3gTCNJob.js @@ -0,0 +1 @@ +const e=JSON.parse(`{"key":"v-0a3647e2","path":"/courses/user/03.html","title":"3. What's the SAF?","lang":"en-US","frontmatter":{"order":3,"next":"04.md","title":"3. What's the SAF?","author":"Aaron Lippold","headerDepth":3,"description":"3. 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 ...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/user/03.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"3. What's the SAF?"}],["meta",{"property":"og:description","content":"3. 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 ..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"3. What's the SAF?\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"3. SAF Scavenger Hunt","slug":"_3-saf-scavenger-hunt","link":"#_3-saf-scavenger-hunt","children":[]}],"git":{},"readingTime":{"minutes":1.46,"words":438},"filePathRelative":"courses/user/03.md","autoDesc":true}`);export{e as data}; diff --git a/assets/03.html-3kNnUOXI.js b/assets/03.html-3kNnUOXI.js new file mode 100644 index 000000000..22a4011af --- /dev/null +++ b/assets/03.html-3kNnUOXI.js @@ -0,0 +1,119 @@ +import{_ as u}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as l,o as d,c as m,d as n,e as s,b as a,w as e,f as c}from"./app-PAvzDPkc.js";const k="/saf-training/assets/NGINX_Heimdall_Report_View-X-NIfGbI.png",v={},b=n("h2",{id:"revisiting-the-nginx-web-server-inspec-profile",tabindex:"-1"},[n("a",{class:"header-anchor",href:"#revisiting-the-nginx-web-server-inspec-profile","aria-hidden":"true"},"#"),s(" Revisiting the NGINX Web Server InSpec Profile")],-1),g=c(`InSpec is a framework which is used to validate the security configuration of a certain target. In this case, we are interested in validating that an NGINX server complies with our requirements.
First let's find our nginx container id using the docker ps command:
docker ps
+Which will return something like:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
+8bs80z6b5n9s redhat/ubi8 "/bin/bash" 2 weeks ago Up 1 hour redhat8
+8ba6b8av5n7s nginx:latest "/docker.…" 2 weeks ago Up 1 hour 80/tcp nginx
+We can then use the container name of our nginx container nginx to target the inspec validation scans at that container.
InSpec profiles are a set of automated tests that relate back to a security requirements benchmark, so the controls are always motivated by the requirements.
http_sslstream_sslmail_ssl/etc/nginx/nginx.conf- should exist as a file.root user and group.InSpec profiles consist of automated tests, that align to security requirements, written in ruby files inside the controls directory.
If you don't have my_nginx profile, run the following command to initialize your InSpec profile.
inspec init profile my_nginx
+Append the inputs sections in your profile at my_nginx/inspec.yml
name: my_nginx
+title: InSpec Profile
+maintainer: The Authors
+copyright: The Authors
+copyright_email: you@example.com
+license: Apache-2.0
+summary: An InSpec Compliance Profile
+version: 0.1.0
+supports:
+ platform: os
+
+inputs:
+ - name: nginx_version
+ type: String
+ value: 1.10.3
+
+ - name: nginx_modules
+ type: Array
+ value:
+ - http_ssl
+ - stream_ssl
+ - mail_ssl
+
+ - name: admin_users
+ type: Array
+ value:
+ - admin
+Create an inputs file in your profile at inputs-linux.yml
admin_users:
+ - admin
+ - root
+Paste the following controls in your profile at my_nginx/controls/example.rb
control 'nginx-version' do
+ impact 1.0
+ title 'NGINX version'
+ desc 'The required version of NGINX should be installed.'
+ describe nginx do
+ its('version') { should cmp >= input('nginx_version') }
+ end
+end
+
+control 'nginx-modules' do
+ impact 1.0
+ title 'NGINX modules'
+ desc 'The required NGINX modules should be installed.'
+ required_modules = input('nginx_modules')
+ describe nginx do
+ required_modules.each do |required_module|
+ its('modules') { should include required_module }
+ end
+ end
+end
+
+control 'nginx-conf-file' do
+ impact 1.0
+ title 'NGINX configuration file'
+ desc 'The NGINX config file should exist.'
+ describe file('/etc/nginx/nginx.conf') do
+ it { should be_file }
+ end
+end
+
+control 'nginx-conf-perms' do
+ impact 1.0
+ title 'NGINX configuration permissions'
+ desc 'The NGINX config file should owned by root, be writable only by owner, and not writeable or and readable by others.'
+ describe file('/etc/nginx/nginx.conf') do
+ it { should be_owned_by 'root' }
+ it { should be_grouped_into 'root' }
+ it { should_not be_readable.by('others') }
+ it { should_not be_writable.by('others') }
+ it { should_not be_executable.by('others') }
+ end
+end
+
+control 'nginx-shell-access' do
+ impact 1.0
+ title 'NGINX shell access'
+ desc 'The NGINX shell access should be restricted to admin users.'
+ non_admin_users = users.shells(/bash/).usernames
+ describe "Shell access for non-admin users" do
+ it "should be removed." do
+ failure_message = "These non-admin should not have shell access: #{non_admin_users.join(", ")}"
+ expect(non_admin_users).to be_in(input('admin_users')), failure_message
+ end
+ end
+end
+To run inspec exec on the target, ensure that you are in the directory that has my_nginx profile.
inspec exec my_nginx -t docker://nginx --input-file inputs-linux.yml --reporter cli json:my_nginx_results.json
+Let's take a look at the default control file, controls/example.rb.
title 'sample section'
+
+# you can also use plain tests
+describe file('/tmp') do
+ it { should be_directory }
+end
+
+# you add controls here
+control 'tmp-1.0' do # A unique ID for this control
+ impact 0.7 # The criticality, if this control fails.
+ title 'Create /tmp directory' # A human-readable title
+ desc 'An optional description...'
+ describe file('/tmp') do # The actual test
+ it { should be_directory }
+ end
+end
+Tip for developing profiles
When creating new profiles use the existing example file as a template
This example shows two tests. Both tests check for the existence of the /tmp directory. The second test provides additional information about the test. Let's break down each component.
control (line 9) is followed by the control's name. Each control in a profile has a unique name.impact (line 10) measures the relative importance of the test and must be a value between 0.0 and 1.0.title (line 11) defines the control's purpose.desc (line 12) provides a more complete description of what the control checks for.describe (lines 13 — 15) defines the test. Here, the test checks for the existence of the /tmp directory.In Ruby, the do and end keywords define a block. An InSpec control always contains at least one describe block. However, a control can contain many describe blocks.
As with many test frameworks, InSpec code resembles natural language. Here's the format of a describe block.
describe <entity> do
+ it { <expectation> }
+end
+An InSpec test has two main components: the subject to examine and the subject's expected state. Here, <entity> is the subject you want to examine, for example, a package name, service, file, or network port. The <expectation> specifies the desired result or expected state, for example, that a port should be open (or perhaps should not be open.)
Let's take a closer look at the describe block in the example.
describe file('/tmp') do
+ it { should be_directory }
+end
+Because InSpec resembles human-readable language, you might read this test as "/tmp should be a directory." Let's break down each component.
fileNote
If you're familiar with Chef, you know that a resource configures one part of the system. InSpec resources are similar.
itThe it statement validates one of your resource's features. A describe block contains one or more it statements. it enables you to test the resource itself. You'll also see its, which describes some feature of the resource, such as its mode or owner. You'll see examples of both it and its shortly.
it vs. its
Important! Just like in English grammar, pay attention to the difference between the thing (it) and the possessive word (its).
it is used to describe an action or the expected behavior of the subject/resource in question.
e.g. it { should be_owned_by 'root' }
its is used to specify the expectation(s) of an attribute of the subject/resource.
e.g. its("signal") { should eq "on" }
shouldshould describes the expectation. should asserts that the condition that follows should be true. Alternatively, should_not asserts that the condition that follows should not be true. You'll see examples of both shortly.
be_directoryA and D are valid InSpec profiles!
INVALID PROFILES:
VALID PROFILES:
TIP: inspec check
To see if you have a valid InSpec profile, you can run inspec check <path-to-inspec-profile-folder>
INSPEC_CONTROL: Specifies which single control to run in the bundle exec kitchen verify phase, useful for testing and debugging a single requirement. noneKITCHEN_LOCAL_YAML: Specifies the target testing environment you want to use to run and validate the profile. noneVANILLA_CONTAINER_IMAGE: Specifies the Docker container image you consider 'not hardened' (used by kitchen.container.yml). registry.access.redhat.com/ubi8/ubi:8.9-1028HARDENED_CONTAINER_IMAGE: Specifies the Docker container image you consider 'hardened' (used by kitchen.container.yml). registry1.dso.mil/ironbank/redhat/ubi/ubi8ruby --version.bundle exec inspec --version.bundle exec kitchen version.aws-cli is correctly configured by running aws s3 ls (or your preferred test command for AWS CLI).bundle exec inspec --version.docker pull https://repo1.dso.mil/dsop/redhat/ubi/ubi8.The main pillars are
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.
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.
Some notable tools within the Security Automation Framework are Vulcan, the SAF CLI, and Heimdall.
A Security Technical Implementation Guide (STIG) is a set of requirements imposed by the US Department of Defense and implementation instructions for those requirements that are specific to a paticular software component. The components can be any piece of technology that needs a secure configuration -- operating systems, webservers, application runtimes, routers, and so on.
STIGs are published by the Defense Information Systems Agency (DISA), but they're usually written by software vendors, which naturally have the most domain knowledge about how to secure their products. DISA then peer reviews the vendor's draft content to ensure it meets its rigorous standards. We'll describe the process for working with DISA to formally publish a STIG later on.
STIGs are also expected to stay up-to-date alongside the software component they describe. STIGs must be updated by the authors and released any time there is a serious change in the software component the STIG describes. Complicated STIGs for widely-used and often-updated components may be updated multiple times a year.
Are STIGs Familiar?
Have you ever been required to configure an application or system to STIG-standard before?
STIGs are created based off of high-level, general guidance documents called Security Requirements Guides (SRGs), also published by DISA. SRGs describe DOD-selected security requirements for entire categories of software components, and all STIG requirements are essentially sets of instructions for how to get a particular component to comply with a general SRG (or even a set of SRGs, for complex systems). STIGs are instructions for security that can be followed even by people who are not experts in the technology in question.
How much STIG are we talking?
STIGs can include hundreds of individual requirements depending on the complexity of the system being configured. At time of writing, the Windows Server 2019 STIG included 303 controls.
We need a way to track and manage all of these easily!
For example, there is an SRG that covers operating systems in general (the aptly-named "General Purpose Operating System Security Requirements Guide"). That piece of guidance is full of requirements for an operating system -- any operating system -- to be considered reasonably secure. There is a requirement in that SRG (SRG ID: SRG-OS-000021-GPOS-00005) which states that "The operating system must enforce the limit of three consecutive invalid logon attempts by a user during a 15-minute time period."
This requirement is saying that an attacker shouldn't be able to brute force a user's password by throwing a high number of guesses at the system. Simple enough, right?
However, this guidance isn't particularly useful unless we know how to implement it on a particular operating system. That's where the STIG comes in. The STIG for, say, Red Hat 8 ("Red Hat Enterprise Linux 8 STIG") has its own requirement for limiting consecutive logon attempts (Rule ID: SV-230334r627750_rule) that cites the relevant SRG IDs that it satisfies. That STIG rule tells us exactly how to configure Red Hat to satisfy this requirement, down to which configuration files we need to edit.
You can think of the process of STIG authorship as distilling the high-level, general requirements of an SRG into a checklist that anybody can follow to lock down their component.
STIGs are ideally created by a team of subject matter experts on a particular piece of software, all of whom work together to close the gap between the SRG and their shiny new STIG.
Published directives from the DOD's Chief Information Officer (DOD CIO) describe the overall Risk Management Framework for DOD Systems (DOD RMF). The DOD RMF requires all information systems across the DOD to be categorized according to how much risk they represent to the organization if compromised. It also requires system owners to select controls from the National Institute of Standards and Technology's (NIST) security control families.
',17),m={class:"hint-container note"},p=e("p",{class:"hint-container-title"},"NIST Control Families",-1),f={href:"https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final",target:"_blank",rel:"noopener noreferrer"},g=o('To speed up the process of control selection, DISA created and published the Control Correlation Identifiers (CCIs), which describe actions that can be taken to cover the NIST security control families. CCIs are a bridge between the extremely high-level policy documents that govern the whole DOD and the low-level documents (i.e. STIGs) that actually tell people how to implement that policy.
DISA also publishes the SRGs, which describe subsets of CCIs that apply to general categories of information systems. This means that individual system owners do not have to figure out on their own which control families need to be covered for their system; they can instead say "I am deploying a router, so I must cover the requirements selected in the Router SRG."
As described before, an SRG can then be tailored into STIGs that give security guidance for individual pieces of software. The full chain of requirements to implementation therefore looks like this:
The good news is that you, the STIG content author, don't have to worry about SRGs or control selections all that much; the whole point of all the good work that DISA has done is that most of these mappings have been done for you. You are responsible for the last leg of the journey -- you know your requirements from the SRG, and now you need to figure out how to implement them as a configuration baseline.
',6);function y(S,w){const s=n("ExternalLinkIcon");return a(),r("div",null,[d,e("div",m,[p,e("p",null,[t("You may be familiar with the control families from "),e("a",f,[t("NIST Special Publication 800-53"),l(s)]),t(", because almost all US Government agencies (and quite a few companies) use them as the authoritative list that defines what security controls are.")])]),g])}const I=i(u,[["render",y],["__file","03.html.vue"]]);export{I as default}; diff --git a/assets/03.html-yprIC4go.js b/assets/03.html-yprIC4go.js new file mode 100644 index 000000000..4be3693d1 --- /dev/null +++ b/assets/03.html-yprIC4go.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-7858d005","path":"/courses/profile-dev-test/03.html","title":"Environment Setup","lang":"en-US","frontmatter":{"order":3,"next":"04.md","title":"Environment Setup","author":"Aaron Lippold","description":"RVM, or another Ruby Management Tool; Ruby v3 or higher; Git; VS Code or another IDE; Docker (if you want to test hardened and non-hardened containers); AWS CLI; AWS Account; 1....","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/profile-dev-test/03.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Environment Setup"}],["meta",{"property":"og:description","content":"RVM, or another Ruby Management Tool; Ruby v3 or higher; Git; VS Code or another IDE; Docker (if you want to test hardened and non-hardened containers); AWS CLI; AWS Account; 1...."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Environment Setup\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[],"git":{},"readingTime":{"minutes":1.56,"words":468},"filePathRelative":"courses/profile-dev-test/03.md","autoDesc":true}');export{e as data}; diff --git a/assets/04.html-7Ib1xBlQ.js b/assets/04.html-7Ib1xBlQ.js new file mode 100644 index 000000000..3f6315628 --- /dev/null +++ b/assets/04.html-7Ib1xBlQ.js @@ -0,0 +1 @@ +const t=JSON.parse(`{"key":"v-0beb2081","path":"/courses/user/04.html","title":"4. Getting Started - Plan","lang":"en-US","frontmatter":{"order":4,"next":"05.md","title":"4. Getting Started - Plan","author":"Aaron Lippold","headerDepth":3,"description":"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 ide...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/user/04.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"4. Getting Started - Plan"}],["meta",{"property":"og:description","content":"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 ide..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"4. Getting Started - Plan\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"4. Start with Planning","slug":"_4-start-with-planning","link":"#_4-start-with-planning","children":[{"level":3,"title":"4.1 Identify your stack of components for the system","slug":"_4-1-identify-your-stack-of-components-for-the-system","link":"#_4-1-identify-your-stack-of-components-for-the-system","children":[]},{"level":3,"title":"4.2 What is the guidance?","slug":"_4-2-what-is-the-guidance","link":"#_4-2-what-is-the-guidance","children":[]},{"level":3,"title":"4.3. Content libraries for software components","slug":"_4-3-content-libraries-for-software-components","link":"#_4-3-content-libraries-for-software-components","children":[]},{"level":3,"title":"4.4. What if there is no content for a software component?","slug":"_4-4-what-if-there-is-no-content-for-a-software-component","link":"#_4-4-what-if-there-is-no-content-for-a-software-component","children":[]}]}],"git":{},"readingTime":{"minutes":1.71,"words":513},"filePathRelative":"courses/user/04.md","autoDesc":true}`);export{t as data}; diff --git a/assets/04.html-DtdjMdcP.js b/assets/04.html-DtdjMdcP.js new file mode 100644 index 000000000..d4cdafca5 --- /dev/null +++ b/assets/04.html-DtdjMdcP.js @@ -0,0 +1 @@ +const e=JSON.parse(`{"key":"v-27518a08","path":"/courses/beginner/04.html","title":"4. How to Get Started - InSpec Commands & Docs","lang":"en-US","frontmatter":{"order":4,"next":"05.md","title":"4. How to Get Started - InSpec Commands & Docs","author":"Aaron Lippold","description":"InSpec Commands and Documentation Before we test our NGINX configuration, let's take a look at the InSpec commands and documentation we can use to write tests. How to Run InSpec...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/beginner/04.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"4. How to Get Started - InSpec Commands & Docs"}],["meta",{"property":"og:description","content":"InSpec Commands and Documentation Before we test our NGINX configuration, let's take a look at the InSpec commands and documentation we can use to write tests. How to Run InSpec..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"4. How to Get Started - InSpec Commands & Docs\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"InSpec Commands and Documentation","slug":"inspec-commands-and-documentation","link":"#inspec-commands-and-documentation","children":[{"level":3,"title":"How to Run InSpec","slug":"how-to-run-inspec","link":"#how-to-run-inspec","children":[]},{"level":3,"title":"How to Write InSpec","slug":"how-to-write-inspec","link":"#how-to-write-inspec","children":[]},{"level":3,"title":"The InSpec shell","slug":"the-inspec-shell","link":"#the-inspec-shell","children":[]},{"level":3,"title":"Entering the InSpec shell","slug":"entering-the-inspec-shell","link":"#entering-the-inspec-shell","children":[]},{"level":3,"title":"Using the InSpec Shell","slug":"using-the-inspec-shell","link":"#using-the-inspec-shell","children":[]},{"level":3,"title":"Exploring Resources","slug":"exploring-resources","link":"#exploring-resources","children":[]}]}],"git":{},"readingTime":{"minutes":7.37,"words":2212},"filePathRelative":"courses/beginner/04.md","autoDesc":true}`);export{e as data}; diff --git a/assets/04.html-QTDREr1e.js b/assets/04.html-QTDREr1e.js new file mode 100644 index 000000000..25117bc2e --- /dev/null +++ b/assets/04.html-QTDREr1e.js @@ -0,0 +1 @@ +import{_ as n}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as s,o as a,c as l,d as e,e as r,b as t}from"./app-PAvzDPkc.js";const c={},d=e("h1",{id:"vulcan-resources",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#vulcan-resources","aria-hidden":"true"},"#"),r(" Vulcan Resources")],-1),i=e("h2",{id:"docs",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#docs","aria-hidden":"true"},"#"),r(" Docs")],-1),_={href:"https://saf.mitre.org/docs/vulcan-install",target:"_blank",rel:"noopener noreferrer"},h={href:"https://github.com/mitre/vulcan",target:"_blank",rel:"noopener noreferrer"},u={href:"https://github.com/orgs/mitre/projects/7",target:"_blank",rel:"noopener noreferrer"},f=e("h2",{id:"stig-resources",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#stig-resources","aria-hidden":"true"},"#"),r(" STIG resources")],-1),m=e("li",null,[e("a",{href:"../assets/downloads/U_Vendor_STIG_Process_Guide_V4R1_20220815.pdf"},"Vendor STIG Process Guide")],-1),p={href:"https://dl.dod.cyber.mil/wp-content/uploads/stigs/pdf/U_Vendor_STIG_Intent_Form.pdf",target:"_blank",rel:"noopener noreferrer"},g={href:"https://www.vmware.com/content/dam/digitalmarketing/vmware/en/pdf/docs/vmware-stig-program-overview.pdf",target:"_blank",rel:"noopener noreferrer"};function v(V,b){const o=s("ExternalLinkIcon");return a(),l("div",null,[d,i,e("ol",null,[e("li",null,[e("a",_,[r("Vulcan full documentation"),t(o)])]),e("li",null,[e("a",h,[r("Vulcan GitHub"),t(o)]),r(" -- Feel free to leave us a feature request!")]),e("li",null,[e("a",u,[r("Vulcan Project roadmap"),t(o)])])]),f,e("ol",null,[m,e("li",null,[r("DISA's "),e("a",p,[r("Vendor STIG Intent Form"),t(o)]),r(". Used to formally start the Vendor STIG process.")]),e("li",null,[r("VMWare's "),e("a",g,[r("STIG Program Overview"),t(o)]),r(". A good primer on terms and process for STIGs.")])])])}const k=n(c,[["render",v],["__file","04.html.vue"]]);export{k as default}; diff --git a/assets/04.html-RCsMUVdJ.js b/assets/04.html-RCsMUVdJ.js new file mode 100644 index 000000000..0002bfbf9 --- /dev/null +++ b/assets/04.html-RCsMUVdJ.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-28c6a192","path":"/resources/04.html","title":"Vulcan Resources","lang":"en-US","frontmatter":{"index":true,"icon":"page","title":"Vulcan Resources","author":"Will Dower","headerDepth":3,"description":"Docs 1. Vulcan full documentation (https://saf.mitre.org/docs/vulcan-install) 2. Vulcan GitHub (https://github.com/mitre/vulcan) -- Feel free to leave us a feature request! 3. V...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/resources/04.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Vulcan Resources"}],["meta",{"property":"og:description","content":"Docs 1. Vulcan full documentation (https://saf.mitre.org/docs/vulcan-install) 2. Vulcan GitHub (https://github.com/mitre/vulcan) -- Feel free to leave us a feature request! 3. V..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Will Dower"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Vulcan Resources\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Will Dower\\"}]}"]]},"headers":[{"level":2,"title":"Docs","slug":"docs","link":"#docs","children":[]},{"level":2,"title":"STIG resources","slug":"stig-resources","link":"#stig-resources","children":[]}],"git":{},"readingTime":{"minutes":0.3,"words":89},"filePathRelative":"resources/04.md","autoDesc":true}');export{e as data}; diff --git a/assets/04.html-Ri1HP-KJ.js b/assets/04.html-Ri1HP-KJ.js new file mode 100644 index 000000000..10e328dd1 --- /dev/null +++ b/assets/04.html-Ri1HP-KJ.js @@ -0,0 +1 @@ +import{_ as i}from"./SAF_Site_Harden-697HRqN7.js";import{_ as s}from"./plugin-vue_export-helper-x3n3nnut.js";import{r,o as l,c,a as h,d as e,e as t,b as n,f as o}from"./app-PAvzDPkc.js";const d="/saf-training/assets/SAF_Capabilities_Plan-1kgo-5aU.png",f="/saf-training/assets/SAF_Home-Fvv5vIy3.png",u="/saf-training/assets/SAF_Site_Validate-MMJEjefb.png",p={},m=o('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.
Your software system is composed of multiple components. i.e., Cloud Services, Virtualization Platforms, Operating Systems, Databases, Application Logic, and Web Servers.
The first step of any assessment is identifying the components for the system you are assessing.
',6),g=o('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.
As you saw in the previous section's SAF Site scavenger hunt, 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.
Go to the SAF site 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:
Once you've set up the necessary tools, you're ready to run the profile. The testing environment is determined by Test Kitchen using environment variables.
There are four testing environments to choose from:
The specifics of each environment's configuration are detailed in the following sections.
For each of these examples, you need to update the KITCHEN_LOCAL_YAML environment variable to point to the correct kitchen.<TEST-TARGET>.yaml file. Ensure that any required supporting environment settings, environment variables, profiles, etc., are in place. See Environment Variables and Testing Target Environments for more information.
Test Kitchen has four major steps: create, converge, verify, and destroy. Use these stages to create, configure, run tests, and destroy your testing target. When starting your testing, it's useful to run each of these in turn to ensure your environment, Test Kitchen, and credentials are set up and working correctly.
create:create stage sets up your testing instance and prepares the necessary login credentials and other components so you can use your testing target.converge:converge stage runs the provisioner of the Test Kitchen suite - the configuration management code set up in the test suite. This could be any configuration management script, such as Ansible, Chef, Puppet, Terraform, Shell, etc., that you and your team use.verify:verify stage runs the actual InSpec profile against your testing target. Test Kitchen supports multiple testing frameworks, which are well documented on the project website.destroy:destroy stage tears down your test target - like an EC2 instance, Docker container, or Vagrant Box.You can also isolate which of the 'target suites' - either vanilla or hardened in our case - to run by appending either hardened or vanilla to the end of your Test Kitchen command. For example, bundle exec kitchen verify will run the Test Kitchen stages all the way through verify on both the hardened and vanilla suites. However, if you say, bundle exec kitchen verify vanilla, it will only run it on the vanilla test target.
login: Allows you to easily log in using the credentials created when you ran bundle exec kitchen create.test: Runs all the Test Kitchen stages starting with create through destroy to easily allow you to go through a full clean test run.Local resources are those that exist only in the profile in which they are developed. Local resources are put in the libraries directory:
$ tree examples/profile
+examples/profile
+...
+├── libraries
+│ └── custom_resource.rb
+Note that the libraries directory is not created by default within a profile when we use inspec init. We need to create the directory ourselves.
Once you create and populate a custom resource Ruby file inside the libraries directory, it can be utilized inside your local profile just like the core resources.
Resources may be added to profiles in the libraries folder:
$ tree examples/profile
+examples/profile
+...
+├── libraries
+│ └── gordon_config.rb
+The smallest possible InSpec resource takes this form:
class Tiny < Inspec.resource(1)
+ name 'tiny'
+end
+This is easy to write, but not particularly useful for testing.
Resources are written as a regular Ruby class, which inherits from the base inspec.resource class. The number (1) specifies the version this resource plugin targets. As Chef InSpec evolves, this interface may change and may require a higher version.
In addition to the resource name, the following attributes can be configured:
name - Identifier of the resource (required)desc - Description of the resource (optional)example - Example usage of the resource (optional)supports - (Chef InSpec 2.0+) Platform restrictions of the resource (optional)The following methods are available to the resource:
inspec - Contains a registry of all other resources to interact with the operating system or target in general.skip_resource - A resource may call this method to indicate that requirements aren’t met. All tests that use this resource will be marked as skipped.The following example shows a full resource using attributes and methods to provide simple access to a configuration file:
class GordonConfig < Inspec.resource(1)
+ name 'gordon_config'
+
+ # Restrict to only run on the below platforms (if none were given, all OS's supported)
+ supports platform_family: 'fedora'
+ supports platform: 'centos', release: '6.9'
+ # Supports \`*\` for wildcard matcher in the release
+ supports platform: 'centos', release: '7.*'
+
+ desc '
+ Resource description ...
+ '
+
+ example '
+ describe gordon_config do
+ its("signal") { should eq "on" }
+ end
+ '
+
+ # Load the configuration file on initialization
+ def initialize(path = nil)
+ @path = path || '/etc/gordon.conf'
+ @params = SimpleConfig.new( read_content )
+ end
+
+ # Expose all parameters of the configuration file.
+ def method_missing(name)
+ @params[name]
+ end
+
+ private
+
+ def read_content
+ f = inspec.file(@path)
+ # Test if the path exist and that it's a file
+ if f.file?
+ # Retrieve the file's contents
+ f.content
+ else
+ # If the file doesn't exist, skip all tests that use gordon_config
+ raise Inspec::Exceptions::ResourceSkipped, "Can't read config at #{@path}"
+ end
+ end
+end
+Let's break down each component of the resource.
The class is where the Ruby file is defined.
The name is how we will call upon this resource within our controls, in the example above that would be gordon_config.
Supports are used to define or restrict the Ruby resource to work in specific ways, as shown in the example above that is used to restrict our class to specific platforms.
A simple description of the purpose of this resource.
A simple use case example. The example is usually a describe block using the resource, given as a multi-line comment.
An initilize method is required if your resource needs to be able to accept a parameter when called in a test (e.g. file('this/path/is/a/parameter'))
These methods return data from the resource so that you can use it in tests.
`,34);function g(y,w){const t=i("RouterLink"),a=i("ExternalLinkIcon");return r(),l("div",null,[u,h,m,s("p",null,[e("As you saw in the "),n(t,{to:"/courses/beginner/"},{default:c(()=>[e("Beginner class")]),_:1}),e(", when writing InSpec code, many core resources are available because they are included in the main InSpec code base.")]),s("ul",null,[s("li",null,[e("You can "),s("a",v,[e("explore the core InSpec resources"),n(a)]),e(" to existing resources.")]),s("li",null,[e("You can also "),s("a",k,[e("examine the source code"),n(a)]),e(" to see what's available. For example, you can see how "),b,e(" and other InSpec resources are implemented.")])]),f])}const I=o(d,[["render",g],["__file","04.html.vue"]]);export{I as default}; diff --git a/assets/04.html-m68ZwoFB.js b/assets/04.html-m68ZwoFB.js new file mode 100644 index 000000000..f759d38e0 --- /dev/null +++ b/assets/04.html-m68ZwoFB.js @@ -0,0 +1,235 @@ +import{_ as u}from"./plugin-vue_export-helper-x3n3nnut.js";import{r,o as d,c as p,d as e,e as n,b as l,w as s,f as c}from"./app-PAvzDPkc.js";const m={},b=e("h2",{id:"inspec-commands-and-documentation",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#inspec-commands-and-documentation","aria-hidden":"true"},"#"),n(" InSpec Commands and Documentation")],-1),h=e("p",null,"Before we test our NGINX configuration, let's take a look at the InSpec commands and documentation we can use to write tests.",-1),v=e("h3",{id:"how-to-run-inspec",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#how-to-run-inspec","aria-hidden":"true"},"#"),n(" How to Run InSpec")],-1),k=e("code",null,"inspec exec",-1),g={href:"https://mitre.github.io/saf-training/courses/user/06.html",target:"_blank",rel:"noopener noreferrer"},_=c(`inspec exec WHERE_IS_THE_PROFILE -t WHAT_IS_THE_TARGET --more-flags EXTRA_STUFF --reporter WHAT_SHOULD_INSPEC_DO_WITH_THE_RESULTS
+You see file and other resources listed.
Earlier, we saw this describe block:
describe file('/tmp') do
+ it { should be_directory }
+end
+The InSpec shell understands the structure of blocks. This enables you to run mutiline code. As an example, run the entire describe block like this which will run the entire block of code in the InSpec Shell and return the result.
In practice, you don't typically run controls interactively this way for day to day use, but it is a great way to test out your ideas, find bugs or validate your approach before running a scan in its entirety on a target of evaluation.
What is the difference between InSpec and Ruby?
Inspec is a Domain Specific Language (DSL) on top of Ruby. In other words, InSpec is built on the Ruby programming language. For example, InSpec matchers are implemented as Ruby methods.
file exampleLet's use the InSpec shell to explore some resources in InSpec. We will start with one of the most common elements on the system: a directory. In the InSpec Shell call the file.directory? method.
file('/tmp').directory?
+inspec> file('/tmp').directory?
+ => true
+This will return true, since /tmp is a directory on the system and exists on your workstation container.
To make the tests easier to read, the InSpec language uses "syntactic sugar" to turn methods into English-like phrases. For example, the Ruby language contains boolean methods ending in ? which evaluate to true or false (nil is a type of false). InSpec changes the syntax of these methods to include be_ before the method rather than ? after the method to make it more readable. For example, to check if a directory exists, Ruby would traditionally use directory? while InSpec uses be_directory.
nginx exampleNow's a good time to define the requirements for our NGINX configuration. Let's say that you require:
1. NGINX version 1.10.3 or later.\n2. The following NGINX modules should be installed:\n * `http_ssl`\n * `stream_ssl`\n * `mail_ssl`\n3. The NGINX configuration file - `/etc/nginx/nginx.conf`- should exist as a file.\n4. The NGINX configuration file should:\n * be owned by the `root` user and group.\n * not be readable, writeable, or executable by others.\n5. The NGINX shell access should be restricted to admin users.\nIn the next section, we will start writing controls for my_nginx profile.
Let's see what resources are available for nginx.
Run help resources a second time to identify InSpec's provided two built-in resources to support NGINX – nginx and nginx_conf.
As you can see we get false - since nginx is not installed on your runner.
We can instead run InSpec shell commands against the target that does have NGINX installed to see what results we find.
To do so, first start by exiting your InSpec shell session.
exit
+Run docker ps to see the running docker containers in your development lab environment that we can test:
To check whether the NGINX configuration file exists as a file, we want to test attributes of the file itself, so we use the file resource.
Use the file resource to check whether the NGINX configuration file is owned by root and is not readable, writeable, or executable by others. You saw earlier how the file resource provides the readable, writeable, and executable methods. You would also see that the file resource provides the owned_by and grouped_into methods.
Exit the InSpec shell session with the exit command.
exit
+Each STIG is a set of requirements and implementation guidance on how to meet them (which we will abbreviate as just a "STIG requirement"). Let's dive into the technical details that make up a STIG requirement.
Each requirement in a STIG will contain the following fields.
These fields are imported unchanged from the SRG, so we do not need to worry about them too much as STIG content authors.
These are the fields we will be responsible for.
Check and Fix
Much of your time writing STIGs will be researching how to fill out the Check and the Fix fields, since those comprise the bulk of the information in STIGs that is not copied from the SRG.
See DISA's Vendor STIG Process Guide section 4.1 for further details on these fields.
A piece of security guidance is not a formal STIG until it has been peer reviewed and published by DISA itself. Before publishing, your security guidance is considered STIG-ready content.
If all you are looking for is an Authority to Operate for the fancy system your team is making for your project, you may not need to undergo the formal process for peer reviewing and publishing your STIG-ready content through DISA. STIG-ready content, since it is tightly aligned to the requirements in its source SRG, is on its own an excellent foundation to use for security automation activities, such as building out automated hardening scripts and test suites.
If you are a software developer creating a product that you expect will be used by other projects within the DOD, it will likely be beneficial to you to formally publish a STIG for your product. Doing so will greatly lower the effort required for your software to be implemented by the Department -- you figure out security once, and no one else will have to reinvent the wheel.
',6),I=o('Vulcan exists because writing STIGs is very time-consuming for reasons that rarely have to do with actual security research.
STIG Authorship Challenges
Have you ever been part of an effort to write a STIG before?
Before Vulcan, vendors could expect to take anywhere from 18 months to 2 years to develop a STIG for a reasonably complex piece of software. An unacceptable amount of that time was locked up in document management activities -- simply keeping the author team all up-to-date with each other's work. STIG documents were often created using spreadsheets of requirements emailed back and forth between the authorship team.
Warning
If you've ever spent hours editing a document only to realize that the rest of your team was editing a completely separate version, take that feeling and multiply it by 300 requirements.
The MITRE SAF© team, acting in collaboration with VMWare (which maintains roughly four dozen STIGs for its software components, at time of writing) and DISA, built the Vulcan webapp to move the STIG authorship workflow into the browser.
Vulcan adds in systems for:
VMWare has reported that with experienced authors, Vulcan cut down the time to write a STIG down to a few weeks. It also makes the problem of tracking and managing content over time much easier.
Software developers tend to ask themselves this frequently.
Why bother creating STIGs in the first place if it takes this much effort? Even with Vulcan speeding things up and taking on many management functions, creating a STIG takes quite a bit of time. Furthermore, there is a time cost inherent to maintaining the STIG over time, because every major change to a software component requires an update to the STIG as per DOD policy. Why go through the headache?
Recall that if you want to use your software anywhere under the Department of Defense's umbrella (and even in many civilian agencies!) you are required to comply with the Security Requirements Guides that apply to your system in order to recieve your Authority to Operate.
Taking the long view, the easiest way to pass security assessments is to write up baseline security guidance early and stick to it. That is, you have to follow the SRG anyway, and STIGs are ultimately just checklists on how to make your software follow the SRG. You're just writing all the security documentation you'd have to keep around anyway into one place.
',15);function T(G,v){const n=a("ExternalLinkIcon"),r=a("Mermaid");return l(),h("div",null,[d,e("div",m,[p,f,g,e("ul",null,[e("li",null,[t("STIG Viewer: DISA's own application for STIG examination. You can download it fromo the "),e("a",y,[t("DOD Cyber Exchange"),i(n)]),t(" just like the STIGs themselves.")]),w,e("li",null,[e("a",S,[t("Heimdall"),i(n)]),t(" (coming soon!): The MITRE SAF team is working to implement all of STIG Viewer's functionality into the Heimdall application, so that policy documents and scan data can be examined by the same application.")])])]),b,i(r,{id:"mermaid-126",code:"eJxlUk1v2zAMvedXcNlhLTBjzUeTNIcVaz0XOWwrlmxFYfSg2EwsTBYzSZ7h/fpRruVm6U2PfCQfHxVF0cBJp3AJDwVqWBdUqRxWkJAphZJ/Eb40sN6s7qLvKPIGbkk71O56kJHeyf1yAOAKLLl+KywG9FMYKbYKrc8DHIwshWluSZFZwvBtMkomyXTY5pTU2CcW8/hzkgwHXtZOUZ0VwjjY3LRMmY/O0phYnEbMwRFkVB5UA7V0BcTfYjD4u5KG52tnr5/Ou6px+khVX5NTVnkCFFRDw4laKsVRFi7tU1cySTdEvFH+3mekA6GbWjQhPU2/er7Qv+wblpOTfuegFtzUUeBcpo9o22SIzNLhg5EOwWJW8aOBfSVzoTMEYXtdwknScPba8vNhaDT/z4biqCEbUlbav3jTLfflG/inwcoilC8TX9xZeJ2h8xUvFt6ji9RPFpmDeLX+9NxxLzXs2q/Rfgq+LGVo+/rRJL2vtkrawq90ROwJ02MC22+Aav52YYG7Tt+HG7QO7g1PlzygjWPf5DL9oXM0e3pWdkA0vOIfiXVPgSj66K9wgqfhgh2ehIN3eByud4LHHZ6HE3R4EVzs8Oiid6+LzE4qroLVJ/mZx363fsnQMmhsGa2Hg3/tXReD"}),I])}const x=s(u,[["render",T],["__file","04.html.vue"]]);export{x as default}; diff --git a/assets/04.html-xZbjtynr.js b/assets/04.html-xZbjtynr.js new file mode 100644 index 000000000..af5edf441 --- /dev/null +++ b/assets/04.html-xZbjtynr.js @@ -0,0 +1 @@ +const e=JSON.parse(`{"key":"v-7a0da8a4","path":"/courses/profile-dev-test/04.html","title":"Test your Test Environment","lang":"en-US","frontmatter":{"order":4,"next":"05.md","title":"Test your Test Environment","author":"Aaron Lippold","description":"Once you've set up the necessary tools, you're ready to run the profile. The testing environment is determined by Test Kitchen using environment variables. There are four testin...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/profile-dev-test/04.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Test your Test Environment"}],["meta",{"property":"og:description","content":"Once you've set up the necessary tools, you're ready to run the profile. The testing environment is determined by Test Kitchen using environment variables. There are four testin..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Test your Test Environment\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"Kitchen Stages","slug":"kitchen-stages","link":"#kitchen-stages","children":[]}],"git":{},"readingTime":{"minutes":1.76,"words":529},"filePathRelative":"courses/profile-dev-test/04.md","autoDesc":true}`);export{e as data}; diff --git a/assets/05.html-062HFELG.js b/assets/05.html-062HFELG.js new file mode 100644 index 000000000..909f4066a --- /dev/null +++ b/assets/05.html-062HFELG.js @@ -0,0 +1,231 @@ +import{_ as c}from"./plugin-vue_export-helper-x3n3nnut.js";import{r,o as p,c as d,b as l,w as a,d as n,e as s,f as o}from"./app-PAvzDPkc.js";const u={},m=n("p",null,[s("Let's practice creating our own custom resource. Let's say we want to write tests that examine the current state of a local Git repository. We want to create a "),n("code",null,"git"),s(" resource to handle all of InSpec's interactions with the Git repo under the hood, so that we can focus on writing clean and easy-to-read profile code.")],-1),k=n("p",null,"Let's take a look at this InSpec video that walks through this example and then try it out ourselves.",-1),b=n("div",{class:"video-container"},[n("iframe",{width:"1028",height:"578",src:"https://www.youtube.com/embed/Xka2xT6Cngg?list=PLSZbtIlMt5rcbXOpMRucKzRMXR7HX7awy",title:"YouTube video player",frameborder:"0",allow:"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture",allowfullscreen:""})],-1),v=n("h3",{id:"create-new-inspec-profile",tabindex:"-1"},[n("a",{class:"header-anchor",href:"#create-new-inspec-profile","aria-hidden":"true"},"#"),s(" Create new InSpec profile")],-1),g=n("p",null,"Let's start by creating a new profile:",-1),h=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[s("inspec init profile "),n("span",{class:"token function"},"git"),s(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"})])],-1),f=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[s(` ─────────────────────────── InSpec Code Generator ─────────────────────────── + +Creating new profile at /workspaces/saf-training-lab-environment/git + • Creating `),n("span",{class:"token function"},"file"),s(` inspec.yml + • Creating directory /workspaces/saf-training-lab-environment/git/controls + • Creating `),n("span",{class:"token function"},"file"),s(` controls/example.rb + • Creating `),n("span",{class:"token function"},"file"),s(` README.md +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),w=o(`To write tests, we first need to know and have what we are testing! In your Codespaces environment, there is a git repository that we will test under the resources folder. The git repository will be the test target, similarly to how the docker containers acted as test targets in previous sections. Unzip the target git repository using the following command:
unzip ./resources/git_test.zip
+This will generate a git_test repository which we will use for these examples.
Now let's write some controls and test that they run. You can put these controls in the example.rb file generated in the controls folder of your git InSpec profile. These controls are written using the command resource which is provided by InSpec. We will write a git resource in this section to improve this test. Note that you will need to put the full directory path of the .git file from your git_test repository as the git_dir value on line 4 of example.rb. To get the full path of your current location in the terminal, use pwd.
# encoding: utf-8
+# copyright: 2018, The Authors
+
+git_dir = "/workspaces/saf-training-lab-environment/git_test/.git"
+
+# The following banches should exist
+describe command("git --git-dir #{git_dir} branch") do
+ its('stdout') { should match /master/ }
+end
+
+describe command("git --git-dir #{git_dir} branch") do
+ its('stdout') { should match /testBranch/ }
+end
+
+# What is the current branch
+describe command("git --git-dir #{git_dir} branch") do
+ its('stdout') { should match /^\\* master/ }
+end
+
+# What is the latest commit
+describe command("git --git-dir #{git_dir} log -1 --pretty=format:'%h'") do
+ its('stdout') { should match /edc207f/ }
+end
+
+# What is the second to last commit
+describe command("git --git-dir #{git_dir} log --skip=1 -1 --pretty=format:'%h'") do
+ its('stdout') { should match /8c30bff/ }
+end
+Our tests pass, but they all use the command resource. It's not best practice to do this -- for one thing, it makes our tests more complicated, and the output too long.
But What If I Don't Care About The Tests Being Complicated And The Output Being Too Long?
Some test writers like to wrap their favorite bash commands in a command block and call it a day.
However, best practice is to write clean and maintainable InSpec code even if you yourself have no trouble using the command resource to do everything.
Recall that other developers and assessors need to be able to understand how your tests function. Nobody likes trying to debug someone else's profile that assumes that the operator knows exactly how the profile writer's favorite terminal commands work.
Let's rewrite these tests in a way that abstracts away the complexity of working with the git command into a resource.
Let's rewrite the first test in our example file to make it more readable with a git resource as follows:
# The following banches should exist
+describe git(git_dir) do
+ its('branches') { should include 'master' }
+end
+Now let's run the profile.
`,7),C=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[s("inspec "),n("span",{class:"token builtin class-name"},"exec"),s(),n("span",{class:"token function"},"git"),s(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"})])],-1),T=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[n("span",{class:"token punctuation"},"["),n("span",{class:"token number"},"2023"),s("-02-22T03:21:41+00:00"),n("span",{class:"token punctuation"},"]"),s(" ERROR: Failed to load profile git: Failed to load "),n("span",{class:"token builtin class-name"},"source"),s(),n("span",{class:"token keyword"},"for"),s(" controls/example.rb: undefined method "),n("span",{class:"token variable"},[n("span",{class:"token variable"},"`"),s("git' "),n("span",{class:"token keyword"},"for"),s(),n("span",{class:"token comment"},"#We should get an error because the git method and resource are not defined yet. We should fix that.
Let's start by creating a new file called git.rb in the libraries directory. If you do not already have a libraries directory, you can make one in the git InSpec profile directory. The content of the file should look like this:
# encoding: utf-8
+# copyright: 2019, The Authors
+
+class Git < Inspec.resource(1)
+ name 'git'
+
+end
+Setting Up a Resource Using InSpec Init
Instead of just creating the git.rb file in the libraries directory, you can use InSpec to assist you in creating a resource. Run inspec init resource <your-resource-name> and follow the prompts to create the foundation and see examples for a resource.
Now run the profile again.
`,6),I=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[s("inspec "),n("span",{class:"token builtin class-name"},"exec"),s(),n("span",{class:"token function"},"git"),s(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"})])],-1),S=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[n("span",{class:"token punctuation"},"["),n("span",{class:"token number"},"2023"),s("-02-22T03:25:57+00:00"),n("span",{class:"token punctuation"},"]"),s(" ERROR: Failed to load profile git: Failed to load "),n("span",{class:"token builtin class-name"},"source"),s(),n("span",{class:"token keyword"},"for"),s(" controls/example.rb: wrong number of arguments "),n("span",{class:"token punctuation"},"("),s("given "),n("span",{class:"token number"},"1"),s(", expected "),n("span",{class:"token number"},"0"),n("span",{class:"token punctuation"},")"),s(` + +Profile: InSpec Profile `),n("span",{class:"token punctuation"},"("),s("git"),n("span",{class:"token punctuation"},")"),s(` +Version: `),n("span",{class:"token number"},"0.1"),s(`.0 +Failure Message: Failed to load `),n("span",{class:"token builtin class-name"},"source"),s(),n("span",{class:"token keyword"},"for"),s(" controls/example.rb: wrong number of arguments "),n("span",{class:"token punctuation"},"("),s("given "),n("span",{class:"token number"},"1"),s(", expected "),n("span",{class:"token number"},"0"),n("span",{class:"token punctuation"},")"),s(` +Target: local:// +Target ID: 6dcb9e6f-5ede-5474-9521-595fadf5c7ce + + No tests executed. + +Test Summary: `),n("span",{class:"token number"},"0"),s(" successful, "),n("span",{class:"token number"},"0"),s(" failures, "),n("span",{class:"token number"},"0"),s(` skipped +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),q=o(`This time we get another error letting us know that we have a resource that has been given the incorrect number of arguments. This means we have given an additional parameter to this resource that we have not yet accepted.
Each resource will require an initialization method.
For our git.rb file let's add that initialization method:
# encoding: utf-8
+# copyright: 2019, The Authors
+
+class Git < Inspec.resource(1)
+ name 'git'
+
+ def initialize(path)
+ @path = path
+ end
+
+end
+This is saving the path we are passing in from the control into an instance method called path.
Now when we run the profile.
`,6),O=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[s("inspec "),n("span",{class:"token builtin class-name"},"exec"),s(),n("span",{class:"token function"},"git"),s(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"})])],-1),N=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[s("Profile: InSpec Profile "),n("span",{class:"token punctuation"},"("),s("git"),n("span",{class:"token punctuation"},")"),s(` +Version: `),n("span",{class:"token number"},"0.1"),s(`.0 +Target: local:// +Target ID: 6dcb9e6f-5ede-5474-9521-595fadf5c7ce + + `),n("span",{class:"token function"},"git"),s(` + × branches + undefined method `),n("span",{class:"token variable"},[n("span",{class:"token variable"},"`"),s("branches' "),n("span",{class:"token keyword"},"for"),s(),n("span",{class:"token comment"},"#<#The test will run but we will get an error saying we do not have a branches method. Remember that the other 4 tests are still passing because they are not yet using the git resource, but are still relying on InSpec's command resource.
Let's go back to our git.rb file to fix that by adding a branches method:
# encoding: utf-8
+# copyright: 2019, The Authors
+
+class Git < Inspec.resource(1)
+ name 'git'
+
+ def initialize(path)
+ @path = path
+ end
+
+ def branches
+
+ end
+
+end
+We have now defined the branches method. Let's see what the test output shows us.
`,4),R=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[s("inspec "),n("span",{class:"token builtin class-name"},"exec"),s(),n("span",{class:"token function"},"git"),s(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"})])],-1),B=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[s("Profile: InSpec Profile "),n("span",{class:"token punctuation"},"("),s("git"),n("span",{class:"token punctuation"},")"),s(` +Version: `),n("span",{class:"token number"},"0.1"),s(`.0 +Target: local:// +Target ID: 6dcb9e6f-5ede-5474-9521-595fadf5c7ce + + `),n("span",{class:"token function"},"git"),s(` + × branches is expected to include `),n("span",{class:"token string"},'"master"'),s(` + expected nil to include `),n("span",{class:"token string"},'"master"'),s(", but it does not respond to "),n("span",{class:"token variable"},[n("span",{class:"token variable"},"`"),s("include?"),n("span",{class:"token variable"},"`")]),s(` + Command: `),n("span",{class:"token variable"},[n("span",{class:"token variable"},"`"),n("span",{class:"token function"},"git"),s(" --git-dir /workspaces/saf-training-lab-environment/git_test/.git branch"),n("span",{class:"token variable"},"`")]),s(` + ✔ stdout is expected to match /testBranch/ + Command: `),n("span",{class:"token variable"},[n("span",{class:"token variable"},"`"),n("span",{class:"token function"},"git"),s(" --git-dir /workspaces/saf-training-lab-environment/git_test/.git branch"),n("span",{class:"token variable"},"`")]),s(` + ✔ stdout is expected to match /^`),n("span",{class:"token punctuation"},"\\"),s(`* master/ + Command: `),n("span",{class:"token variable"},[n("span",{class:"token variable"},"`"),n("span",{class:"token function"},"git"),s(" --git-dir /workspaces/saf-training-lab-environment/git_test/.git log "),n("span",{class:"token parameter variable"},"-1"),s(),n("span",{class:"token parameter variable"},"--pretty"),n("span",{class:"token operator"},"="),s("format:"),n("span",{class:"token string"},"'%h'"),n("span",{class:"token variable"},"`")]),s(` + ✔ stdout is expected to match /edc207f/ + Command: `),n("span",{class:"token variable"},[n("span",{class:"token variable"},"`"),n("span",{class:"token function"},"git"),s(" --git-dir /workspaces/saf-training-lab-environment/git_test/.git log "),n("span",{class:"token parameter variable"},"--skip"),n("span",{class:"token operator"},"="),n("span",{class:"token number"},"1"),s(),n("span",{class:"token parameter variable"},"-1"),s(),n("span",{class:"token parameter variable"},"--pretty"),n("span",{class:"token operator"},"="),s("format:"),n("span",{class:"token string"},"'%h'"),n("span",{class:"token variable"},"`")]),s(` + ✔ stdout is expected to match /8c30bff/ + +Test Summary: `),n("span",{class:"token number"},"4"),s(" successful, "),n("span",{class:"token number"},"1"),s(" failure, "),n("span",{class:"token number"},"0"),s(` skipped +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),L=o(`Now the error message says that the branches method is returning a null value when it's expecting an array or something that is able to accept the include method invoked on it.
We can use the InSpec helper method which enables you to invoke any other inspec resource as seen below:
# encoding: utf-8
+# copyright: 2019, The Authors
+
+class Git < Inspec.resource(1)
+ name 'git'
+
+ def initialize(path)
+ @path = path
+ end
+
+ def branches
+ inspec.command("git --git-dir #{@path} branch").stdout
+ end
+
+end
+We have borrowed the built-in command resource to handle running Git's CLI commands.
Now we see that we get a passing test!
Now let's adjust our test to also check for our second branch that we created earlier as well as check our current branch:
# The following banches should exist
+describe git(git_dir) do
+ its('branches') { should include 'master' }
+ its('branches') { should include 'testBranch' }
+ its('current_branch') { should cmp 'master' }
+end
+Let's head over to the git.rb file to create the current_branch method we are invoking in the above test:
# encoding: utf-8
+# copyright: 2019, The Authors
+
+class Git < Inspec.resource(1)
+ name 'git'
+
+ def initialize(path)
+ @path = path
+ end
+
+ def branches
+ inspec.command("git --git-dir #{@path} branch").stdout
+ end
+
+ def current_branch
+ branch_name = inspec.command("git --git-dir #{@path} branch").stdout.strip.split("\\n").find do |name|
+ name.start_with?('*')
+ end
+ branch_name.gsub(/^\\*/,'').strip
+ end
+
+end
+Now we can run the profile again.
`,3),z=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[s("inspec "),n("span",{class:"token builtin class-name"},"exec"),s(),n("span",{class:"token function"},"git"),s(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"})])],-1),E=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[s("Profile: InSpec Profile "),n("span",{class:"token punctuation"},"("),s("git"),n("span",{class:"token punctuation"},")"),s(` +Version: `),n("span",{class:"token number"},"0.1"),s(`.0 +Target: local:// +Target ID: 6dcb9e6f-5ede-5474-9521-595fadf5c7ce + + `),n("span",{class:"token function"},"git"),s(` + ✔ branches is expected to include `),n("span",{class:"token string"},'"master"'),s(` + ✔ branches is expected to include `),n("span",{class:"token string"},'"testBranch"'),s(` + ✔ current_branch is expected to `),n("span",{class:"token function"},"cmp"),s(),n("span",{class:"token operator"},"=="),s(),n("span",{class:"token string"},'"master"'),s(` + Command: `),n("span",{class:"token variable"},[n("span",{class:"token variable"},"`"),n("span",{class:"token function"},"git"),s(" --git-dir /workspaces/saf-training-lab-environment/git_test/.git log "),n("span",{class:"token parameter variable"},"-1"),s(),n("span",{class:"token parameter variable"},"--pretty"),n("span",{class:"token operator"},"="),s("format:"),n("span",{class:"token string"},"'%h'"),n("span",{class:"token variable"},"`")]),s(` + ✔ stdout is expected to match /edc207f/ + Command: `),n("span",{class:"token variable"},[n("span",{class:"token variable"},"`"),n("span",{class:"token function"},"git"),s(" --git-dir /workspaces/saf-training-lab-environment/git_test/.git log "),n("span",{class:"token parameter variable"},"--skip"),n("span",{class:"token operator"},"="),n("span",{class:"token number"},"1"),s(),n("span",{class:"token parameter variable"},"-1"),s(),n("span",{class:"token parameter variable"},"--pretty"),n("span",{class:"token operator"},"="),s("format:"),n("span",{class:"token string"},"'%h'"),n("span",{class:"token variable"},"`")]),s(` + ✔ stdout is expected to match /8c30bff/ + +Test Summary: `),n("span",{class:"token number"},"7"),s(" successful, "),n("span",{class:"token number"},"0"),s(" failures, "),n("span",{class:"token number"},"0"),s(` skipped +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),F=n("p",null,"All the tests should pass!",-1),G=n("div",{class:"hint-container tip"},[n("p",{class:"hint-container-title"},"Exercise!"),n("p",null,"As a solo exercise, try to create a method in the git.rb file to check what the last commit is.")],-1);function M(X,U){const i=r("CodeTabs");return p(),d("div",null,[m,k,b,v,g,l(i,{id:"14",data:[{id:"Command"},{id:"Output"}]},{title0:a(({value:e,isActive:t})=>[s("Command")]),title1:a(({value:e,isActive:t})=>[s("Output")]),tab0:a(({value:e,isActive:t})=>[h]),tab1:a(({value:e,isActive:t})=>[f]),_:1}),w,l(i,{id:"36",data:[{id:"Command"},{id:"Output"}]},{title0:a(({value:e,isActive:t})=>[s("Command")]),title1:a(({value:e,isActive:t})=>[s("Output")]),tab0:a(({value:e,isActive:t})=>[y]),tab1:a(({value:e,isActive:t})=>[_]),_:1}),x,l(i,{id:"71",data:[{id:"Command"},{id:"Output"}]},{title0:a(({value:e,isActive:t})=>[s("Command")]),title1:a(({value:e,isActive:t})=>[s("Output")]),tab0:a(({value:e,isActive:t})=>[C]),tab1:a(({value:e,isActive:t})=>[T]),_:1}),A,l(i,{id:"97",data:[{id:"Command"},{id:"Output"}]},{title0:a(({value:e,isActive:t})=>[s("Command")]),title1:a(({value:e,isActive:t})=>[s("Output")]),tab0:a(({value:e,isActive:t})=>[I]),tab1:a(({value:e,isActive:t})=>[S]),_:1}),q,l(i,{id:"121",data:[{id:"Command"},{id:"Output"}]},{title0:a(({value:e,isActive:t})=>[s("Command")]),title1:a(({value:e,isActive:t})=>[s("Output")]),tab0:a(({value:e,isActive:t})=>[O]),tab1:a(({value:e,isActive:t})=>[N]),_:1}),P,l(i,{id:"139",data:[{id:"Command"},{id:"Output"}]},{title0:a(({value:e,isActive:t})=>[s("Command")]),title1:a(({value:e,isActive:t})=>[s("Output")]),tab0:a(({value:e,isActive:t})=>[R]),tab1:a(({value:e,isActive:t})=>[B]),_:1}),L,l(i,{id:"164",data:[{id:"Command"},{id:"Output"}]},{title0:a(({value:e,isActive:t})=>[s("Command")]),title1:a(({value:e,isActive:t})=>[s("Output")]),tab0:a(({value:e,isActive:t})=>[D]),tab1:a(({value:e,isActive:t})=>[V]),_:1}),W,l(i,{id:"179",data:[{id:"Command"},{id:"Output"}]},{title0:a(({value:e,isActive:t})=>[s("Command")]),title1:a(({value:e,isActive:t})=>[s("Output")]),tab0:a(({value:e,isActive:t})=>[z]),tab1:a(({value:e,isActive:t})=>[E]),_:1}),F,G])}const Y=c(u,[["render",M],["__file","05.html.vue"]]);export{Y as default}; diff --git a/assets/05.html-0lRQQ4nw.js b/assets/05.html-0lRQQ4nw.js new file mode 100644 index 000000000..c7953aad6 --- /dev/null +++ b/assets/05.html-0lRQQ4nw.js @@ -0,0 +1,163 @@ +import{_ as u}from"./plugin-vue_export-helper-x3n3nnut.js";import{r,o as d,c as p,d as n,b as t,e as s,w as e,f as c}from"./app-PAvzDPkc.js";const m={},b=c(`Let's work through some example requirements to write InSpec controls.
We write InSpec controls to test some target based on security guidance. Here, let's verify that the NGINX instance had been configured to meet the following requirements:
1. NGINX version 1.10.3 or later.
+2. The following NGINX modules should be installed:
+ * \`http_ssl\`
+ * \`stream_ssl\`
+ * \`mail_ssl\`
+3. The NGINX configuration file - \`/etc/nginx/nginx.conf\`- should exist as a file.
+4. The NGINX configuration file should:
+ * be owned by the \`root\` user and group.
+ * not be readable, writeable, or executable by others.
+5. The NGINX shell access should be restricted to admin users.
+The first requirement is for the NGINX version to be 1.10.3 or later.
We can check this using the InSpec cmp matcher.
Replace the contents of my_nginx/controls/example.rb with this:
control 'nginx-version' do
+ impact 1.0
+ title 'NGINX version'
+ desc 'The required version of NGINX should be installed.'
+ describe nginx do
+ its('version') { should cmp >= '1.10.3' }
+ end
+end
+You see that the test passes.
The second requirement verifies that our required modules are installed.
Append your control file to add this describe block:
control 'nginx-modules' do
+ impact 1.0
+ title 'NGINX modules'
+ desc 'The required NGINX modules should be installed.'
+ describe nginx do
+ its('modules') { should include 'http_ssl' }
+ its('modules') { should include 'stream_ssl' }
+ its('modules') { should include 'mail_ssl' }
+ end
+end
+The second control resembles the first; however, this version uses multiple its statements and the nginx.modules method. The nginx.modules method returns a list; the built-in include matcher verifies whether a value belongs to a given list.
Run inspec exec on the target.
This time, both controls pass.
nginx_conf fileThe third requirement verifies that the NGINX configuration file - /etc/nginx/nginx.conf - exists as a file.
Append this describe block to your control file:
control 'nginx-conf-file' do
+ impact 1.0
+ title 'NGINX configuration file'
+ desc 'The NGINX config file should exist as a file.'
+ describe file('/etc/nginx/nginx.conf') do
+ it { should be_file }
+ end
+end
+Run inspec exec on the target.
nginx_conf fileThe fourth requirement verifies that the NGINX configuration file, /etc/nginx/nginx.conf:
Append your control file to add this describe block:
control 'nginx-conf-perms' do
+ impact 1.0
+ title 'NGINX configuration'
+ desc 'The NGINX config file should owned by root, be writable only by owner, and not writeable or and readable by others.'
+ describe file('/etc/nginx/nginx.conf') do
+ it { should be_owned_by 'root' }
+ it { should be_grouped_into 'root' }
+ it { should_not be_readable.by('others') }
+ it { should_not be_writable.by('others') }
+ it { should_not be_executable.by('others') }
+ end
+end
+This time you see a failure. You discover that /etc/nginx/nginx.conf is potentially readable by others. Because this control also has an impact of 1.0, your team may need to investigate further.
The last requirement checks whether NGINX shell access is provided to non-admin users. In this case, access to bash needs to be restricted to admin users.
Append this describe block to your control file:
control 'nginx-shell-access' do
+ impact 1.0
+ title 'NGINX shell access'
+ desc 'The NGINX shell access should be restricted to admin users.'
+ describe users.shells(/bash/).usernames do
+ it { should be_in ['admin']}
+ end
+end
+Run inspec exec on the target.
bundle exec kitchen list. You should see something like this: Instance Driver Provisioner Verifier Transport Last Action Last Error
+ vanilla-rhel-8 Ec2 AnsiblePlaybook Inspec Ssh Verified None
+ hardened-rhel-8 Ec2 AnsiblePlaybook Inspec Ssh Verified None
+bundle exec kitchen create vanilla.➜ redhat-enterprise-linux-8-stig-baseline git:(main*)bundle exec kitchen create vanilla
+-----> Starting Test Kitchen (v3.5.1)
+-----> Creating <vanilla-rhel-8>...
+ < OTHER OUTPUT >
+ Finished creating <vanilla-rhel-8> (0m0.00s).
+-----> Test Kitchen is finished. (0m1.21s)
+bundle exec kitchen converge.➜ redhat-enterprise-linux-8-stig-baseline git:(main*)bundle exec kitchen converge vanilla
+-----> Starting Test Kitchen (v3.5.1)
+ NOTICE - Installing needed packages
+ Updating Subscription Management repositories.
+ Unable to read consumer identity
+
+ This system is not registered with an entitlement server. You can use subscription-manager to register.
+
+ 39 files removed
+ < LOTS OF OTHER OUTPUT >
+ Downloading files from <vanilla-rhel-8>
+ Finished converging <vanilla-rhel-8> (0m21.36s).
+-----> Test Kitchen is finished. (1m13.52s)
+bundle exec kitchen verify. ➜ redhat-enterprise-linux-8-stig-baseline git:(main*)bundle exec kitchen verify vanilla
+ -----> Starting Test Kitchen (v3.5.1)
+ -----> Setting up <vanilla-rhel-8>...
+ Finished setting up <vanilla-rhel-8> (0m0.00s).
+ -----> Verifying <vanilla-rhel-8>...
+ Loaded redhat-enterprise-linux-8-stig-baseline
+ Could not determine patch status.
+ Profile: redhat-enterprise-linux-8-stig-baseline (redhat-enterprise-linux-8-stig-baseline)
+ Version: 1.12.0
+ Target: ssh://ec2-user@34.229.216.179:22
+ Target ID: 4c62a305-69eb-5ed6-9ee7-723cdc21c578
+
+ ✔ SV-230222: RHEL 8 vendor packaged system security patches and updates must be installed and up to date.
+ ✔ List of out-of-date packages is expected to be empty
+ Profile Summary: 1 successful control, 0 control failures, 0 controls skipped
+ Test Summary: 1 successful, 0 failures, 0 skipped
+ Finished verifying <vanilla-rhel-8> (0m5.38s).
+ -----> Test Kitchen is finished. (0m6.62s)
+For the purposes of this class, let's assume the role of a security engineer who has been tasked to write STIG-ready content for the Red Hat Enterprise Linux 9 (RHEL9) operating system.
DISA has already published a RHEL9 STIG, so we will be able to compare our content to the real thing if we wish.
If you haven't yet registered an account with this instance, do so now.
After logging in, you will reach the Projects screen.
Vulcan categorizes security guidance content into Projects. Each project can include multiple Components, where a component is a single piece of security guidance (for instance, a single STIG document). A Project can contain multiple versions of the same component (for instance, multiple releases of the STIG for the same software).
We need a new Project as a workspace to write our STIG-ready content.
Click it and begin to fill out the details for our project. You can make the Title and Description of your project whatever you want, but be sure to set the Visibility of the project to "discoverable," because you'll want your colleagues to be able to peer review your work later.
Before we create a Component, though, let's configure Role-Based Access Control (RBAC).
In a new Project, you'll be the only member at first. You can add a new member with a Role of:
Read only access to the Project or Component
Edit, comment, and mark Controls as requiring review. Cannot sign-off or approve changes to a Control. Great for individual contributors.
Write and approve changes to a Control.
Full control of a Project or Component. Lock Controls, revert controls, and manage members. You'll note that the Project's creator is automatically an admin.
Adding Colleagues
If you have any colleagues taking the class with you, you may want to add them as a reviewer now (note that you can only add members to a project if they have registered to the Vulcan instance already).
Should I Be An Author Or A Reviewer?
Reviewers are able to approve requirements written by other members. Depending on how your team operates, you may want to have many authors with one final reviewer role, or you may want to have every member be a reviewer. It's up to you.
Only the Admin role can bypass the peer review process to lock (finalize) their own requirements. Try not to dole out the Admin role too often; it's best practice to force all requirements to undergo peer review.
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.
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.
When using this mindset in software development, this kind of development can be referred to as Test Driven Development.
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.
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.
To run InSpec, you must have:
./lab-setup.sh script) Check out the Installation Tab for more information on installing InSpec in a different environment.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.
inspec exec WHERE_IS_THE_PROFILE -t WHAT_IS_THE_TARGET --more-flags EXTRA_STUFF --reporter WHAT_SHOULD_INSPEC_DO_WITH_THE_RESULTS
+You need to start with inspec exec so that your terminal knows what it is trying to do in the first place.
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.
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.
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 section.
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.
We will go more in depth on this example in the next two sections, but if you want a head start, you can give running InSpec a try by running this command in your Codespace terminal.
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.
Note: The first time you run InSpec, it will likely ask you to accept Chef's license like this:
+---------------------------------------------+
+ Chef License Acceptance
+
+Before you can continue, 1 product license
+must be accepted. View the license at
+https://www.chef.io/end-user-license-agreement/
+
+License that need accepting:
+ * Chef InSpec
+
+Do you accept the 1 product license (yes/no)?
+
+>
+You can type yes and press enter. This will only happen one time.
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.
inspec exec https://github.com/mitre/nginx-stigready-baseline
+ -t docker://instance_id
+ --input-file <path_to_your_input_file/name_of_your_input_file.yml>
+ --reporter json:<path_to_your_output_file/name_of_your_output_file.json>
+inspec exec https://github.com/mitre/nginx-stigready-baseline
+ -t ssh://Username:Password@IP
+ --input-file <path_to_your_input_file/name_of_your_input_file.yml>
+ --reporter json:<path_to_your_output_file/name_of_your_output_file.json>
+Defaults
Note that if you do not provide one of the required flags in the InSpec exec command, there is default behavior.
| Missing Flag | Default Behavior |
|---|---|
| No target (-t or --target) | Uses your local machine (where InSpec is running) as the target. |
| No --reporter flag | Prints results to the terminal on the InSpec runner machine |
Your my_nginx profile is off to a great start. As your requirements evolve, you can add additional controls. You can also run this profile as often as you need to verify whether your systems remain in compliance.
Let's review the control file, example.rb.
control 'nginx-version' do
+ impact 1.0
+ title 'NGINX version'
+ desc 'The required version of NGINX should be installed.'
+ describe nginx do
+ its('version') { should cmp >= '1.10.3' }
+ end
+end
+
+control 'nginx-modules' do
+ impact 1.0
+ title 'NGINX modules'
+ desc 'The required NGINX modules should be installed.'
+ describe nginx do
+ its('modules') { should include 'http_ssl' }
+ its('modules') { should include 'stream_ssl' }
+ its('modules') { should include 'mail_ssl' }
+ end
+end
+
+control 'nginx-conf-file' do
+ impact 1.0
+ title 'NGINX configuration file'
+ desc 'The NGINX config file should exist.'
+ describe file('/etc/nginx/nginx.conf') do
+ it { should be_file }
+ end
+end
+
+control 'nginx-conf-perms' do
+ impact 1.0
+ title 'NGINX configuration'
+ desc 'The NGINX config file should owned by root, be writable only by owner, and not writeable or and readable by others.'
+ describe file('/etc/nginx/nginx.conf') do
+ it { should be_owned_by 'root' }
+ it { should be_grouped_into 'root' }
+ it { should_not be_readable.by('others') }
+ it { should_not be_writable.by('others') }
+ it { should_not be_executable.by('others') }
+ end
+end
+
+control 'nginx-shell-access' do
+ impact 1.0
+ title 'NGINX shell access'
+ desc 'The NGINX shell access should be restricted to admin users.'
+ describe users.shells(/bash/).usernames do
+ it { should be_in ['admin']}
+ end
+end
+Although these rules do what you expect, imagine your control file contains dozens or hundreds of tests. As the data you check for, such as the version or which modules are installed, evolve, it can become tedious to locate and update your tests. You may also find that you repeat the same data across multiple control files.
One way to improve these tests is to use inputs. Inputs enable you to separate the logic of your tests from the data of your tests. Input files are typically expressed as a YAML file (files ending in .yaml or .yml).
Profile Inputs exist in your profile's main directory within the inspec.yml for global inputs to be used across all the controls in your profile.
Let's create the inspec.yml file for our profile:
name: my_nginx
+title: InSpec Profile
+maintainer: The Authors
+copyright: The Authors
+copyright_email: you@example.com
+license: Apache-2.0
+summary: An InSpec Compliance Profile
+version: 0.1.0
+supports:
+ platform: os
+
+inputs:
+ - name: nginx_version
+ type: String
+ value: 1.10.3
+To access an input you will use the input keyword. You can use this anywhere in your control code.
For example:
control 'nginx-version' do
+ impact 1.0
+ title 'NGINX version'
+ desc 'The required version of NGINX should be installed.'
+ describe nginx do
+ its('version') { should cmp >= input('nginx_version') }
+ end
+end
+For our next control we require specific modules
Example of adding an array object of servers:
`,14),b=n("div",{class:"language-yaml line-numbers-mode","data-ext":"yml"},[n("pre",{class:"language-yaml"},[n("code",null,[s(" "),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(` servers + `),n("span",{class:"token key atrule"},"type"),n("span",{class:"token punctuation"},":"),s(` Array + `),n("span",{class:"token key atrule"},"value"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token punctuation"},"-"),s(` server1 + `),n("span",{class:"token punctuation"},"-"),s(` server2 + `),n("span",{class:"token punctuation"},"-"),s(` server3 +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),y=n("div",{class:"language-yaml line-numbers-mode","data-ext":"yml"},[n("pre",{class:"language-yaml"},[n("code",null,[s(" "),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(` nginx_modules + `),n("span",{class:"token key atrule"},"type"),n("span",{class:"token punctuation"},":"),s(` Array + `),n("span",{class:"token key atrule"},"value"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token punctuation"},"-"),s(` http_ssl + `),n("span",{class:"token punctuation"},"-"),s(` stream_ssl + `),n("span",{class:"token punctuation"},"-"),s(` mail_ssl +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),g=n("div",{class:"language-yaml line-numbers-mode","data-ext":"yml"},[n("pre",{class:"language-yaml"},[n("code",null,[n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(` my_nginx +`),n("span",{class:"token key atrule"},"title"),n("span",{class:"token punctuation"},":"),s(` InSpec Profile +`),n("span",{class:"token key atrule"},"maintainer"),n("span",{class:"token punctuation"},":"),s(` The Authors +`),n("span",{class:"token key atrule"},"copyright"),n("span",{class:"token punctuation"},":"),s(` The Authors +`),n("span",{class:"token key atrule"},"copyright_email"),n("span",{class:"token punctuation"},":"),s(` you@example.com +`),n("span",{class:"token key atrule"},"license"),n("span",{class:"token punctuation"},":"),s(" Apache"),n("span",{class:"token punctuation"},"-"),n("span",{class:"token number"},"2.0"),s(` +`),n("span",{class:"token key atrule"},"summary"),n("span",{class:"token punctuation"},":"),s(` An InSpec Compliance Profile +`),n("span",{class:"token key atrule"},"version"),n("span",{class:"token punctuation"},":"),s(` 0.1.0 +`),n("span",{class:"token key atrule"},"supports"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token key atrule"},"platform"),n("span",{class:"token punctuation"},":"),s(` os + +`),n("span",{class:"token key atrule"},"inputs"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(` nginx_version + `),n("span",{class:"token key atrule"},"type"),n("span",{class:"token punctuation"},":"),s(` String + `),n("span",{class:"token key atrule"},"value"),n("span",{class:"token punctuation"},":"),s(` 1.10.3 + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(` nginx_modules + `),n("span",{class:"token key atrule"},"type"),n("span",{class:"token punctuation"},":"),s(` Array + `),n("span",{class:"token key atrule"},"value"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token punctuation"},"-"),s(` http_ssl + `),n("span",{class:"token punctuation"},"-"),s(` stream_ssl + `),n("span",{class:"token punctuation"},"-"),s(` mail_ssl +`)])]),n("div",{class:"highlight-lines"},[n("br"),n("br"),n("br"),n("br"),n("br"),n("br"),n("br"),n("br"),n("br"),n("br"),n("br"),n("br"),n("br"),n("br"),n("br"),n("br"),n("div",{class:"highlight-line"}," "),n("div",{class:"highlight-line"}," "),n("div",{class:"highlight-line"}," "),n("div",{class:"highlight-line"}," "),n("div",{class:"highlight-line"}," "),n("div",{class:"highlight-line"}," ")]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),h=i(`Your control can be changed to look like this:
control 'nginx-modules' do
+ impact 1.0
+ title 'NGINX modules'
+ desc 'The required NGINX modules should be installed.'
+
+ nginx_modules = input('nginx_modules')
+
+ describe nginx do
+ nginx_modules.each do |current_module|
+ its('modules') { should include current_module }
+ end
+ end
+end
+Lastly, we can edit our inspec.yml file to create a list of admin users:
Your fifth control can be changed to look like this:
control 'nginx-shell-access' do
+ impact 1.0
+ title 'NGINX shell access'
+ desc 'The NGINX shell access should be restricted to admin users.'
+ describe users.shells(/bash/).usernames do
+ it { should be_in input('admin_users')}
+ end
+end
+To change your inputs for platform specific cases you can setup multiple input files.
For example, an NGINX web server could be run on a Windows or Linux machine, which may require different admin users for each context. The inputs can be tailored for each system. You can create the inputs-windows.yml and inputs-linux.yml files in your home directory.
Note
Another example is that a production and development environment may require different inputs.
The following command runs the tests and applies the inputs specified, first, on the Linux system:
inspec exec ./my_nginx -t docker://nginx --input-file inputs-linux.yml
+And, on our Windows systems:
inspec exec ./my_nginx -t docker://nginx --input-file inputs-windows.yml
+bundle exec kitchen list➜ redhat-enterprise-linux-8-stig-baseline git:(main*)bundle exec kitchen list
+Instance Driver Provisioner Verifier Transport Last Action Last Error
+vanilla-ubi8 Dokken Dummy Inspec Dokken <Not Created> <None>
+hardened-ubi8 Dokken Dummy Inspec Dokken <Not Created> <None>
+bundle exec kitchen create vanilla-----> Starting Test Kitchen (v3.5.1)
+-----> Creating <vanilla-ubi8>...
+ Creating kitchen sandbox at /Users/alippold/.dokken/kitchen_sandbox/de2da32d73-vanilla-ubi8
+ Creating verifier sandbox at /Users/alippold/.dokken/verifier_sandbox/de2da32d73-vanilla-ubi8
+ Building work image..
+ Creating container de2da32d73-vanilla-ubi8
+ Finished creating <vanilla-ubi8> (0m0.88s).
+-----> Test Kitchen is finished. (0m1.77s)
+bundle exec kitchen converge vanilla➜ redhat-enterprise-linux-8-stig-baseline git:(main*)bundle exec kitchen converge vanilla
+-----> Starting Test Kitchen (v3.5.1)
+-----> Converging <vanilla-ubi8>...
+ ...
+ Finished converging <vanilla-ubi8> (0m0.00s).
+-----> Test Kitchen is finished. (0m0.88s)
+bundle exec kitchen verify vanilla-----> Starting Test Kitchen (v3.5.1)
+-----> Verifying <vanilla-ubi8>...
+ Loaded redhat-enterprise-linux-8-stig-baseline
+
+Profile: redhat-enterprise-linux-8-stig-baseline (redhat-enterprise-linux-8-stig-baseline)
+Version: 1.12.0
+Target: docker://c4e89b7406dc0ebf8658fe90d6384d69885a7f07ab9bfbc91c85c64483868c44
+Target ID: da39a3ee-5e6b-5b0d-b255-bfef95601890
+
+ × SV-230222: RHEL 8 vendor packaged system security patches and updates must be installed and up to date. (4 failed)
+...
+
+Profile Summary: 0 successful controls, 1 control failure, 0 controls skipped
+Test Summary: 0 successful, 4 failures, 0 skipped
+The error below is just Test Kitchen telling you that not all of the Contrls in the profile passed.
>>>>>> ------Exception-------
+>>>>>> Class: Kitchen::ActionFailed
+>>>>>> Message: 1 actions failed.
+>>>>>> Verify failed on instance <vanilla-ubi8>. Please see .kitchen/logs/vanilla-ubi8.log for more details
+>>>>>> ----------------------
+>>>>>> Please see .kitchen/logs/kitchen.log for more details
+>>>>>> Also try running \`kitchen diagnose --all\` for configuration
+./spec/results/ directory, named ./spec/results/ubi-8_*.hardened and vanilla results to ensure your changes and updates, "failed as expected and passed as expected and covered your corner cases."We have our project created and have allowed access to everyone who needs it. Now let's create ourselves a Component.
The first thing we need to do when building a Component is determine what set of requirements applies to it.
A helpful question to keep in mind for this decision is "What is the purpose of the software you are securing? What is its role?" This will determine what guidance document we want to use as a foundation for our content.
Let's take a look at the options we have for a foundation.
You'll see options in the top navbar of Vulcan for "SRGs" and "STIGs." These links lead to the lists of security guidance documents already saved to Vulcan. We can use any of these as a template for our own content.
We have pre-loaded this Vulcan instance with a few SRGs to get us started. Since we're writing content for the RHEL9 operating system, we're going to want to use the General Purpose Operating System Security Requirements Guide.
DISA and SRG selection
Note that if you intend to formally publish your STIG, DISA will tell you which one to use based off the description of your software that you give them.
Application STIGs
Applications (as opposed to software like operating systems, webservers and routers) that undergo the STIG process all should be using the Application Security and Development STIG as a foundation document.
Remember that a STIG can itself be used as the foundation for a tailored security baseline document!
Let's create a new Component to track our RHEL9 work.
Here, you'll select the SRG we decided on earlier.
*Optional.
STIG ID Prefixes
If you intend to formally publish your STIG, DISA will eventually assign these for you. These are just a placeholder value for now to allow us to track requirements inside Vulcan itself.
Other Ways of Loading Components
Vulcan allows you to import Components as well as creating them brand-new. You are able to load from your own released Components in your Vulcan instance, or even from a spreadsheet.
Let's crack open what we just created.
The page should look something like this:
On the right-hand side of the Vulcan window, if we don't have a requirement selected, we can see metadata about the overall Component, including an edit history.
The left-hand side of the Vulcan window shows us the list of each requirement in the Component, and can be filtered by keyword, control status (which we will discuss in the next section) or review status. Note that each control is labeled with the STIG ID prefix that you gave this Component earlier. You can click on the requirement IDs in this view to see their contents.
When first created, a new Component's requirements will all be exact copies of the SRG or other underlying document we used as a foundation. Our job is to edit these controls to make them specific, actionable implementation guidance.
',35),h=[p];function u(d,m){return o(),n("div",null,h)}const y=t(c,[["render",u],["__file","06.html.vue"]]);export{y as default}; diff --git a/assets/06.html-lc3SD2e2.js b/assets/06.html-lc3SD2e2.js new file mode 100644 index 000000000..ca9f9ac63 --- /dev/null +++ b/assets/06.html-lc3SD2e2.js @@ -0,0 +1,255 @@ +import{_ as c}from"./TestDrivenDevelopment-M1Sg-EUL.js";import{_ as r}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as p,o as u,c as d,b as o,w as e,d as s,f as l,e as n}from"./app-PAvzDPkc.js";const k={},m=l(`Now let's try a more complicated example. Let's say we want to create a resource that can parse a docker-compose file.
First, we need a test target! Check out the resources/docker-compose.yml file in Codespaces for what we can test. It looks like this:
version: '3'
+services:
+ workstation:
+ container_name: workstation
+ image: learnchef/inspec_workstation
+ stdin_open: true
+ tty: true
+ links:
+ - target
+ volumes:
+ - .:/root
+ target:
+ image: learnchef/inspec_target
+ stdin_open: true
+ tty: true
+We will continue writing our controls to check against this docker file:
`,6),v=s("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[s("pre",{class:"language-bash"},[s("code",null,`inspec init profile docker-workstations +`)]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"})])],-1),b=s("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[s("pre",{class:"language-bash"},[s("code",null,[n(` ─────────────────────────── InSpec Code Generator ─────────────────────────── + +Creating new profile at /workspaces/saf-training-lab-environment/docker-workstations + • Creating `),s("span",{class:"token function"},"file"),n(` inspec.yml + • Creating directory /workspaces/saf-training-lab-environment/docker-workstations/controls + • Creating `),s("span",{class:"token function"},"file"),n(` controls/example.rb + • Creating `),s("span",{class:"token function"},"file"),n(` README.md +`)])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"})])],-1),g=l(`Conceptually, we want to write tests with this profile that will check different settings in a docker-compose file. If you are not sure what the InSpec code looks like for a particular test, start by writing what conceptually you want to achieve, then modify it to be correct syntax. We can do that with the idea of checking a setting in a docker-compose file, which we know is a YAML file, as such:
In the docker-workstations/controls/example.rb file, write the control:
describe yaml('file_name') do
+ its('setting') { should_not eq 'value' }
+end
+We test early and often. We know that the test we wrote is not complete, but we can see if we are on the right track. Remember that the command line output can help guide your development!
`,5),h=s("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[s("pre",{class:"language-bash"},[s("code",null,[n("inspec "),s("span",{class:"token builtin class-name"},"exec"),n(` docker-workstations +`)])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"})])],-1),f=s("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[s("pre",{class:"language-bash"},[s("code",null,[n("Profile: InSpec Profile "),s("span",{class:"token punctuation"},"("),n("docker-workstations"),s("span",{class:"token punctuation"},")"),n(` +Version: `),s("span",{class:"token number"},"0.1"),n(`.0 +Target: local:// +Target ID: 6dcb9e6f-5ede-5474-9521-595fadf5c7ce + + YAML file_name + ↺ Can't `),s("span",{class:"token function"},"find"),n(` file: file_name + +Test Summary: `),s("span",{class:"token number"},"0"),n(" successful, "),s("span",{class:"token number"},"0"),n(" failures, "),s("span",{class:"token number"},"1"),n(` skipped +`)])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"})])],-1),w=l(`We need to replace the file_name above with the location of the docker-compose.yml file. We also need to change the setting to grab the tag we want to retrieve. Finally we need to change value with the actual value as shown in the docker compose file. You can write multiple expectation statements in the describe block.
describe yaml('/path/to/docker-compose.yml') do
+ its(['services', 'workstation', 'image']) { should eq 'learnchef/inspec_workstation' }
+ its(['services', 'workstation', 'volumes']) { should cmp '.:/root' }
+end
+Now if we test this control using the following command we should see all the tests pass.
`,3),y=s("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[s("pre",{class:"language-bash"},[s("code",null,[n("inspec "),s("span",{class:"token builtin class-name"},"exec"),n(` docker-workstations +`)])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"})])],-1),_=s("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[s("pre",{class:"language-bash"},[s("code",null,[n("Profile: InSpec Profile "),s("span",{class:"token punctuation"},"("),n("docker-workstations"),s("span",{class:"token punctuation"},")"),n(` +Version: `),s("span",{class:"token number"},"0.1"),n(`.0 +Target: local:// +Target ID: 6dcb9e6f-5ede-5474-9521-595fadf5c7ce + + YAML /workspaces/saf-training-lab-environment/resources/docker-compose.yml + ✔ `),s("span",{class:"token punctuation"},"["),s("span",{class:"token string"},'"services"'),n(", "),s("span",{class:"token string"},'"workstation"'),n(", "),s("span",{class:"token string"},'"image"'),s("span",{class:"token punctuation"},"]"),n(" is expected to eq "),s("span",{class:"token string"},'"learnchef/inspec_workstation"'),n(` + ✔ `),s("span",{class:"token punctuation"},"["),s("span",{class:"token string"},'"services"'),n(", "),s("span",{class:"token string"},'"workstation"'),n(", "),s("span",{class:"token string"},'"volumes"'),s("span",{class:"token punctuation"},"]"),n(" is expected to "),s("span",{class:"token function"},"cmp"),n(),s("span",{class:"token operator"},"=="),n(),s("span",{class:"token string"},'".:/root"'),n(` + +Test Summary: `),s("span",{class:"token number"},"2"),n(" successful, "),s("span",{class:"token number"},"0"),n(" failures, "),s("span",{class:"token number"},"0"),n(` skipped +`)])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"})])],-1),x=l(`If you received an error above! - Concept Check
If you saw this as your output:
Profile: InSpec Profile (docker-workstations)
+Version: 0.1.0
+Target: local://
+Target ID: 6dcb9e6f-5ede-5474-9521-595fadf5c7ce
+
+ YAML /path/to/docker-compose.yml
+ ↺ Can't find file: /path/to/docker-compose.yml
+
+Test Summary: 0 successful, 0 failures, 1 skipped
+It is because you did not give YOUR path to the docker-compose file. You need to replace the path in your example.rb file to be something like this:
describe yaml('/workspaces/saf-training-lab-environment/resources/docker-compose.yml') do
+ its(['services', 'workstation', 'image']) { should eq 'learnchef/inspec_workstation' }
+ its(['services', 'workstation', 'volumes']) { should cmp '.:/root' }
+end
+Going back to the control, we will write it using a resource that doesn't exist called docker-compose-config that is going to take a path as a parameter.
Remember the idea of Test Driven Development (TDD), the red-green-clean cycle. This way of development is driven by the tests. In this way, you know when you have succeeded while developing something new! In other words, before writing a solution, first write the test (which will fail - red), so that you know exactly what the expectation should be and when you have achieved it. Then you can write the solution to make the test pass (green). Finally, clean up the solution to make it easy to read and efficient!
In the libraries directory of the profile we will make a docker_compose_config.rb file, , the content of the file should look like this:
# encoding: utf-8
+# copyright: 2019, The Authors
+
+class DockerComposeConfig < Inspec.resource(1)
+
+ name 'docker_compose_config'
+
+end
+We will get an error saying we gave it the wrong number of arguments: was given 1 but expected 0. This is because every class in Ruby that has a parameter must have an initialize function to accept that parameter.
# encoding: utf-8
+# copyright: 2019, The Authors
+
+class DockerComposeConfig < Inspec.resource(1)
+
+ name 'docker_compose_config'
+
+ def initialize(path)
+ @path = path
+ end
+
+end
+Now let's run the profile once more.
`,3),W=s("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[s("pre",{class:"language-bash"},[s("code",null,[n("inspec "),s("span",{class:"token builtin class-name"},"exec"),n(` docker-workstations +`)])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"})])],-1),z=s("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[s("pre",{class:"language-bash"},[s("code",null,[n("Profile: InSpec Profile "),s("span",{class:"token punctuation"},"("),n("docker-workstations"),s("span",{class:"token punctuation"},")"),n(` +Version: `),s("span",{class:"token number"},"0.1"),n(`.0 +Target: local:// +Target ID: 6dcb9e6f-5ede-5474-9521-595fadf5c7ce + + YAML /workspaces/saf-training-lab-environment/resources/docker-compose.yml + ✔ `),s("span",{class:"token punctuation"},"["),s("span",{class:"token string"},'"services"'),n(", "),s("span",{class:"token string"},'"workstation"'),n(", "),s("span",{class:"token string"},'"image"'),s("span",{class:"token punctuation"},"]"),n(" is expected to eq "),s("span",{class:"token string"},'"learnchef/inspec_workstation"'),n(` + ✔ `),s("span",{class:"token punctuation"},"["),s("span",{class:"token string"},'"services"'),n(", "),s("span",{class:"token string"},'"workstation"'),n(", "),s("span",{class:"token string"},'"volumes"'),s("span",{class:"token punctuation"},"]"),n(" is expected to "),s("span",{class:"token function"},"cmp"),n(),s("span",{class:"token operator"},"=="),n(),s("span",{class:"token string"},'".:/root"'),n(` + docker_compose_config + × services.workstation.image + undefined method `),s("span",{class:"token variable"},[s("span",{class:"token variable"},"`"),n("services' "),s("span",{class:"token keyword"},"for"),n(),s("span",{class:"token comment"},"#<#This time the profile runs, but we get a message that the docker_compose_config resource does not have the services method. So let's define that method now:
# encoding: utf-8
+# copyright: 2019, The Authors
+
+class DockerComposeConfig < Inspec.resource(1)
+
+ name 'docker_compose_config'
+
+ def initialize(path)
+ @path = path
+ end
+
+ def services
+
+ end
+
+end
+Start by just defining the services method. Then, let's run the profile once more.
Now we got a different failure that tells us a nil value was returned. So now we will go ahead and define the services method. We will use an already existing InSpec resource to parse the path file.
# encoding: utf-8
+# copyright: 2019, The Authors
+
+class DockerComposeConfig < Inspec.resource(1)
+
+ name 'docker_compose_config'
+
+ def initialize(path)
+ @path = path
+ @yaml = inspec.yaml(path)
+ end
+
+ def services
+ @yaml['services']
+ end
+
+end
+Now let's run the profile once more.
`,3),j=s("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[s("pre",{class:"language-bash"},[s("code",null,[n("inspec "),s("span",{class:"token builtin class-name"},"exec"),n(` docker-workstations +`)])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"})])],-1),B=s("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[s("pre",{class:"language-bash"},[s("code",null,[n("Profile: InSpec Profile "),s("span",{class:"token punctuation"},"("),n("docker-workstations"),s("span",{class:"token punctuation"},")"),n(` +Version: `),s("span",{class:"token number"},"0.1"),n(`.0 +Target: local:// +Target ID: 6dcb9e6f-5ede-5474-9521-595fadf5c7ce + + YAML /workspaces/saf-training-lab-environment/resources/docker-compose.yml + ✔ `),s("span",{class:"token punctuation"},"["),s("span",{class:"token string"},'"services"'),n(", "),s("span",{class:"token string"},'"workstation"'),n(", "),s("span",{class:"token string"},'"image"'),s("span",{class:"token punctuation"},"]"),n(" is expected to eq "),s("span",{class:"token string"},'"learnchef/inspec_workstation"'),n(` + ✔ `),s("span",{class:"token punctuation"},"["),s("span",{class:"token string"},'"services"'),n(", "),s("span",{class:"token string"},'"workstation"'),n(", "),s("span",{class:"token string"},'"volumes"'),s("span",{class:"token punctuation"},"]"),n(" is expected to "),s("span",{class:"token function"},"cmp"),n(),s("span",{class:"token operator"},"=="),n(),s("span",{class:"token string"},'".:/root"'),n(` + docker_compose_config + × services.workstation.image + undefined method `),s("span",{class:"token variable"},[s("span",{class:"token variable"},"`"),n("workstation' "),s("span",{class:"token keyword"},"for"),n(),s("span",{class:"token operator"},"<"),n("Hash:0x0000000003abada"),s("span",{class:"token operator"},[s("span",{class:"token file-descriptor important"},"8"),n(">")]),n(` + × services.workstation.volumes + undefined method `),s("span",{class:"token variable"},"`")]),n("workstation' "),s("span",{class:"token keyword"},"for"),n(),s("span",{class:"token operator"},"<"),n("Hash:0x0000000003abada"),s("span",{class:"token operator"},[s("span",{class:"token file-descriptor important"},"8"),n(">")]),n(` + +Test Summary: `),s("span",{class:"token number"},"2"),n(" successful, "),s("span",{class:"token number"},"2"),n(" failures, "),s("span",{class:"token number"},"0"),n(` skipped +`)])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"})])],-1),X=l(`You will notice that it parses correctly, but instead of our result we end up getting a hash. We need to convert the hash into an object that appears like other objects so that we may use our dot notation. So we will wrap our hash in a Ruby class called a Hashie::Mash. This gives us a quick way to convert a hash into a Ruby object with a number of methods attached to it. You will have to import the Hashie library by running gem install hashie and import it in the resource file to be used. It and is written as follows:
# encoding: utf-8
+# copyright: 2019, The Authors
+
+require "hashie/mash"
+
+class DockerComposeConfig < Inspec.resource(1)
+
+ name 'docker_compose_config'
+
+ def initialize(path)
+ @path = path
+ @yaml = inspec.yaml(path)
+ end
+
+ def services
+ Hashie::Mash.new(@yaml['services'])
+ end
+
+end
+Lets run the profile again.
`,3),U=s("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[s("pre",{class:"language-bash"},[s("code",null,[n("inspec "),s("span",{class:"token builtin class-name"},"exec"),n(` docker-workstations +`)])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"})])],-1),K=s("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[s("pre",{class:"language-bash"},[s("code",null,[n("Profile: InSpec Profile "),s("span",{class:"token punctuation"},"("),n("docker-workstations"),s("span",{class:"token punctuation"},")"),n(` +Version: `),s("span",{class:"token number"},"0.1"),n(`.0 +Target: local:// +Target ID: 6dcb9e6f-5ede-5474-9521-595fadf5c7ce + + YAML /workspaces/saf-training-lab-environment/resources/docker-compose.yml + ✔ `),s("span",{class:"token punctuation"},"["),s("span",{class:"token string"},'"services"'),n(", "),s("span",{class:"token string"},'"workstation"'),n(", "),s("span",{class:"token string"},'"image"'),s("span",{class:"token punctuation"},"]"),n(" is expected to eq "),s("span",{class:"token string"},'"learnchef/inspec_workstation"'),n(` + ✔ `),s("span",{class:"token punctuation"},"["),s("span",{class:"token string"},'"services"'),n(", "),s("span",{class:"token string"},'"workstation"'),n(", "),s("span",{class:"token string"},'"volumes"'),s("span",{class:"token punctuation"},"]"),n(" is expected to "),s("span",{class:"token function"},"cmp"),n(),s("span",{class:"token operator"},"=="),n(),s("span",{class:"token string"},'".:/root"'),n(` + docker_compose_config + ✔ services.workstation.image is expected to eq `),s("span",{class:"token string"},'"learnchef/inspec_workstation"'),n(` + ✔ services.workstation.volumes is expected to `),s("span",{class:"token function"},"cmp"),n(),s("span",{class:"token operator"},"=="),n(),s("span",{class:"token string"},'".:/root"'),n(` + +Test Summary: `),s("span",{class:"token number"},"4"),n(" successful, "),s("span",{class:"token number"},"0"),n(" failures, "),s("span",{class:"token number"},"0"),n(` skipped +`)])]),s("div",{class:"line-numbers","aria-hidden":"true"},[s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"}),s("div",{class:"line-number"})])],-1),Z=s("p",null,"Everything passed!",-1),J=s("div",{class:"hint-container info"},[s("p",{class:"hint-container-title"},"Check your work"),s("p",null,"Check your work with the InSpec video below that walks through this docker resource example!")],-1),Q=s("div",{class:"video-container"},[s("iframe",{width:"1462",height:"762",src:"https://www.youtube.com/embed/9rbb2RWa9Oo?list=PLSZbtIlMt5rcbXOpMRucKzRMXR7HX7awy",title:"YouTube video player",frameborder:"0",allow:"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture",allowfullscreen:""})],-1);function $(ss,ns){const i=p("CodeTabs");return u(),d("div",null,[m,o(i,{id:"16",data:[{id:"Command"},{id:"Output"}]},{title0:e(({value:a,isActive:t})=>[n("Command")]),title1:e(({value:a,isActive:t})=>[n("Output")]),tab0:e(({value:a,isActive:t})=>[v]),tab1:e(({value:a,isActive:t})=>[b]),_:1}),g,o(i,{id:"37",data:[{id:"Command"},{id:"Output"}]},{title0:e(({value:a,isActive:t})=>[n("Command")]),title1:e(({value:a,isActive:t})=>[n("Output")]),tab0:e(({value:a,isActive:t})=>[h]),tab1:e(({value:a,isActive:t})=>[f]),_:1}),w,o(i,{id:"52",data:[{id:"Command"},{id:"Output"}]},{title0:e(({value:a,isActive:t})=>[n("Command")]),title1:e(({value:a,isActive:t})=>[n("Output")]),tab0:e(({value:a,isActive:t})=>[y]),tab1:e(({value:a,isActive:t})=>[_]),_:1}),x,o(i,{id:"81",data:[{id:"Tests"},{id:"Generic Tests"}]},{title0:e(({value:a,isActive:t})=>[n("Tests")]),title1:e(({value:a,isActive:t})=>[n("Generic Tests")]),tab0:e(({value:a,isActive:t})=>[C]),tab1:e(({value:a,isActive:t})=>[A]),_:1}),T,o(i,{id:"92",data:[{id:"Command"},{id:"Output"}]},{title0:e(({value:a,isActive:t})=>[n("Command")]),title1:e(({value:a,isActive:t})=>[n("Output")]),tab0:e(({value:a,isActive:t})=>[I]),tab1:e(({value:a,isActive:t})=>[S]),_:1}),D,s("div",O,[R,P,o(i,{id:"111",data:[{id:"Command"},{id:"Options"}]},{title0:e(({value:a,isActive:t})=>[n("Command")]),title1:e(({value:a,isActive:t})=>[n("Options")]),tab0:e(({value:a,isActive:t})=>[q]),tab1:e(({value:a,isActive:t})=>[M]),_:1})]),N,o(i,{id:"123",data:[{id:"Command"},{id:"Output"}]},{title0:e(({value:a,isActive:t})=>[n("Command")]),title1:e(({value:a,isActive:t})=>[n("Output")]),tab0:e(({value:a,isActive:t})=>[Y]),tab1:e(({value:a,isActive:t})=>[V]),_:1}),F,o(i,{id:"138",data:[{id:"Command"},{id:"Output"}]},{title0:e(({value:a,isActive:t})=>[n("Command")]),title1:e(({value:a,isActive:t})=>[n("Output")]),tab0:e(({value:a,isActive:t})=>[W]),tab1:e(({value:a,isActive:t})=>[z]),_:1}),E,o(i,{id:"153",data:[{id:"Command"},{id:"Output"}]},{title0:e(({value:a,isActive:t})=>[n("Command")]),title1:e(({value:a,isActive:t})=>[n("Output")]),tab0:e(({value:a,isActive:t})=>[L]),tab1:e(({value:a,isActive:t})=>[H]),_:1}),G,o(i,{id:"168",data:[{id:"Command"},{id:"Output"}]},{title0:e(({value:a,isActive:t})=>[n("Command")]),title1:e(({value:a,isActive:t})=>[n("Output")]),tab0:e(({value:a,isActive:t})=>[j]),tab1:e(({value:a,isActive:t})=>[B]),_:1}),X,o(i,{id:"183",data:[{id:"Command"},{id:"Output"}]},{title0:e(({value:a,isActive:t})=>[n("Command")]),title1:e(({value:a,isActive:t})=>[n("Output")]),tab0:e(({value:a,isActive:t})=>[U]),tab1:e(({value:a,isActive:t})=>[K]),_:1}),Z,J,Q])}const is=r(k,[["render",$],["__file","06.html.vue"]]);export{is as default}; diff --git a/assets/06.html-mS6M1fnL.js b/assets/06.html-mS6M1fnL.js new file mode 100644 index 000000000..80067258e --- /dev/null +++ b/assets/06.html-mS6M1fnL.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-0f54d1bf","path":"/courses/user/06.html","title":"6. How to Run InSpec","lang":"en-US","frontmatter":{"order":6,"next":"07.md","title":"6. How to Run InSpec","author":"Aaron Lippold","headerDepth":3,"description":"6. 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! 6.1 Requirements To run InSpec, you must hav...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/user/06.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"6. How to Run InSpec"}],["meta",{"property":"og:description","content":"6. 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! 6.1 Requirements To run InSpec, you must hav..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"6. How to Run InSpec\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"6. How to Run InSpec","slug":"_6-how-to-run-inspec","link":"#_6-how-to-run-inspec","children":[{"level":3,"title":"6.1 Requirements","slug":"_6-1-requirements","link":"#_6-1-requirements","children":[]},{"level":3,"title":"6.2 The InSpec Command Formula","slug":"_6-2-the-inspec-command-formula","link":"#_6-2-the-inspec-command-formula","children":[]},{"level":3,"title":"6.3 How to Deploy InSpec","slug":"_6-3-how-to-deploy-inspec","link":"#_6-3-how-to-deploy-inspec","children":[]}]}],"git":{},"readingTime":{"minutes":3.46,"words":1039},"filePathRelative":"courses/user/06.md","autoDesc":true}');export{e as data}; diff --git a/assets/06.html-ubMevqRY.js b/assets/06.html-ubMevqRY.js new file mode 100644 index 000000000..94d8dec53 --- /dev/null +++ b/assets/06.html-ubMevqRY.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-2abb3b46","path":"/courses/beginner/06.html","title":"6. Inputs in InSpec","lang":"en-US","frontmatter":{"order":6,"next":"07.md","title":"6. Inputs in InSpec","author":"Aaron Lippold","description":"Refactoring the code to use Inputs Your my_nginx profile is off to a great start. As your requirements evolve, you can add additional controls. You can also run this profile as ...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/beginner/06.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"6. Inputs in InSpec"}],["meta",{"property":"og:description","content":"Refactoring the code to use Inputs Your my_nginx profile is off to a great start. As your requirements evolve, you can add additional controls. You can also run this profile as ..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"6. Inputs in InSpec\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"Refactoring the code to use Inputs","slug":"refactoring-the-code-to-use-inputs","link":"#refactoring-the-code-to-use-inputs","children":[]},{"level":2,"title":"Input File Example","slug":"input-file-example","link":"#input-file-example","children":[]}],"git":{},"readingTime":{"minutes":3.39,"words":1017},"filePathRelative":"courses/beginner/06.md","autoDesc":true}');export{e as data}; diff --git a/assets/07.html-AUiZ2lcd.js b/assets/07.html-AUiZ2lcd.js new file mode 100644 index 000000000..7a5cdc152 --- /dev/null +++ b/assets/07.html-AUiZ2lcd.js @@ -0,0 +1,54 @@ +import{_ as s}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as a,o,c as r,d as t,e,b as l,a as p,f as n}from"./app-PAvzDPkc.js";const c="/saf-training/assets/Codespaces_InputFile_NGINX-fuC7bzWS.png",u={},d=n('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.
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.
Best Practice
It is best practice to always run profiles with inputs so that the profile is properly tailored to your environment.
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.
Caution
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.
To tailor the tested values for your deployment or organizationally defined values, you may update the inputs.
',9),h={href:"https://docs.chef.io/inspec/inputs/",target:"_blank",rel:"noopener noreferrer"},f=n(`For the NGINX example, we are going to add the following inputs. Make a new file called inputs.yml in your lab environment:
inputs.yml file.---
+key_file_path: /etc/ssl/nginx-selfsigned.pem
+org_allowed_nginx_version: 1.23.1
+nginx_owner: "nginx"
+uses_pki: false
+sys_admin: ["root"]
+sys_admin_group: ["root"]
+In your codespaces, it should look like this:
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.
To determine the value itself, you should think about the environment, talk to your assessor, and explore the target to see if you can find the necessary information.
If the profile does not have a "Tailoring to Your Environment" section in their README, then you can reference the inspec.yml file to see what inputs are defined and available and what their default values are. However, remember not to modify the inspec.yml file itself.
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.
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.
In software development, the decision between making many small pull requests (micro PRs) or fewer, larger pull requests (massive PRs) often depends on the context. Both approaches have their benefits and challenges.
Micro PRs involve making frequent, small changes to the codebase. Each PR is focused on a single task or feature.
Benefits:
Challenges:
Massive PRs involve making larger, more comprehensive changes to the codebase. Each PR may encompass multiple tasks or features.
Benefits:
Challenges:
The choice between micro and massive PRs can significantly impact the workflows in our Patch Update, Release Update, and Major Version Update.
In conclusion, the choice between micro and massive PRs depends on the specific needs and circumstances of your project. It's important to strike a balance that maximizes efficiency while minimizing risk, and fosters effective collaboration within your team.
',18);function g(f,p){const t=i("ExternalLinkIcon");return a(),n("div",null,[s("p",null,[e("This project follows the "),s("a",h,[e("GitFlow model"),o(t)]),e(" for managing the repository, accepting pull requests (PRs), and merging changes into the profile.")]),d])}const v=r(l,[["render",g],["__file","07.html.vue"]]);export{v as default}; diff --git a/assets/07.html-VaK3TpAa.js b/assets/07.html-VaK3TpAa.js new file mode 100644 index 000000000..3a5f8731b --- /dev/null +++ b/assets/07.html-VaK3TpAa.js @@ -0,0 +1 @@ +import{_ as i}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as a,o as n,c as o,b as s,f as e}from"./app-PAvzDPkc.js";const r="/saf-training/assets/edit_controls-MHnoPDv9.png",l="/saf-training/assets/selecting_controls-Pm5Uy1WO.png",c="/saf-training/assets/selected_control-HEYLnC55.png",h="/saf-training/assets/assigning_status-7fj2pa_U.png",u="/saf-training/assets/inherently_met_control-Rzkm4J9Q.png",d="/saf-training/assets/inherently_met_control_picking_status-KMCfe_FE.png",p="/saf-training/assets/justification-QYpJb_Oi.png",m="/saf-training/assets/saving_requirement-nk4uDv2L.png",f="/saf-training/assets/saving_requirement_comment-3OcjGmwr.png",g="/saf-training/assets/revision_history-7KQ-L5o4.png",y="/saf-training/assets/before_and_after-1suZerLp.png",b={},w=e('For your Component, you'll need to decide what requirements are appliable to your specific Component (hint: not all of them will be). Of the applicable requirements, you'll need to tailor them to give specific implementation guidance.
Controls vs. Requirements
You may note that Vulcan refers to the STIG requirements as "controls." A security control is an action taken by an organization in order to meet a security requirement.
STIGs are technically comprised of a set of requirements, but each requirement's main focus is describing a control to meet that requirement (i.e. the Check and Fix content).
You'll see a view of the requirement's text fields, like the vulnerability discussion, the check text, and the fix text.
Note how all of these text fields are:
We can't edit these text fields yet because we haven't yet told Vulcan if this requirement is even applicable to our Component. Let's fix that.
The process of tailoring SRG requirements into specific STIG controls first requires you to determine which of the following statuses applies to each requirement[1]:
Applicable – Configurable: The product requires configuration or the application of policy settings to achieve compliance.
Applicable – Inherently Meets: The product is compliant in its initial state and cannot be subsequently reconfigured to a noncompliant state.
Applicable – Does Not Meet: There are no technical means to achieve compliance.
Not Applicable: The requirement addresses a capability or use case that the product does not support.
If you select any status other than "Applicable - Configurable" for a requirement, you'll need to fill out a few fields explaining why you did so. We'll take a look at a requirement like that in a moment.
Based on the above definitions, we can use the following workflow to determine the right status.
',19),q=e('The requirement's title is "The operating system must audit all account creations."
This requirement does apply. RHEL9, like any other operating system, must have a functioning auditing system; no inherent aspect of RHEL would change this.
RHEL9, like all operating systems, has a built in auditing capability. The auditing capability is configurable (i.e. it is possible to have the system configured to either meet or not meet this requirement).
How do we know all this about the system?
If you are not familiar with the RHEL9 auditing system, don't worry; it's just an example we're using for the class. We promise we will not quiz you on how the auditd service works.
If you have to develop STIG content for a project, it will concern a Component that you are familiar with enough to answer these questions (or are at least in a position to research).
We would consider this requirement Applicable - Configurable. The system is capable of complying with the SRG requirement, but only if properly configured.
Hint: Most SRG requirements wind up being applicable to Components. A handful may be either Not Applicable, Inherently Met or Inherently Not Met. We still have to check.
Note that once we select the status, the text fields become editable. Now we can tailor the general guidance from the SRG into specific guidance.
Before we do that, let's investigate a the Status field a bit more.
Our title here is "The operating system must obscure feedback of authentication information during the authentication process to protect the information from possible exploitation/use by unauthorized individuals."
Yes, this requirement still applies. Like most requirements, RHEL9 doesn't have any quirks that would make this requirement not apply.
However, you may know that RHEL (and all Linux OSes) obscure user passwords when they are entered either into the GUI or on the terminal. This behavior is baked into the RHEL source code -- there is no way for a user to configure the system to not do this.
As such, the status should be Applicable - Inherently Meets.
Notice that this time, several of the fields in the Vulcan editing window changed.
If a requirement is flagged as any of Not Applicable, Inherently Met, or Inherently Not Met, then we need to offer proof that this is the case, and give the end users guidance on how to mitigate the vulnerability if the requirement cannot be met.
If we select any of those statuses in Vulcan, we therefore get a different set of fields to complete. We can't describe them better than DISA can, so we will refer you to the Vendor STIG guide[2] for the definitions of the new fields.
Per Per the Vendor STIG Process Guide section 4.1.15 -
"The Mitigation offers a method for minimizing risk. Mitigations do not eliminate the need for the requirement.
The “Mitigation” field must be populated if the status of the requirement is Applicable – Does Not Meet.
After the mitigation, include a summary statement to address any impact to the overall risk associated with this requirement.
Example summary statements:
An “Applicable – Does Not Meet” vulnerability may be fully mitigated by the application of another STIG check or by the underlying operating system. In these instances, include a statement in the Mitigation as shown in the example below.
Examples of risk mitigated by other STIG requirements:
Per the Vendor STIG Process Guide section 4.1.16 -
"Populate this information for requirements that have a status of Applicable – Inherently Meets. The Artifact Description describes the artifacts or substantiating information that shows how the product inherently meets the requirement.
All self-certification claims must be accompanied by supporting vendor documentation, which taken as a whole, provides DISA with reasonable assurance that the particular requirement has been met.
This field provides citations to the documentary evidence that describe how each requirement is satisfied. Examples of artifacts include:
Note: Blogs and email messages are not sufficient documentation to support an Applicable – Inherently Meets status."
Per the Vendor STIG Process Guide section 4.1.17 -
"For requirements that have a status of Not Applicable:
For requirements that have a status of Applicable – Does Not Meet:
For requirements that have a status of Applicable – Inherently Meets
What about the Vendor Comments field?
You may note that picking any status in Vulcan opens the Vendor Comments field for editing.
That field is purely stored in Vulcan and will not be included in any exports. It exists for the content authors to leave comments on the process of writing the requirement.
For example, an author may add their references for a control's Check or Fix text in the Vendor Comment field, since a reviewer might like to know how they arrived at their conclusions.
We will not complete the Artifact field in RHEL-09-000045 because digging around in the RHEL9 source code is beyond the scope of this course.
RHEL9 automatically obfuscates user passwords in the graphical user interface and at the command line interface.
Like so:
Hit "Save Control" when finished.
You'll be asked to fill out a short description of the change you made. If you are familiar with a source code manager like Git, this process is analogous to adding a commit message when you add code to version control.
Once we save edits, we will see the Revision History on the right side of the screen automatically update:
Clicking the "Rule Was Updated" button will show a before and after view of what was changed by the edit.
You can even select changes to revert, again similar to how a source code manager lets you roll back changes.
Why would I revert changes?
Remember that writing requirements in Vulcan is intended to be done in groups. Authors can and do often disagree about how a requirement should be completed.
Having the ability to granularly revert edits -- and even just track what change was made, when, and by who -- is an important part of a collaborative workflow.
Most of the time you won't need to use RSpec syntax to write a good test. But we want to show you a few neat tricks you can accomplish with RSpec.
We will write a few tests in this section to demonstrate the difference between InSpec's default syntax and RSpec syntax.
Let's pretend we have a new requirement for NGINX:
6. NGINX's /etc/nginx directory should not be empty.
+(It's a bit of an odd requirement, but bear with us for the sake of this example.)
First, we'll try a test that does not use RSpec syntax to illustrate the problem we want to solve:
`,7),w=e("div",{class:"language-ruby line-numbers-mode","data-ext":"rb"},[e("pre",{class:"language-ruby"},[e("code",null,[s("control "),e("span",{class:"token string-literal"},[e("span",{class:"token string"},"'Requirement 6'")]),s(),e("span",{class:"token keyword"},"do"),s(` + impact `),e("span",{class:"token number"},"1.0"),s(` + title `),e("span",{class:"token string-literal"},[e("span",{class:"token string"},"'Checking that /etc/nginx does not return empty'")]),s(` + desc `),e("span",{class:"token string-literal"},[e("span",{class:"token string"},"'Let\\'s do this the ugly way.'")]),s(` + describe command`),e("span",{class:"token punctuation"},"("),e("span",{class:"token string-literal"},[e("span",{class:"token string"},"'ls -al'")]),e("span",{class:"token punctuation"},")"),e("span",{class:"token punctuation"},"."),s("stdout"),e("span",{class:"token punctuation"},"."),s("strip "),e("span",{class:"token keyword"},"do"),s(` + it `),e("span",{class:"token punctuation"},"{"),s(" should_not be_empty "),e("span",{class:"token punctuation"},"}"),s(` + `),e("span",{class:"token keyword"},"end"),s(` +`),e("span",{class:"token keyword"},"end"),s(` +`)])]),e("div",{class:"line-numbers","aria-hidden":"true"},[e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"})])],-1),x=e("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[e("pre",{class:"language-bash"},[e("code",null,[s(" ✔ Requirement "),e("span",{class:"token number"},"6"),s(": Checking that /etc/nginx does not "),e("span",{class:"token builtin class-name"},"return"),s(` empty + ✔ total `),e("span",{class:"token number"},"76"),s(` + drwxr-xr-x `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Nov "),e("span",{class:"token number"},"8"),s(),e("span",{class:"token number"},"20"),s(":21 "),e("span",{class:"token builtin class-name"},"."),s(` + drwxr-xr-x `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Nov "),e("span",{class:"token number"},"8"),s(),e("span",{class:"token number"},"20"),s(":21 "),e("span",{class:"token punctuation"},".."),s(` + -rwxr-xr-x `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"0"),s(" Nov "),e("span",{class:"token number"},"8"),s(),e("span",{class:"token number"},"20"),s(`:21 .dockerenv + lrwxrwxrwx `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"7"),s(" Oct "),e("span",{class:"token number"},"30"),s(" 00:00 bin -"),e("span",{class:"token operator"},">"),s(` usr/bin + drwxr-xr-x `),e("span",{class:"token number"},"2"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Sep "),e("span",{class:"token number"},"29"),s(),e("span",{class:"token number"},"20"),s(`:04 boot + drwxr-xr-x `),e("span",{class:"token number"},"5"),s(" root root "),e("span",{class:"token number"},"360"),s(" Nov "),e("span",{class:"token number"},"8"),s(),e("span",{class:"token number"},"20"),s(`:21 dev + drwxr-xr-x `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Nov "),e("span",{class:"token number"},"1"),s(` 05:12 docker-entrypoint.d + -rwxrwxr-x `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"1620"),s(" Nov "),e("span",{class:"token number"},"1"),s(` 05:11 docker-entrypoint.sh + drwxr-xr-x `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Nov "),e("span",{class:"token number"},"8"),s(),e("span",{class:"token number"},"20"),s(`:21 etc + drwxr-xr-x `),e("span",{class:"token number"},"2"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Sep "),e("span",{class:"token number"},"29"),s(),e("span",{class:"token number"},"20"),s(`:04 home + lrwxrwxrwx `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"7"),s(" Oct "),e("span",{class:"token number"},"30"),s(" 00:00 lib -"),e("span",{class:"token operator"},">"),s(` usr/lib + lrwxrwxrwx `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"9"),s(" Oct "),e("span",{class:"token number"},"30"),s(" 00:00 lib32 -"),e("span",{class:"token operator"},">"),s(` usr/lib32 + lrwxrwxrwx `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"9"),s(" Oct "),e("span",{class:"token number"},"30"),s(" 00:00 lib64 -"),e("span",{class:"token operator"},">"),s(` usr/lib64 + lrwxrwxrwx `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"10"),s(" Oct "),e("span",{class:"token number"},"30"),s(" 00:00 libx32 -"),e("span",{class:"token operator"},">"),s(` usr/libx32 + drwxr-xr-x `),e("span",{class:"token number"},"2"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Oct "),e("span",{class:"token number"},"30"),s(` 00:00 media + drwxr-xr-x `),e("span",{class:"token number"},"2"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Oct "),e("span",{class:"token number"},"30"),s(` 00:00 mnt + drwxr-xr-x `),e("span",{class:"token number"},"2"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Oct "),e("span",{class:"token number"},"30"),s(` 00:00 opt + dr-xr-xr-x `),e("span",{class:"token number"},"228"),s(" root root "),e("span",{class:"token number"},"0"),s(" Nov "),e("span",{class:"token number"},"8"),s(),e("span",{class:"token number"},"20"),s(`:21 proc + drwx------ `),e("span",{class:"token number"},"2"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Oct "),e("span",{class:"token number"},"30"),s(` 00:00 root + drwxr-xr-x `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Nov "),e("span",{class:"token number"},"8"),s(),e("span",{class:"token number"},"20"),s(`:21 run + lrwxrwxrwx `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"8"),s(" Oct "),e("span",{class:"token number"},"30"),s(" 00:00 sbin -"),e("span",{class:"token operator"},">"),s(` usr/sbin + drwxr-xr-x `),e("span",{class:"token number"},"2"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Oct "),e("span",{class:"token number"},"30"),s(` 00:00 srv + dr-xr-xr-x `),e("span",{class:"token number"},"12"),s(" root root "),e("span",{class:"token number"},"0"),s(" Nov "),e("span",{class:"token number"},"8"),s(),e("span",{class:"token number"},"20"),s(`:21 sys + drwxrwxrwt `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Nov "),e("span",{class:"token number"},"1"),s(` 05:12 tmp + drwxr-xr-x `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Oct "),e("span",{class:"token number"},"30"),s(` 00:00 usr + drwxr-xr-x `),e("span",{class:"token number"},"1"),s(" root root "),e("span",{class:"token number"},"4096"),s(" Oct "),e("span",{class:"token number"},"30"),s(` 00:00 var is expected not to be empty +`)])]),e("div",{class:"line-numbers","aria-hidden":"true"},[e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"})])],-1),f=e("p",null,[s("Well. . . it "),e("em",null,"sort of"),s(" works.")],-1),y=e("p",null,`Notice how much output InSpec printed here to answer the simple question of "did this command return empty?" Imagine if we had done this on a directory with many files in it. We'd just be cluttering up the screen (and our report files).`,-1),_=e("div",{class:"hint-container warning"},[e("p",{class:"hint-container-title"},"Wait, couldn't we have just used the directory resource for this?"),e("p",null,[s(`Correct. That would have been a much better way of doing this, and illustrates the general principle of "don't use raw shell commands with the `),e("code",null,"command"),s(' resource unless you have to."')]),e("p",null,"We're just doing it this way for the example.")],-1),A={href:"https://relishapp.com/rspec/rspec-core/docs/subject/explicit-subject",target:"_blank",rel:"noopener noreferrer"},S=e("div",{class:"language-ruby line-numbers-mode","data-ext":"rb"},[e("pre",{class:"language-ruby"},[e("code",null,[s("control "),e("span",{class:"token string-literal"},[e("span",{class:"token string"},"'Requirement 6'")]),s(),e("span",{class:"token keyword"},"do"),s(` + impact `),e("span",{class:"token number"},"1.0"),s(` + title `),e("span",{class:"token string-literal"},[e("span",{class:"token string"},"'Checking that /etc/nginx does not return empty'")]),s(` + desc `),e("span",{class:"token string-literal"},[e("span",{class:"token string"},"'Let\\'s do this the concise way.'")]),s(` + describe `),e("span",{class:"token string-literal"},[e("span",{class:"token string"},'"The /etc/nginx directory"')]),s(),e("span",{class:"token keyword"},"do"),s(` + subject `),e("span",{class:"token punctuation"},"{"),s(" command"),e("span",{class:"token punctuation"},"("),e("span",{class:"token string-literal"},[e("span",{class:"token string"},"'ls -al'")]),e("span",{class:"token punctuation"},")"),e("span",{class:"token punctuation"},"."),s("stdout"),e("span",{class:"token punctuation"},"."),s("strip "),e("span",{class:"token punctuation"},"}"),s(` + it `),e("span",{class:"token punctuation"},"{"),s(" should_not be_empty "),e("span",{class:"token punctuation"},"}"),s(` + `),e("span",{class:"token keyword"},"end"),s(` +`),e("span",{class:"token keyword"},"end"),s(` +`)])]),e("div",{class:"line-numbers","aria-hidden":"true"},[e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"}),e("div",{class:"line-number"})])],-1),I=e("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[e("pre",{class:"language-bash"},[e("code",null,[s(" ✔ Requirement "),e("span",{class:"token number"},"6"),s(": Checking that /etc/nginx does not "),e("span",{class:"token builtin class-name"},"return"),s(` empty + ✔ The /etc/nginx directory is expected not to be empty +`)])]),e("div",{class:"line-numbers","aria-hidden":"true"},[e("div",{class:"line-number"}),e("div",{class:"line-number"})])],-1),O=r('Much better, right? We can override InSpec's default output to print a message that is actually useful.
Info
Another benefit to using subject is preventing command output from being stored in the report.
should vs. expect syntaxUsers familiar with the RSpec testing framework may know that there are two ways to write test statements: should and expect. The RSpec community decided that expect is the preferred syntax.
InSpec recommends the should syntax as it tends to read more easily. However, there are times when the expect syntax will communicate much more clearly to the end-user. InSpec will continue to support both methods of writing tests.
Let's copy the describe shown below directly into our example.rb file (we don't need to wrap them in a control block for this section). Consider this describe block from your my_nginx profile:
The failure_message variable in the above describe block is assigned a value by pure Ruby assignment. Remember how we said that, since InSpec is built on Ruby, any Ruby syntax will work inside an InSpec test? Ruby's string formatting syntax (the #{non_admin_users.join(", ")}) can create a string that lists the users who fail the test by having shell access when they shouldn't.
Writing good failure messages
The trick to writing useful failure messages is to use Ruby to find the subset of all elements we are testing (here, the users) that actually fail the test. We don't need to print a statement for every array element we tested; we only need to print a statement that shows the elements that failed.
Expect syntax and Password HashesHere's another example -- we have an InSpec test that checks if passwords are SHA512 hashes.
As we said, when possible, and when there is a high change of a large set only having a few offending items, attempt to find only those items that could be outside our requirements. If there are none -- wonderful! We met our requirement.
bad_users = inspec.shadow.where { password != "*" && password != "!" && password !~ /\\$6\\$/ }.users # note that SHA12-encrypted passwords are marked by starting with '$6$' in /etc/shadow
+
+describe 'Password hashes in /etc/shadow' do
+ it 'should only contain SHA512 hashes' do
+ failure_message = "Users without SHA512 hashes: #{bad_users.join(', ')}"
+ expect(bad_users).to be_empty, failure_message
+ end
+end
+The file resource is perfect for looking at single files and their properties. However, it does not look at groups of files. To do that, we need to use multiple resources in concert.
Take a look at this example from a profile for use in AWS virtual machines. We use the command resource to run the find command and then use the file resource to investigate each result. Using multiple resources together is one of the key values InSpec provides, allowing you to get at just the data you need when you need it.
command('find ~/* -type f -maxdepth 0 -xdev').stdout.split.each do |fname| # we need to be careful about using 'find' --
+ # there could be a LOT of output if we are not specific enough with the search!
+ describe file(fname) do
+ its('owner') { should cmp 'ec2-user' }
+ end
+end
+Avoid Large Sets or 'Check Everyone at the Door' Approaches
For IO intensive (full filesystem, or global scans) or large scale processes, try to be as specific as possible with your searches. Think about using 'negative logic' vs 'positive logic' - "Find me all the items outside my target set" vs "Look at each item in the set and ensure it has these properties".
This 'find the outsiders' vs 'check everyone at the door' approach can really speed things along. Again, keep your data set as small as possible, don't inspect more than the requirements require!
Try writing your own resources and think about how you could implement them in a profile!
Suggested Resources to start on (Simple):
id retrieves container idimage retrieves image namerepo retrieves the repotag retrieves the tagports retrieves the portscommand retrieves commandbranches checks if branch existscurrent_branch retrieves current branchlast_commit retrieves last commit from loggit_log retrieve log of all commitstag retrieve tag for repoSuggested Resources to start on (Medium):
owner tests if the owner of the file matches the specified value.group tests if the group to which a file belongs matches the specified value.size tests if a file’s size matches, is greater than, or is less than the specified value.contents tests if contents in the file match the value specified in a regular expression.path retrieves path to fileowner tests if the owner of the file matches the specified value.group tests if the group to which a file belongs matches the specified value.size tests if a file’s size matches, is greater than, or is less than the specified value.contents tests if contents in the file match the value specified in a regular expression.path retrieves path to directoryexist tests if the named user existsgid tests the group identifiergroup tests the group to which the user belongsgroups tests two (or more) groups to which the user belongshome tests the home directory path for the usermaxdays tests the maximum number of days between password changesmindays tests the minimum number of days between password changesshell tests the path to the default shell for the useruid tests the user identifierwarndays tests the number of days a user is warned before a password must be changeddaemon daemon returns a string containing the daemon that is allowed in the rule.client_list client_list returns a 2d string array where each entry contains the clients specified for the rule.options options returns a 2d string array where each entry contains any options specified for the rule.Suggested Resources to start on (Hard):
users A list of strings, representing the usernames matched by the filterpasswords A list of strings, representing the encrypted password strings for entries matched by the where filter. Each string may not be an encrypted password, but rather a * or similar which indicates that direct logins are not allowed.last_changes A list of integers, indicating the number of days since Jan 1 1970 since the password for each matching entry was changed.min_days A list of integers reflecting the minimum number of days a password must exist, before it may be changed, for the users that matched the filter.max_days A list of integers reflecting the maximum number of days after which the password must be changed for each user matching the filter.warn_days A list of integers reflecting the number of days a user is warned about an expiring password for each user matching the filter.inactive_days A list of integers reflecting the number of days a user must be inactive before the user account is disabled for each user matching the filter.expiry_dates A list of integers reflecting the number of days since Jan 1 1970 that a user account has been disabled, for each user matching the filter. Value is nil if the account has not expired.count The count property tests the number of records that the filter matched.device_name is the name associated with the device.mount_point is the directory at which the file system is configured to be mounted.file_system_type is the type of file system of the device or partition.mount_options is the options for the device or partition.dump_options is a number used by dump to decide if a file system should be backed up.file_system_options is a number that specifies the order the file system should be checked.parse_conf parse the conf filefetch_connectors retrieves keys port, protocol, timeout, redirect, sslprotocol, scheme, sslenable, clientauth, secureinspec exec my_nginx -t docker://nginx --reporter cli json:baseline_output.json
+When using InSpec in practice, most users aggregate report files from multiple systems over time, so we recommend that you generate reports that specify:
inspec exec my_nginx --reporter json:nginx-$(date +"%Y-%m-%d-%H-%M-%S").json
+Here we add a bash eval (the $(date +"%Y-%m-%d-%H-%M-%S")) to our filename when we invoke inspec exec. Now we can run tests multiple times with the same command and get a different filename each time.
Caution
Note that if you save InSpec results to a file (such as with the json reporter), and then re-run the same command, you will overwrite the original contents of that file with the more recent results. Be sure that all of your reports have unique names.
inspec exec my_nginx --reporter cli json:tmp/output.json
+inspec exec my_nginx --reporter junit2:tmp/junit.xml html:www/index.html
+inspec exec my_nginx --reporter json junit2:tmp/junit.xml | tee out.json
+InSpec also lets you capture all of these reporter options in a configuration file:
{
+ "reporter": {
+ "cli": {
+ "stdout": true
+ },
+ "json": {
+ "file": "tmp/output.json",
+ "stdout": false
+ }
+ }
+}
+The following are supported reporters:
InSpec includes the --enhanced-outcomes flag to enrich the output format slightly if more detail is needed.
When this flag is passed, the control level status outcomes of the profile execution are Passed, Failed, Not Applicable (N/A), Not Reviewed (N/R), or Error (ERR).
So far, we have been executing InSpec profiles that we have written ourselves and saved to the local machine. InSpec also gives you the ability to execute a profile that lives on the other end of an HTTP/S link or a .git link.
inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx
+Wait, what if I can't publish to GitHub?
Not everyone can open source their code, or make it available on the open Internet. Your organization or environment may be more suited to using a private code repository (e.g. GitLab or BitBucket) to store profiles. InSpec supports passing authentication tokens as part of profile locations:
inspec exec https://API_TOKEN@gitlab.supersecret.com/profiles/inspec_baseline.git
+Let's try running an already-complete profile and generating a report.
The following command will run the SAF Validation Library's NGINX baseline profile from MITRE GitHub, and use the reporter to output a json file. You will need this JSON file for the next section, where we'll load our results into Heimdall:
inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx --reporter cli json:nginx-full-baseline-$(date +"%Y-%m-%d-%H-%M-%S").json
+https://github.com/mitre/nginx-stigready-baseline to specify the profile.-t docker://nginx.--reporter cli json:./results/nginx_vanilla_results.json--input-file inputs.ymlTo execute this command to run the GitHub profile on your target system, run this inspec exec command.
inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx --input-file inputs.yml --reporter cli json:./results/nginx_vanilla_results.json
+Enter the command from the previous step in your terminal and press enter. It will take a moment to start running.
You should see output similar to that below. The whole profile should execute in only a couple minutes.
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
+ ...
+ × is expected not to be nil
+ expected: not nil
+ got: nil
+ ↺ This test is NA because the ssl_client_certificate directive has not been configured.
+ ↺ V-56029: The NGINX web server must augment re-creation to a stable and known
+ baseline.
+ ↺ This test requires a Manual Review: Interview the SA and ask for documentation on the
+ disaster recovery methods for the NGINX web server in the event of the necessity for rollback.
+ ↺ V-56031: The NGINX web server must encrypt user identifiers and passwords.
+ ↺ This check is NA because NGINX does not manage authentication.
+ ✔ V-56033: The web server must install security-relevant software updates within
+ the configured time period directed by an authoritative source (e.g., IAVM,
+ CTOs, DTMs, and STIGs).
+ ✔ NGINX version v1.25.3 installed is not more then one patch level behind v1.25.2 is expected to cmp >= "1.25.2"
+ ✔ NGINX version v1.25.3 installed is greater then or equal to the organization approved version v1.23.1 is expected to cmp >= "1.23.1"
+ ✔ V-56035: The NGINX web server must display a default hosted application web page, not
+ a directory listing, when a requested web page cannot be found.
+ ✔ The root directory /usr/share/nginx/html should include the default index.html file.
+ ↺ V-61353: The web server must remove all export ciphers to protect the
+ confidentiality and integrity of transmitted information. (2 skipped)
+ ↺ This test is NA because the ssl_prefer_server_ciphers directive has not been configured.
+ ↺ This test is NA because the ssl_ciphers directive has not been configured.
+
+
+Profile Summary: 27 successful controls, 26 control failures, 36 controls skipped
+Test Summary: 137 successful, 91 failures, 55 skipped
+You see that many of the tests pass, while others fail and may require investigation.
`,10),_=e("h4",{id:"_8-3-2-results-saved-to-a-file",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#_8-3-2-results-saved-to-a-file","aria-hidden":"true"},"#"),n(" 8.3.2 Results saved to a file")],-1),w=e("p",null,[n("You should also see your results in a JSON file located in "),e("code",null,"/results"),n(" folder with the name that you specified in the command, for example "),e("code",null,"nginx_vanilla_results.json"),n('. 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.'),e("br"),e("img",{src:p,alt:"The Results Folder",loading:"lazy"})],-1),j={class:"hint-container details"},I=a(`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).
$ inspec exec /root/my_nginx -t ssh://TARGET_USERNAME:TARGET_PASSWORD@TARGET_IP --reporter cli json:baseline_output.json
+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.
Output json to screen.
inspec exec /root/my_nginx --reporter json
+or
+inspec exec /root/my_nginx --reporter json:-
+Output yaml to screen
inspec exec /root/my_nginx --reporter yaml
+or
+inspec exec /root/my_nginx --reporter yaml:-
+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.
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.
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 --.
inspec exec --reporter json junit:/tmp/junit.xml -- profile1 profile2
Output cli to screen and write json to a file.
{
+ "reporter": {
+ "cli": {
+ "stdout": true
+ },
+ "json": {
+ "file": "/tmp/output.json",
+ "stdout": false
+ }
+ }
+}
+The following are the current supported reporters:
Let's go back to our requirement for earlier that we said was "Applicable - Configurable." It's time to fill it out completely.
The Check and Fix fields are the ones that acually tell the user:
As such, these fields represent the bulk of what you will need to research and modify when constructing your security guidance.
DISA requires that STIG authors use very specific language for these sections. Again, we will leverage the official guidance[1] for instructions.
Per the Vendor STIG Process Guide section 4.1.11 -
"The Check is used to provide specific instruction on how to validate product configuration settings. It must include any information and procedures necessary for validating the configured value.
The Check should also state:
If the vendor is leveraging third-party tools to satisfy a requirement, identify in the Check the product and the specific steps to check compliance.
If the product is expected to be compatible with a number of third-party tools, include in the Check general instructions that would enable a systems administrator with reasonable familiarity with the third-party tool to perform the necessary procedure.
For example, if the requirement is to block certain TCP ports on a firewall, a general instruction to this effect may suffice.
"
"Write the Check so the user can easily follow the steps to assess and determine compliance.
Check text example:
If Bluetooth connectivity is required to facilitate use of approved external devices, this is not applicable.
+
+To determine if any hardware components for Bluetooth are loaded in the system, run the following command:
+
+# sudo kextstat | grep -i Bluetooth
+
+If a result is returned, this is a finding.
+
+In some cases, determining when an item is NOT a finding might be appropriate.
+Check text example:
If the "xyz" parameter is set to "5", this is not a finding.
+
+When using a command to inspect the status of a host, listing example output can be helpful. The output must comply with STIG requirements unless an example of a failure is needed and is clearly explained.
+Check text example:
Find the file systems that contain the directories being exported with the following command:
+
+# cat /etc/fstab | grep nfs
+UUID=e06097bb-cfcd-437b-9e4d-a691f5662a7d /store nfs rw,nosuid 0 0
+
+If a file system found in "/etc/fstab" refers to NFS and does not have the "nosuid" option set, this is a finding.
+"
The Finding Statement
We want to call out the Finding statement as particularly important. STIG content must be very clear on when exactly a misconfiguration becomes a finding, or non-compliance with the requirement.
Recall that a STIG is intended to be something that can be followed by someone who is not an expert in the system at hand; recall also that we want to eventually automate these checks, and as such we want to make it easier for us as well!
Per the Vendor STIG Process Guide section 4.1.11 -
"The Fix is used to provide specific instructions on how to configure the product to comply with the requirement.
After steps in the Fix text are implemented, the resulting system state should be the same no matter how many times the instructions are followed."
"When writing the Fix content, the vendor must include all steps needed to configure the product to comply with the requirement.
Let's go back and try this for requirement RHEL-09-000003. Right now, the requirement is only populated by the original SRG text. We need to tailor this to RHEL9.
Remember that STIG writing is an open-book test. We encourage authors to go back and take a look at how other authors filled out their requirements for similar systems. In fact, the best place to look for reference is usually in a prior major version of the same software. That is, the best place to start for security guidance for RHEL9 is to see what they did for other RHEL versions!
Luckily, Vulcan has access to every STIG and SRG you have uploaded to the instance for cross-referencing.
You'll see a view of every requirement Vulcan can find in its content library that also refers back to the same SRG ID.
You can filter and search through this library for keywords if you like, or even restrict the results to only show content your team has written inside this Vulcan instance's Components. For now, though, we are likely interested only in the published STIGs.
Warning
The real, published RHEL9 STIG is uploaded to this Vulcan instance. For the purposes of this exercise, though, we will use an earlier version of RHEL.
Great! Now we have a Check and Fix field that actually have content. Note also that this content is already following STIG syntax; the commands are very direct, and the line on what counts as a finding is clearly drawn.
Is It Always This Easy?
Prior STIGs are always an excellent starting point, but new STIG content does require research and testing to ensure that guidance from the prior STIGs is still accurate for our current Component.
The Original SRG content
If you scroll down in the requirement window, you can expand out the original SRG content that this STIG requirement was sourced from. This can be useful to reference if you want to make sure your Check and Fix are still addressing the SRG requirement.
Sections 4.1.11 and 4.1.13 of the "Vendor STIG Process", Version 4 Release 1. ↩︎
Software developers create pipelines for the same reason that factory designers create assembly lines. They break processes into logical units and make them repeatable, consistent, and automated.
Pipelines also enable several paradigms in modern DevSecOps development, including continuous integration and continuous delivery (CD).
Continuous Integration (CI) is the practice of requiring all changes to a codebase to pass a test suite before they are committed. CI is implemented on a codebase to make sure that any time a bug is introduced to a codebase, it is caught and corrected as soon as someone tries to commit it, instead of months or years later in operations when it is much more difficult to fix.
Continuous Delivery is the practice of automatically delivering software (such as, for example, by pushing code to live deployment) once it passes a test suite. This is a core practice of DevSecOps -- code should be developed incrementally and small units of functionality should be delivered as soon as they are complete and pass all tests.
A fully mature DevSecOps pipeline will implement both strategies. Note that both CI and CD both presuppose that you have a high-quality, easy to use test suite available. We will create our demo pipeline using an InSpec profile as our test suite.
Have you used pipeline orchestration software other than that mentioned here?
Most of the general concepts discusses in this portion of the class will be covered by any pipeline orchestrator tool, though they wil likely have different terminology for individual features.
Let's learn how to build pipelines by taking on the role of a developer who needs to create a pipeline for a hardened NGINX container image. We can borrow the InSpec profile we've already written for our container to make sure that any time we update the container image, we do not accidentally break any security controls.
We need to:
Real-world pipelines are often used this way in a gold image pipeline, which run on a defined frequency to continuously deliver a secure, updated machine image that can be used as a base for further applications. In this use case, we would take the hardened and validated image we produced as part of the pipeline and save it as our new gold image. This way, developers can grab a "known-good" image to host their applications without having to configure or keep it up to date themselves.
Pipelines are conceptually broken down into a series of individual tasks. The tasks we need to complete in our pipeline include:
',9),x=e("li",null,"Prep - configure our runner for later work (in our case, make sure InSpec is installed and ready to go)",-1),C=e("li",null,[t("Lint - make sure code passes style requirements (in our case, "),e("code",null,"inspec check ."),t(")")],-1),A=e("li",null,"Deploy the test suite (in our case, an NGINX container we want to use as a test system)",-1),S=e("li",null,"Validate - check configuration (in our case, run InSpec against our test system and generate a report)",-1),G=e("li",null,"Verify - confirm if the validation run passed our expectations (in our case, use the SAF CLI to check that the Validation report met our threshold)",-1),D=e("li",null,"Do something with results - e.g. publish our image if it met our expectations and passed the tests",-1),H=e("p",null,[t("GitHub Actions organizes the tasks inside a pipeline into "),e("strong",null,"jobs"),t(". A given pipeline can trigger multiple jobs, but for our sample gold image pipeline we really only need one for storing all of our tasks.")],-1),N=e("h3",{id:"runners",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#runners","aria-hidden":"true"},"#"),t(" Runners")],-1),L=e("p",null,[t("Pipeline orchestrators all have some system for selecting a "),e("strong",null,"runner"),t(" node that will be assigned to handle the tasks we define for the pipeline. Runners are any system -- containers or full virtual machines in a cloud environment -- that handle the actual task execution for a pipeline.")],-1),P={href:"https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners",target:"_blank",rel:"noopener noreferrer"},W=e("p",null,"In the next sections we will create a GitHub Action workflow to handle these jobs for us. We will commit the workflow file to our repository and watch it work!",-1);function V(T,j){const o=a("RouterLink"),n=a("ExternalLinkIcon");return c(),u("div",null,[p,f,m,e("p",null,[t("If you have taken the "),i(o,{to:"/courses/user/"},{default:s(()=>[t("SAF User")]),_:1}),t(" class, you will be familiar with many of the activities we will be doing as part of the sample pipeline in the next few sections, including using Ansible to harden a test image, validating it with InSpec, and using the SAF CLI to assess our results. We will be bundling all those activities together into a pipeline workflow file so that we can automate them.")]),g,e("p",null,[t("We will be building our sample pipeline using "),e("a",b,[t("GitHub Actions"),i(n)]),t(", the pipeline orchestration tool that is built into GitHub. We are using this feature because it is free to use unless we exceed usage limits, and because we can write up a pipeline workflow file right from our GitHub Codespaces lab environment.")]),w,e("ul",null,[e("li",null,[t("GitLab's GitLab "),e("a",_,[t("CI/CD"),i(n)])]),e("li",null,[e("a",y,[t("DroneCI"),i(n)])]),e("li",null,[t("Atlassian's "),e("a",k,[t("BitBucket Pipelines"),i(n)])]),e("li",null,[e("a",v,[t("Jenkins"),i(n)])])]),I,e("ul",null,[x,C,A,e("li",null,[t("Harden the test suite (we will use Ansible like we do in the "),i(o,{to:"/courses/user/10.html"},{default:s(()=>[t("SAF User class")]),_:1}),t(")")]),S,G,D]),H,N,L,e("p",null,[t("In the case of GitHub actions, when we trigger a pipeline, GitHub by default sends the jobs to its cloud environment to hosted runner nodes. The operating system of the runner for a particular job can be specified in the workflow file. See the "),e("a",P,[t("docs"),i(n)]),t(" for details.")]),W])}const O=l(d,[["render",V],["__file","08.html.vue"]]);export{O as default}; diff --git a/assets/08.html-svY7cBD7.js b/assets/08.html-svY7cBD7.js new file mode 100644 index 000000000..a1f006cf3 --- /dev/null +++ b/assets/08.html-svY7cBD7.js @@ -0,0 +1 @@ +import{_ as e}from"./plugin-vue_export-helper-x3n3nnut.js";import{o as a,c as r,f as o}from"./app-PAvzDPkc.js";const t={},c=o('When planning your team's approach, remember that a Security Benchmark is only considered 'complete and valid' when all requirements for that specific Release or Major Version are met. This differs from traditional software projects where features and capabilities can be incrementally added.
A Security Benchmark and its corresponding InSpec Profile are only applicable within the context of a specific 'Release' of that Benchmark.
The choice between a micro or massive approach depends more on your team's work style preference.
Regardless of the approach, the final release of the Benchmark will be the same. The deciding factors for its readiness for release are the expected thresholds, hardening, and validation results.
out of scope for a BenchmarkBenchmarks do not accommodate 'incremental requirements'. Therefore, your team should always work off a fork of the last release. If there is a 'main' or 'development' branch in your profile, it should be considered as a candidate for merging into the next patch or update release.
',8),n=[c];function i(s,d){return a(),r("div",null,n)}const l=e(t,[["render",i],["__file","08.html.vue"]]);export{l as default}; diff --git a/assets/09.html-1G4jKolf.js b/assets/09.html-1G4jKolf.js new file mode 100644 index 000000000..4ead1559b --- /dev/null +++ b/assets/09.html-1G4jKolf.js @@ -0,0 +1,7 @@ +import{_ as e}from"./plugin-vue_export-helper-x3n3nnut.js";import{o as s,c as n,f as a}from"./app-PAvzDPkc.js";const t={},r=a(`When updating the profile, you'll be making one of three types of changes:
v1.12.4 to v1.12.5. We aim to release these updates on a regular schedule, either weekly, bi-weekly, or monthly.The STIGs and CIS Benchmarks are scoped within the Major Version of the software products they represent.
Updates or amendments to a Benchmark's requirements are tracked within the 'Releases' of the Benchmark.
As we mentioned in the previous section, there is no concept of 'back-patching'; it is a 'forward-only' process.
Each requirement is indexed from their source SRG document, aligned to a CCI, and then given a unique Rule ID and STIG ID in the respective XCCDF Benchmark document.
Here is an example of various indices you may recognize:
tag gtitle: 'SRG-OS-000480-GPOS-00227'
+tag gid: 'V-230221'
+tag rid: 'SV-230221r858734_rule'
+tag stig_id: 'RHEL-08-010000'
+tag fix_id: 'F-32865r567410_fix'
+tag cci: ['CCI-000366']
+Now that we have written up some Check and Fix text, it's time to use one of Vulcan's other features -- the InSpec code pane.
We've already used Vulcan to generate a document that has most of the metadata in place that we would need to properly label an automated validation test. Now we can go the last mile or so to a complete security test.
You'll see a code editing window directly in Vulcan. What we can do now is write in the test code we want to use for testing the check we just wrote.
',7),f={class:"hint-container warning"},g=e("p",{class:"hint-container-title"},"Wait, what if I have no idea how to write InSpec code?!",-1),w=e("p",null,"But if you don't have the time for those, don't sweat it; we just want you to know that this is something you can do with Vulcan.",-1),_=c(`That code is as follows:
audit_command = '/etc/passwd'
+
+if virtualization.system.eql?('docker')
+ impact 0.0
+ describe 'Control not applicable - audit config must be done on the host' do
+ skip 'Control not applicable - audit config must be done on the host'
+ end
+else
+ describe 'Command' do
+ it "#{audit_command} is audited properly" do
+ audit_rule = auditd.file(audit_command)
+ expect(audit_rule).to exist
+ expect(audit_rule.key).to cmp 'identity'
+ expect(audit_rule.permissions.flatten).to include('w', 'a')
+ end
+ end
+end
+Note
If you have taken the SAF User class, you have used inspec exec to run code that looks like the above against a target system.
Save the requirement.
Now check the "InSpec Control (Read-Only)" tab. It has used the contents of the other two tabs to assemble a completed InSpec control from your requirement, including the complete context of your STIG control as metadata tags in the test.
We can export this content and start using it immediately if we wish (we'll discuss how in a later section).
Vulcan includes the ability to write InSpec control code right alongside original guidance because we need a tight binding between the human-readable guidance and the machine-readable automation code.
',11),b={href:"https://saf-cli.mitre.org/#xccdf-benchmark-to-inspec-stub",target:"_blank",rel:"noopener noreferrer"},y=e("p",null,[n("You can think of this process as recording the pedigree of your tests into the code, so that you dont lose it as your code moves down the pipeline, and so that you "),e("em",null,"always know why you are running a check"),n(".")],-1),v=e("p",null,"Furthermore, another reason we added the InSpec control editing window is because in most cases, you are writing security guidance because you want to write security validation code! Recall that the whole point of Vulcan is to help us define the security posture target so that we can automate reaching it!",-1),I=e("div",{class:"hint-container note"},[e("p",{class:"hint-container-title"},"Do I need to use InSpec for my ATO process?"),e("p",null,"DOD does not and will not require teams to use any one particlar security validation tool."),e("p",null,"MITRE SAF favors InSpec because it favors our use cases nicely, but there are many different security tools on the market, some of which are better suited to particular tasks.")],-1),S=e("hr",{class:"footnotes-sep"},null,-1),x={class:"footnotes"},C={class:"footnotes-list"},V={id:"footnote1",class:"footnote-item"},q={href:"https://github.com/mitre/redhat-enterprise-linux-7-stig-baseline",target:"_blank",rel:"noopener noreferrer"},T={href:"https://saf.mitre.org/libs/validate",target:"_blank",rel:"noopener noreferrer"},E=e("a",{href:"#footnote-ref1",class:"footnote-backref"},"↩︎",-1);function N(A,B){const a=o("RouterLink"),s=o("ExternalLinkIcon");return r(),p("div",null,[k,e("div",f,[g,e("p",null,[n("Great news, we have an in-depth "),t(a,{to:"/courses/beginner/"},{default:i(()=>[n("training class")]),_:1}),n(" on how to do this ("),t(a,{to:"/courses/advanced/"},{default:i(()=>[n("two of them")]),_:1}),n(", actually).")]),w]),_,e("p",null,[n("Using Vulcan will ensure that all of your guidance is included in your test code as metadata (you can also do this by creating a profile stub with the "),e("a",b,[n("SAF CLI"),t(s)]),n(".)")]),y,v,I,S,e("section",x,[e("ol",C,[e("li",V,[e("p",null,[n("See the full profile code "),e("a",q,[n("here"),t(s)]),n(". Or see many more examples of InSpec profiles at "),e("a",T,[n("https://saf.mitre.org/libs/validate"),t(s)]),n(". "),E])])])])])}const L=l(m,[["render",N],["__file","09.html.vue"]]);export{L as default}; diff --git a/assets/09.html-7jlh-VKk.js b/assets/09.html-7jlh-VKk.js new file mode 100644 index 000000000..7ac497f77 --- /dev/null +++ b/assets/09.html-7jlh-VKk.js @@ -0,0 +1,7 @@ +import{_ as i}from"./Heimdall_Load-a_OCE2Lf.js";import{_ as o}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as s,o as l,c as n,d as e,e as t,b as r,f as d}from"./app-PAvzDPkc.js";const u="/saf-training/assets/SAF_Capabilities_Visualize-syiJ9qWZ.png",c="/saf-training/assets/Heimdall_NGINX_Vanilla_With_Inputs-fih6JUyh.png",h="/saf-training/assets/Heimdall_Filter_Failure-3zncmq1J.png",m="/saf-training/assets/Heimdall_TreeMap_Failures-bQaGeLB0.png",f="/saf-training/assets/Heimdall_V-41670_ResultsDetails-SaI3gEeI.png",p="/saf-training/assets/Heimdall_V-41670_ResultsDetails_Code-1jGKfuJ4.png",g="/saf-training/assets/Heimdall_NGINX_Inputs-dC9Mvg7o.png",_={},y=e("h2",{id:"_9-visualize-mitre-heimdall",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#_9-visualize-mitre-heimdall","aria-hidden":"true"},"#"),t(" 9. Visualize - MITRE Heimdall")],-1),v=e("p",null,"Now we want to SEE our results in a more meaningful way!",-1),b=e("figure",null,[e("img",{src:u,alt:"The Visualize Capability",tabindex:"0",loading:"lazy"}),e("figcaption",null,"The Visualize Capability")],-1),w={href:"https://heimdall-lite.mitre.org/",target:"_blank",rel:"noopener noreferrer"},x=d('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.
This will allow you to view the InSpec results in the Heimdall viewer.
Your visualization should look similar to the following:
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!
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.
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.
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.
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.
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:
+
+To protect the integrity of the data that is being captured in the
+ log files, ensure that only the members of the Auditors group, Administrators,
+ and the user assigned to run the web server software is granted permissions to
+ read the log files.
+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.
Let's create a GitHub Action workflow to define our pipeline.
Pipeline orchestration tools are usually configured in a predefined workflow file, which defines a set of tasks and the order they should run in. Workflow files live in the .github folder for GitHub Actions (the equivalent is the gitlab-ci file for GitLab CI, for example).
Let's create a new file to store our workflow.
mkdir .github
+mkdir .github/workflows
+touch .github/workflows/pipeline.yml
+Neither command has output, but you should see a new file if you examine your .github directory:
Open that file up for editing.
For reference, this is the complete workflow file we will end up with at the end of the class:
name: Demo Security Validation Gold Image Pipeline
+
+on:
+ push:
+ branches: [ main, pipeline ] # trigger this action on any push to main branch
+
+jobs:
+ gold-image:
+ name: Gold Image NGINX
+ runs-on: ubuntu-20.04
+ env:
+ CHEF_LICENSE: accept # so that we can use InSpec without manually accepting the license
+ PROFILE: my_nginx # path to our profile
+ steps:
+ - name: PREP - Update runner # updating all dependencies is always a good start
+ run: sudo apt-get update
+ - name: PREP - Install InSpec executable
+ run: curl https://omnitruck.chef.io/install.sh | sudo bash -s -- -P inspec -v 5
+
+ - name: PREP - Check out this repository # because that's where our profile is!
+ uses: actions/checkout@v3
+
+ - name: LINT - Run InSpec Check # double-check that we don't have any serious issues in our profile code
+ run: inspec check $PROFILE
+
+ - name: DEPLOY - Run a Docker container from nginx
+ run: docker run -dit --name nginx nginx:latest
+
+ - name: DEPLOY - Install Python for our nginx container
+ run: |
+ docker exec nginx apt-get update -y
+ docker exec nginx apt-get install -y python3
+
+ - name: HARDEN - Fetch Ansible role
+ run: |
+ git clone --branch docker https://github.com/mitre/ansible-nginx-stigready-hardening.git || true
+ chmod 755 ansible-nginx-stigready-hardening
+
+ - name: HARDEN - Fetch Ansible requirements
+ run: ansible-galaxy install -r ansible-nginx-stigready-hardening/requirements.yml
+
+ - name: HARDEN - Run Ansible hardening
+ run: ansible-playbook --inventory=nginx, --connection=docker ansible-nginx-stigready-hardening/hardening-playbook.yml
+
+ - name: VALIDATE - Run InSpec
+ continue-on-error: true # we dont want to stop if our InSpec run finds failures, we want to continue and record the result
+ run: |
+ inspec exec $PROFILE \\
+ --input-file=$PROFILE/inputs.yml \\
+ --target docker://nginx \\
+ --reporter cli json:results/pipeline_run.json
+
+ - name: VALIDATE - Save Test Result JSON # save our results to the pipeline artifacts, even if the InSpec run found failing tests
+ uses: actions/upload-artifact@v3
+ with:
+ path: results/pipeline_run.json
+
+ - name: VERIFY - Display our results summary
+ uses: mitre/saf_action@v1
+ with:
+ command_string: "view summary -i results/pipeline_run.json"
+
+ - name: VERIFY - Ensure the scan meets our results threshold
+ uses: mitre/saf_action@v1 # check if the pipeline passes our defined threshold
+ with:
+ command_string: "validate threshold -i results/pipeline_run.json -F threshold.yml"
+This is a bit much all in one bite, so let's construct this full pipeline piece by piece.
Pipeline orchestrators need you to define some set of events that should trigger the pipeline to run. The first thing we want to define in a new pipeline is what triggers it.
In our case, we want this pipeline to be a continuous integration pipeline, which should trigger every time we push code to the repository. Other options include "trigger this pipeline when a pull request is opened on a branch," or "trigger this pipeline when someone opens an issue on our repository," or even "trigger this pipeline when I hit the manual trigger button."
Saving Files vs. Pushing Code
In all class content so far, we have been taking advantage of Codespaces' autosave feature. We have been saving our many edits to our profiles locally.
Pushing code, by contrast, means taking your saved code and officially adding it to your base repository's committed codebase, making it a permanent change. Codespaces won't do that automatically.
Let's give our pipeline a name and add a workflow trigger. Add the following into the pipeline.yml file:
name: Demo Security Validation Gold Image Pipeline
+
+on:
+ push:
+ branches: [main] # trigger this action on any push to main branch
+YAML Syntax
We will be heavily editing pipeline.yml throughout this part of the class. Recall that YAML files like this are whitespace-delimited. If you hit confusing errors when we run these pipelines, always be sure to double-check your code lines up with the examples.
Why Is `[main]` in brackets?
The branches attribute in a workflow file can accept an array of branches we want to trigger the pipeline if they see a commit. We are only concerned with main at present, so we wind up with '[main]'.
Next, we need to define some kind of task to complete when the event triggers.
First, we'll define a job, the logical group for our tasks. In our pipeline.yml file, add:
gold-image is an arbitrary name we gave this job. It would be more useful if we were running more than one.name is a simple title for this job.runs-on declares what operating system we want our runner node to be. We picked Ubuntu (and we suggest you do to to make sure the rest of the workflow commands work correctly).env declares environment variables for use by any step of this job. We will go ahead and set a few variables for running InSpec later on: CHEF_LICENSE will automatically accept the license prompt when you run InSpec the first time so that we don' hang waiting for input!PROFILE is set to the path of the InSpec profile we will use to test. This will make it easier to refer to the profile multiple times and still make it easy to swap out.Now that we have our job metadata in place, let's add an actual task for the runner to complete, which GitHub Actions refer to as steps -- a quick update on our runner node's dependencies (this shouldn't be strictly necessary, but it's always good to practice good dependency hygiene!). In our pipeline.yml file, add:
Once we push our code, you can go to another tab in our browser, load up your personal code repository for the class content that you forked earlier, and check out the Actions tab to see your pipeline executing.
Note the little green checkmark next to your pipeline run. This indicates that the pipeline has finished running. You may also see a yellow circle to indicate that the pipeline has not completed yet, or a red X mark to indicate an errr, depending on the status of your pipeline when you examine it.
If we click on the card for our pipeline run, we get more detail:
You can see some info on the triggered run, including a card showing the job that we defined earlier. Clicking it gives us a view of the step we've worked into our pipeline -- we can even see the stdout (terminal output) of running that step on the runner.
Congratulations, you've run a pipeline! Now we just need to make it do something useful for us.
It's up to you.
Some orchestration tools let you run pipelines locally, and in a real repo, you'd probably want to do this on a branch other than the main one to keep it clean. But in practice it has been the authors' experience that everyone winds up simply creating dozens of commits to the repo to trigger the pipeline and watch for the next spot where it breaks. There's nothing wrong with doing this.
For example, consider how many failed pipelines the author had while designing the test pipeline for this class, and how many of them involve fixing simple typos. . .
pipeline.yml after adding a job"}],"tab-id":"shell"},{title0:s(({value:a,isActive:t})=>[e("Adding a Job")]),title1:s(({value:a,isActive:t})=>[E,e(" after adding a job")]),tab0:s(({value:a,isActive:t})=>[A]),tab1:s(({value:a,isActive:t})=>[P]),_:1},8,["data"]),C,i(l,{id:"131",data:[{id:"Adding a Step"},{id:"pipeline.yml after adding a step"}],"tab-id":"shell"},{title0:s(({value:a,isActive:t})=>[e("Adding a Step")]),title1:s(({value:a,isActive:t})=>[S,e(" after adding a step")]),tab0:s(({value:a,isActive:t})=>[N]),tab1:s(({value:a,isActive:t})=>[L]),_:1},8,["data"]),R,T,i(l,{id:"144",data:[{id:"Committing And Pushing Code"},{id:"Output of Pushing Code"}],"tab-id":"shell"},{title0:s(({value:a,isActive:t})=>[e("Committing And Pushing Code")]),title1:s(({value:a,isActive:t})=>[e("Output of Pushing Code")]),tab0:s(({value:a,isActive:t})=>[j]),tab1:s(({value:a,isActive:t})=>[F]),_:1}),O])}const V=u(v,[["render",G],["__file","09.html.vue"]]);export{V as default};
diff --git a/assets/09.html-TNAq4b_z.js b/assets/09.html-TNAq4b_z.js
new file mode 100644
index 000000000..2bbc128e9
--- /dev/null
+++ b/assets/09.html-TNAq4b_z.js
@@ -0,0 +1 @@
+const e=JSON.parse('{"key":"v-14735b9c","path":"/courses/user/09.html","title":"9. Visualize Results - Heimdall","lang":"en-US","frontmatter":{"order":9,"next":"10.md","title":"9. Visualize Results - Heimdall","author":"Aaron Lippold","headerDepth":3,"description":"9. Visualize - MITRE Heimdall Now we want to SEE our results in a more meaningful way! The Visualize Capability Navigate to the our online version of the Heimdall application, t...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/user/09.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"9. Visualize Results - Heimdall"}],["meta",{"property":"og:description","content":"9. Visualize - MITRE Heimdall Now we want to SEE our results in a more meaningful way! The Visualize Capability Navigate to the our online version of the Heimdall application, t..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"9. Visualize Results - Heimdall\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"9. Visualize - MITRE Heimdall","slug":"_9-visualize-mitre-heimdall","link":"#_9-visualize-mitre-heimdall","children":[{"level":3,"title":"9.1 Upload Results","slug":"_9-1-upload-results","link":"#_9-1-upload-results","children":[]},{"level":3,"title":"9.2 Visualize Results","slug":"_9-2-visualize-results","link":"#_9-2-visualize-results","children":[]},{"level":3,"title":"9.3 Explore Heimdall","slug":"_9-3-explore-heimdall","link":"#_9-3-explore-heimdall","children":[]}]}],"git":{},"readingTime":{"minutes":2.25,"words":674},"filePathRelative":"courses/user/09.md","autoDesc":true}');export{e as data};
diff --git a/assets/09.html-TYobHnIk.js b/assets/09.html-TYobHnIk.js
new file mode 100644
index 000000000..4a4666b2c
--- /dev/null
+++ b/assets/09.html-TYobHnIk.js
@@ -0,0 +1 @@
+const e=JSON.parse(`{"key":"v-3ac158f3","path":"/courses/advanced/09.html","title":"9. GitHub Actions","lang":"en-US","frontmatter":{"order":9,"next":"10.md","title":"9. GitHub Actions","author":"Will Dower","headerDepth":3,"description":"GitHub Actions Let's create a GitHub Action workflow to define our pipeline. The Workflow file Pipeline orchestration tools are usually configured in a predefined workflow file,...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/advanced/09.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"9. GitHub Actions"}],["meta",{"property":"og:description","content":"GitHub Actions Let's create a GitHub Action workflow to define our pipeline. The Workflow file Pipeline orchestration tools are usually configured in a predefined workflow file,..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Will Dower"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"9. GitHub Actions\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Will Dower\\"}]}"]]},"headers":[{"level":2,"title":"GitHub Actions","slug":"github-actions","link":"#github-actions","children":[{"level":3,"title":"The Workflow file","slug":"the-workflow-file","link":"#the-workflow-file","children":[]},{"level":3,"title":"Workflow File - Complete Example","slug":"workflow-file-complete-example","link":"#workflow-file-complete-example","children":[]},{"level":3,"title":"Workflow Triggers","slug":"workflow-triggers","link":"#workflow-triggers","children":[]},{"level":3,"title":"Our First Step","slug":"our-first-step","link":"#our-first-step","children":[]},{"level":3,"title":"The Next Step","slug":"the-next-step","link":"#the-next-step","children":[]}]}],"git":{},"readingTime":{"minutes":5.98,"words":1793},"filePathRelative":"courses/advanced/09.md","autoDesc":true}`);export{e as data};
diff --git a/assets/09.html-Ti7khI6G.js b/assets/09.html-Ti7khI6G.js
new file mode 100644
index 000000000..856211d02
--- /dev/null
+++ b/assets/09.html-Ti7khI6G.js
@@ -0,0 +1 @@
+const t=JSON.parse(`{"key":"v-7c844629","path":"/courses/guidance/09.html","title":"9. Automated InSpec Testing","lang":"en-US","frontmatter":{"order":9,"next":"10.md","title":"9. Automated InSpec Testing","author":"Sumaa Sayed","headerDepth":3,"description":"9.1 Automated Validation Tests Now that we have written up some Check and Fix text, it's time to use one of Vulcan's other features -- the InSpec code pane. We've already used V...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/guidance/09.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"9. Automated InSpec Testing"}],["meta",{"property":"og:description","content":"9.1 Automated Validation Tests Now that we have written up some Check and Fix text, it's time to use one of Vulcan's other features -- the InSpec code pane. We've already used V..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:image","content":"https://mitre.github.io/saf-training/saf-training/"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"name":"twitter:card","content":"summary_large_image"}],["meta",{"name":"twitter:image:alt","content":"9. Automated InSpec Testing"}],["meta",{"property":"article:author","content":"Sumaa Sayed"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"9. Automated InSpec Testing\\",\\"image\\":[\\"https://mitre.github.io/saf-training/saf-training/\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Sumaa Sayed\\"}]}"]]},"headers":[{"level":2,"title":"9.1 Automated Validation Tests","slug":"_9-1-automated-validation-tests","link":"#_9-1-automated-validation-tests","children":[{"level":3,"title":"9.1.1 The InSpec Control Body","slug":"_9-1-1-the-inspec-control-body","link":"#_9-1-1-the-inspec-control-body","children":[]},{"level":3,"title":"9.1.2 Why am I writing test code inside Vulcan?","slug":"_9-1-2-why-am-i-writing-test-code-inside-vulcan","link":"#_9-1-2-why-am-i-writing-test-code-inside-vulcan","children":[]}]}],"git":{},"readingTime":{"minutes":2.21,"words":663},"filePathRelative":"courses/guidance/09.md","autoDesc":true}`);export{t as data};
diff --git a/assets/09.html-pI5nuU8N.js b/assets/09.html-pI5nuU8N.js
new file mode 100644
index 000000000..46e9c90b4
--- /dev/null
+++ b/assets/09.html-pI5nuU8N.js
@@ -0,0 +1 @@
+const e=JSON.parse(`{"key":"v-2fd9c523","path":"/courses/beginner/09.html","title":"9. Viewing and Analyzing Results","lang":"en-US","frontmatter":{"order":9,"next":"10.md","title":"9. Viewing and Analyzing Results","author":"Aaron Lippold","headerDepth":3,"description":"Viewing and Analyzing Results We discussed using reporters in the last section to capture InSpec's output in convenient JSON files. JSON reports like these are a transport mediu...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/beginner/09.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"9. Viewing and Analyzing Results"}],["meta",{"property":"og:description","content":"Viewing and Analyzing Results We discussed using reporters in the last section to capture InSpec's output in convenient JSON files. JSON reports like these are a transport mediu..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"9. Viewing and Analyzing Results\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"Viewing and Analyzing Results","slug":"viewing-and-analyzing-results","link":"#viewing-and-analyzing-results","children":[{"level":3,"title":"Heimdall","slug":"heimdall","link":"#heimdall","children":[]},{"level":3,"title":"Heimdall Lite","slug":"heimdall-lite","link":"#heimdall-lite","children":[]}]}],"git":{},"readingTime":{"minutes":1.3,"words":390},"filePathRelative":"courses/beginner/09.md","autoDesc":true}`);export{e as data};
diff --git a/assets/09.html-qiGyptHL.js b/assets/09.html-qiGyptHL.js
new file mode 100644
index 000000000..90eef9dba
--- /dev/null
+++ b/assets/09.html-qiGyptHL.js
@@ -0,0 +1 @@
+const e=JSON.parse(`{"key":"v-fad43882","path":"/courses/profile-dev-test/09.html","title":"Types of Profile Updates","lang":"en-US","frontmatter":{"order":9,"next":"10.md","title":"Types of Profile Updates","author":"Aaron Lippold","description":"When updating the profile, you'll be making one of three types of changes: 1. Patch Update: These frequent updates cover missing corner cases of testing for one or more benchmar...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/profile-dev-test/09.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Types of Profile Updates"}],["meta",{"property":"og:description","content":"When updating the profile, you'll be making one of three types of changes: 1. Patch Update: These frequent updates cover missing corner cases of testing for one or more benchmar..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Types of Profile Updates\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":3,"title":"Scope of the Update Patterns","slug":"scope-of-the-update-patterns","link":"#scope-of-the-update-patterns","children":[]}],"git":{},"readingTime":{"minutes":0.98,"words":293},"filePathRelative":"courses/profile-dev-test/09.md","autoDesc":true}`);export{e as data};
diff --git a/assets/10.html-2qHElRRB.js b/assets/10.html-2qHElRRB.js
new file mode 100644
index 000000000..965e215d8
--- /dev/null
+++ b/assets/10.html-2qHElRRB.js
@@ -0,0 +1,95 @@
+import{_ as d}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as c,o as p,c as u,b as o,w as s,d as n,e,f as i}from"./app-PAvzDPkc.js";const m={},v=i(`In addition to its own controls, an InSpec profile can leverage controls from one or more other InSpec profiles.
When a profile depends on controls from other profiles, it can be referred to as an "overlay" or "wrapper" profile. We'll use the term overlay profile in this section.
An overlay can include all, select specific, skip some, or modify controls it uses from the profiles it is depending on.
overlay=>operation: my_nginx_overlay
+e=>end: my_nginx
+
+e->overlay
+To recap, here are the controls that are in the my_nginx profile:
control 'nginx-version' do
+ impact 1.0
+ title 'NGINX version'
+ desc 'The required version of NGINX should be installed.'
+ describe nginx do
+ its('version') { should cmp >= input('nginx_version') }
+ end
+end
+
+control 'nginx-modules' do
+ impact 1.0
+ title 'NGINX modules'
+ desc 'The required NGINX modules should be installed.'
+ required_modules = input('nginx_modules')
+ describe nginx do
+ required_modules.each do |required_module|
+ its('modules') { should include required_module }
+ end
+ end
+end
+
+control 'nginx-conf-file' do
+ impact 1.0
+ title 'NGINX configuration file'
+ desc 'The NGINX config file should exist.'
+ describe file('/etc/nginx/nginx.conf') do
+ it { should be_file }
+ end
+end
+
+control 'nginx-conf-perms' do
+ impact 1.0
+ title 'NGINX configuration permissions'
+ desc 'The NGINX config file should owned by root, be writable only by owner, and not writeable or and readable by others.'
+ describe file('/etc/nginx/nginx.conf') do
+ it { should be_owned_by 'root' }
+ it { should be_grouped_into 'root' }
+ it { should_not be_readable.by('others') }
+ it { should_not be_writable.by('others') }
+ it { should_not be_executable.by('others') }
+ end
+end
+
+control 'nginx-shell-access' do
+ impact 1.0
+ title 'NGINX shell access'
+ desc 'The NGINX shell access should be restricted to admin users.'
+ describe users.shells(/bash/).usernames do
+ it { should be_in input('admin_users')}
+ end
+end
+inspec init profile my_nginx_overlay
+The terminal output should look like the following:
Create new profile at /<pwd>/my_nginx_overlay
+ * Create directory controls
+ * Create file controls/example.rb
+ * Create file inspec.yml
+ * Create file README.md
+In this example, we will rename the example.rb to overlay.rb to avoid confusion.
tree my_nginx_overlay
+Which should look like:
my_nginx_overlay
+ ├── README.md
+ ├── controls
+ │ └── overlay.rb
+ └── inspec.yml
+
+ 1 directory, 3 files
+For a profile to use controls from another profile, the dependency needs to be included in the depends section of the overlay's inspec.yml file. For example, you can develop my_nginx_overlay that uses controls from the my_nginx profile. In this case, the depends section of inspec.yml of my_nginx_overlay should list the name and location of my_nginx. One way of declaring the dependency is:
After defining the dependency in the inspec.yml of my_nginx_overlay, controls from my_nginx are available to be used in the overlay. By using include_controls <profile> in the overlay.rb of the overlay profile, all controls from the named profile will be executed every time the overlay is executed. Below you can see an example of an overlay.rb file in the controls folder of the overlay.
In the example above, every time my_nginx_overlay profile is executed, all the controls from my_nginx profile are also executed. Therefore, the following controls would be executed for my_nginx_overlay:
| Controls | Executed |
|---|---|
| nginx-version | ✓ |
| nginx-modules | ✓ |
| nginx-conf-file | ✓ |
| nginx-conf-perms | ✓ |
| nginx-shell-access | ✓ |
What if you don't want to run one of the controls from the included profile? Luckily, it is not necessary to maintain a slightly-modified copy of the included profile just to delete a control. The skip_control command tells InSpec not to run a particular control.
In the above example, all controls from my_nginx profile will be executed, except for control nginx-conf-perms, every time my_nginx_overlay is executed. Therefore, the following controls will be executed for my_nginx_overlay:
| Controls | Executed |
|---|---|
| nginx-version | ✓ |
| nginx-modules | ✓ |
| nginx-conf-file | ✓ |
| nginx-conf-perms | ✗ |
| nginx-shell-access | ✓ |
If there are only a handful of controls that should be executed from an included profile, it’s not necessary to skip all the unneeded controls, or worse, copy/paste those controls bit-for-bit into your profile[1]. Instead, use the require_controls command.
Whenever my_nginx_overlay is executed, it will run only the controls from my_nginx that are specified in the require_controls block. In the case, the following controls would be executed:
| Controls | Executed |
|---|---|
| nginx-version | ✓ |
| nginx-modules | ✓ |
| nginx-conf-file | ✗ |
| nginx-conf-perms | ✗ |
| nginx-shell-access | ✗ |
Controls nginx-conf-file, nginx-conf-perms, and nginx-shell-access would not be executed, just as if they were manually skipped. This method of including specific controls ensures only the controls specified are executed.
Warning
If new controls are added to a later version of my_nginx, they would not be executed unless explicitly required in this scenario.
Let’s say a particular control from an included profile should still run, but the impact level set in the control isn’t appropriate. When a control is included or required, it can also be modified!
',6),C=n("div",{class:"language-ruby line-numbers-mode","data-ext":"rb"},[n("pre",{class:"language-ruby"},[n("code",null,[e("include_controls "),n("span",{class:"token string-literal"},[n("span",{class:"token string"},"'my_nginx'")]),e(),n("span",{class:"token keyword"},"do"),e(` + control `),n("span",{class:"token string-literal"},[n("span",{class:"token string"},"'nginx-modules'")]),e(),n("span",{class:"token keyword"},"do"),e(` + impact `),n("span",{class:"token number"},"0.5"),e(` + `),n("span",{class:"token keyword"},"end"),e(` +`),n("span",{class:"token keyword"},"end"),e(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),S=n("div",{class:"language-ruby line-numbers-mode","data-ext":"rb"},[n("pre",{class:"language-ruby"},[n("code",null,[e("require_controls "),n("span",{class:"token string-literal"},[n("span",{class:"token string"},"'my_nginx'")]),e(),n("span",{class:"token keyword"},"do"),e(` + control `),n("span",{class:"token string-literal"},[n("span",{class:"token string"},"'nginx-modules'")]),e(),n("span",{class:"token keyword"},"do"),e(` + impact `),n("span",{class:"token number"},"0.5"),e(` + `),n("span",{class:"token keyword"},"end"),e(` + control `),n("span",{class:"token string-literal"},[n("span",{class:"token string"},"'nginx-conf-file'")]),e(` +`),n("span",{class:"token keyword"},"end"),e(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),T=i('In the above example, all included or required controls from my_nginx profile are executed. However, should control nginx-modules fail, it will be raised with an impact of 0.5 instead of the originally-intended impact of 1.0.
Note
Any fields that you do not explicitly modify in an included control will not be changed from the baseline.
Therefore, you can import a control and only override a single field like the impact while leaving the actual control code and the rest of the metadata tags untouched.
Let's poke around a few more examples of inheritance.
',4),E={href:"https://github.com/mitre/helloworld-web-baseline",target:"_blank",rel:"noopener noreferrer"},W={href:"https://github.com/mitre/sample-rhel8-overlay",target:"_blank",rel:"noopener noreferrer"},D={href:"https://github.com/mitre/sample-mysql-overlay",target:"_blank",rel:"noopener noreferrer"},G={href:"https://github.com/mitre/aws-rds-oracle-database-19c-cis-baseline",target:"_blank",rel:"noopener noreferrer"},X={class:"hint-container note"},M=n("p",{class:"hint-container-title"},"Cloud environment overlays",-1),O={href:"https://saf.mitre.org/libs/validation",target:"_blank",rel:"noopener noreferrer"},z=n("code",null,"ec2-user",-1),L=i('Copying and pasting controls from a profile, instead of creating an overlay, can lead to important updates not being reflected. Overlays keep the profile changes in sync as they pull the latest updates. ↩︎
We now have inspec exec and the my_nginx profile available in our pipeline. Now we need the image we're going to harden.
Luckily, the Ubuntu runner we are using already has the Docker Engine installed, so we can deploy a container easily. We will deploy the same container image we have been using in this class so far. We will also name it nginx to keep things consistent, but recall that this container is running on a GitHub cloud runner, not inside your codespace like your local containers we've been using for prior classwork.
We'll also need to make sure that our test target has Python installed, since that's how Ansible will connect to it later to harden it.
(You didn't have to do that for your local NGINX container because the build-lab.sh script did all that config for you.)
You may notice that the step that runs InSpec sets an attribute called continue-on-error to true. We'll discuss why we do that in the next section.
Where are we in the directory structure right now?!
Remember that we used the checkout action earlier, so the pipeline is currently running inside the root of our repo as it exists on the runner system. That's why we can refer to files in this repo by local paths (like the profile repo itself, and the results subdirectory).
We used the --reporter json flag when we invoked InSpec, so we should now have a report file sitting on the runner. We want to be able to access that file -- both so that we can read it ourselves, and so that we can do some later processing on it in later jobs if we want to.
That's why we used upload-artifact, another extremely common Action. This one makes whatever file or files you pass it available for download through the browser when we examine the pipeline run later, and also makes those files available to later jobs even if they take place on different runners in this workflow (by default, any files created by a runner do not persist when the workflow ends).
Let's do some brainstorming -- are there any other steps you'd like to insert into the pipeline? What else do you want to know about the profile or do with it?
pipeline.yml after adding more steps"}],"tab-id":"shell"},{title0:e(({value:a,isActive:t})=>[s("Adding More Steps")]),title1:e(({value:a,isActive:t})=>[g,s(" after adding more steps")]),tab0:e(({value:a,isActive:t})=>[f]),tab1:e(({value:a,isActive:t})=>[_]),_:1},8,["data"]),n("p",null,[s("The first new step installs the InSpec executable using the install instructions for Ubuntu as given "),n("a",w,[s("here"),l(o)]),s(". Remember that GitHub gives us a brand-new runner node every time we execute the pipeline; if we don't install it and it isn't on the pre-installed software list, it won't be available!")]),x,n("p",null,[s('The next step ("PREP - Check out this repository") is our first one to use an Action. Actions are pre-packaged pipeline steps published to the '),n("a",I,[s("GitHub Marketplace"),l(o)]),s(". Any project or developer can publish an Action to the Marketplace as part of the GitHub Actions ecosystem. Most other orchestration tools for pipelines have a similar plugin system.")]),P,n("p",null,[s("This Action in particular is one of the most common -- "),n("a",A,[E,l(o)]),s(". If called with no other attributes attached to it, it simply checks out and changes directory into the repository where the workflow file lives to the runner that is currently executing the workflow. We need to do this to make sure we have access to InSpec profile you created earlier!")]),R,S,L,N,l(c,{id:"47",data:[{id:"Adding Lint Step"},{id:"pipeline.yml after adding lint step"}],"tab-id":"shell"},{title0:e(({value:a,isActive:t})=>[s("Adding Lint Step")]),title1:e(({value:a,isActive:t})=>[D,s(" after adding lint step")]),tab0:e(({value:a,isActive:t})=>[C]),tab1:e(({value:a,isActive:t})=>[F]),_:1},8,["data"]),O,l(c,{id:"70",data:[{id:"Adding Deploy Steps"},{id:"pipeline.yml after adding deploy steps"}],"tab-id":"shell"},{title0:e(({value:a,isActive:t})=>[s("Adding Deploy Steps")]),title1:e(({value:a,isActive:t})=>[H,s(" after adding deploy steps")]),tab0:e(({value:a,isActive:t})=>[G]),tab1:e(({value:a,isActive:t})=>[T]),_:1},8,["data"]),j,V,W,n("p",null,[s("In our case, we're going to borrow an open-source Ansible role for NGINX that is part of the "),n("a",Y,[s("SAF Hardening Library"),l(o)]),s(". If you took the "),l(u,{to:"/courses/user/"},{default:e(()=>[s("SAF User Class")]),_:1}),s(", you might recognize this role as what you ran manually during the "),l(u,{to:"/courses/user/10.html"},{default:e(()=>[s("Hardening")]),_:1}),s(" section of that class. Again, we are borrowing some of the steps from the lab setup script and executing them against our runner system, for convenience.")]),U,l(c,{id:"95",data:[{id:"Adding Harden Steps"},{id:"pipeline.yml after adding hardening steps"}],"tab-id":"shell"},{title0:e(({value:a,isActive:t})=>[s("Adding Harden Steps")]),title1:e(({value:a,isActive:t})=>[$,s(" after adding hardening steps")]),tab0:e(({value:a,isActive:t})=>[q]),tab1:e(({value:a,isActive:t})=>[M]),_:1},8,["data"]),X,B,z,l(c,{id:"112",data:[{id:"Adding Validate Steps"},{id:"pipeline.yml after adding validate steps"}],"tab-id":"shell"},{title0:e(({value:a,isActive:t})=>[s("Adding Validate Steps")]),title1:e(({value:a,isActive:t})=>[J,s(" after adding validate steps")]),tab0:e(({value:a,isActive:t})=>[K]),tab1:e(({value:a,isActive:t})=>[Q]),_:1},8,["data"]),Z])}const ln=r(m,[["render",nn],["__file","10.html.vue"]]);export{ln as default};
diff --git a/assets/10.html-UQrjWLRc.js b/assets/10.html-UQrjWLRc.js
new file mode 100644
index 000000000..b5fbe0f4f
--- /dev/null
+++ b/assets/10.html-UQrjWLRc.js
@@ -0,0 +1 @@
+import{_ as t}from"./plugin-vue_export-helper-x3n3nnut.js";import{o as i,c as r,f as o}from"./app-PAvzDPkc.js";const a="/saf-training/assets/review_status-9yKCc7j9.png",n="/saf-training/assets/filling_out_request_for_review-JJUnYRBj.png",s="/saf-training/assets/r_and_c-hpGDg1Bl.png",e="/saf-training/assets/review_status_filter-0cOnnA6s.png",u={},l=o('With that, we've done two full requirements -- one "Applicable - Configurable" and one "Applicable - Inherently Meets." There are only 189 or so more requirements to go!
In a real project of this size, you will be part of a team of authors each taking a subset of these requirements to complete. However, in a project of any size, you will also be peer reviewing the content your colleagues write to ensure quality standards are met.
Let's flag our completed RHEL-09-000003 requirement as Ready for Review.
Note that we, as the primary author, are not able to approve our own requirement; the option is grayed out. All we can do is mark the requirement for review (or, as an admin, we can simply lock the control against further edits).
Note that the "Reviews & Comments" section on the right hand side of the Component view has updated.
Note also that the control is locked from further editing now. We can reverse this using the Review Status menu if we want.
If you want to conduct a peer review on another author's requirements, you can do so by filtering the requirements using the filter bar on the left side of the Component view.
If you enter a control that has been marked for review, and you are at least the role of Reviewer on the project, you will be able to:
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.
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.
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:
source ./install-nginxHardeningTools.sh
+This command will make sure that the NGINX docker container has the required software dependencies such as Python to run the Ansible hardening content. This script also downloads the hardening content locally. Unlike the InSpec scan, we will run the hardening content from a local folder rather than from GitHub. Therefore, you should see the ansible-nginx-stigready-hardening folder in your files when the script completes.
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
Make sure you are in the ansible content's directory before running the following command. You can run the commandcd 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:
ansible-playbook -i hosts.yml hardening-playbook.yml
+To see the following results:
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
+it as an ansible.cfg source. For more information see https://docs.ansible.com/ansible/devel/reference_appendices/config.html#cfg-in-world-writable-
+dir
+
+PLAY [all] ******************************************************************************************************************************************
+
+TASK [Gathering Facts] ******************************************************************************************************************************
+ok: [docker]
+
+TASK [../ansible-nginx-stigready-hardening : Ensure the "/usr/sbin/nginx" binary is not worldwide read- or writeable] *******************************
+changed: [docker]
+
+...
+
+TASK [../ansible-nginx-stigready-hardening : Generate a '/C=US/O=U.S. Government/OU=DoD/CN=DoD' self-signed ssl certificate and key] ****************
+changed: [docker]
+
+TASK [../ansible-nginx-stigready-hardening : Ensure the private key is only readable by 'root'] *****************************************************
+changed: [docker]
+
+TASK [../ansible-nginx-stigready-hardening : Ensure the crt should only be readable by 'root'] ******************************************************
+changed: [docker]
+
+TASK [../ansible-nginx-stigready-hardening : Post Task] *********************************************************************************************
+changed: [docker]
+
+PLAY RECAP ******************************************************************************************************************************************
+docker : ok=38 changed=35 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
+You and your team might be wondering what 'done' means for a security control in your profile. Here are a few things to consider:
The 'is it done' litmus test is not solely determined by a perfect InSpec control or describe and expect blocks. It also heavily relies on you, the security automation engineer. Your experience, understanding of the platform you're working on, and the processes that you and your team have collectively agreed upon are all vital components.
Trust your established expected test outcomes, the guidance document, and the CI/CD testing framework. They will help you know that, to the best of your ability, you have captured the spirit of the testing required by the Benchmark.
We consider a control effectively tested when:
only_if block vs 'if/else' logic when possible to ensure that the control is as clear, direct, and maintainable as possible from a coding perspective.'Passing as expected' is the most straightforward concept as it directly corresponds to the test conditions. When the test asserts a condition, it validates that assertion and reports it to the end user in a clear and concise manner.
We strive to ensure that when we report a 'pass', we do so in a language that is direct, simple, and easy to understand.
For example:
✔ SV-230222: RHEL 8 vendor packaged system security patches and updates must be installed and up to date.
+ ✔ All system security patches and updates are up to date and have been applied
+Passes as Expected also encompasses:
Fails as Expected'Failing as expected' is a less straightforward concept as it doesn't always directly correspond to the test conditions. When the test asserts a condition and it fails, the reason for that failure should be communicated to the end user in a clear and concise manner.
However, as we all know, a test may fail for more than one reason. Sometimes, the reason for failure might be connected to human error, conditions on the system such as extra lines, files, or housekeeping on the system that was not done, etc. All these factors may need to be accounted for in your tests and perhaps captured in your output and 'reasons' for failure.
This is where the above 'best practices' come into play. You don't just test in optional 'pass' and 'fail' conditions only, but also 'dirty things up' a bit and make sure that your 'failure' cases are robust enough to handle the real world and semi-perfect conditions.
For example:
✔ SV-230222: RHEL 8 vendor packaged system security patches and updates must be installed and up to date.
+ x The following packages have security patches and need to be updated:
+ - package 1
+ - package 2
+ - package 3
+ - package 4
+Fails as Expected also encompasses:
Communicates EffectivelyClear communication from your testing suite may require you to use a combination of approaches, but the extra time and effort is well worth it.
Here are some methods you can employ and things to consider:
expect vs describe statements in cases where you have multi-part or multi-phase test cases.describe statements into multiple layers so that the final output to the end user is clear and concise.At this point, we have tailored two requirements from the original SRG into STIG-ready content, and discussed how to peer review them.
Let's discuss what we can do with our components after we finish the requirement writing and reviewing.
We have a few ways of exporting the content from Vulcan once it is written.
Notice on the right-hand side that the overall project summary now reflects that we made edits.
From left to right, those buttons will:
A component can only be released if every requirement is locked. Requirements are only locked from further editing when they have undergone peer review. Therefore, releasing a component should only happen when all authorship is complete.
Importing a Released Component
Once a Component is released, it can be imported into a different Vulcan project as a building block.
One of our purposes with Vulcan is to avoid duplicating effort wherever possible; if the guidannce is already written, we want to be able to access it!
Unlike formal release, the Component does not need to be locked to be exported (in any format). You are not required to keep your editing workflow inside Vulcan (though we do, of course, recommend keeping your workflow inside Vulcan where you can).
Note
This means, for example, that we can export our InSpec profile regularly to test our code against test systems throughout the authorship process.
We have spent quite a bit of time discussing how to use Vulcan to make initial authorship easier. However, Vulcan also has features intended to make the maintenace of your guidance documentation easier.
This is why we have a Duplicate Component button available on the Component card, for example.
We will not be releasing the Component in this class because that would require us to at least have made a Status Determination for each requirement. We can, however, create a Duplicate of the component. Let's do that now.
Why are we duplicating the Component?
In a complex system with many software components, it may make sense to create multiple Components in one project, all of which have a shared source SRG.
For this example, we are duplicating the Component to mimic the release process.
This time, we want to mark this Component as Version 1, Release 2.
Let's open up the component and edit another one of the controls. Any will do.
Save the edit, just like you would in the first release.
Go back to the Project page for RHEL9 and click the Diff Viewer tab. You'll get a menu asking you which two Components you want to compare.
Note
Duplicating a Component automatically generates empty InSpec stubs inside the new component, which is why the Diff viewer believes that every requirement has a change.
How do I use this?
The Diff Viewer enables you to do several things.
For one, you can compare releases to tell at a glance what has changed in a piece of guidance, which traditionally would require tracking everything in a changelog manually.
For another, we can easily compare the Components we make with published STIGs.
At this point, we have gone over most of the processes you would use in Vulcan to develop your own security guidance content. To close us off, let's review the process for foally publishing a STIG.
',37),d=[h];function u(f,m){return t(),o("div",null,d)}const y=e(c,[["render",u],["__file","11.html.vue"]]);export{y as default}; diff --git a/assets/11.html-BW22Z0ue.js b/assets/11.html-BW22Z0ue.js new file mode 100644 index 000000000..7d08b332a --- /dev/null +++ b/assets/11.html-BW22Z0ue.js @@ -0,0 +1,172 @@ +import{_ as d}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as u,o as m,c as k,d as n,e as s,b as i,w as e,f as l}from"./app-PAvzDPkc.js";const r="/saf-training/assets/the_completed_pipeline_run-Wpx-ZqJy.png",h="/saf-training/assets/summary_data-nKGFtr64.png",b={},v=l('At this point we have a much more mature workflow file. We have one more activity we need to do -- verification, or checking that the output of our validation run met our expectations.
Note that "meeting our expectations" does not automatically mean that there are no failing tests. In many real-world use cases, security tests fail, but the software is still considered worth the risk to deploy because of mitigations for that risk, or perhaps the requirement is inapplicable due to the details of the deployment. With that said, we still want to run our tests to make sure we are continually collecting data; we just don't want our pipeline to halt if it finds a test that we were always expecting to fail.
By default, the InSpec executable returns a code 100 if any tests in a profile run fail. Pipeline orchestrators, like most software, interpret any non-zero return code as a serious failure, and will halt the pipeline run accordingly unless we explicitly tell it to ignore errors. This is why the "VALIDATE - Run InSpec" step has the continue-on-error: true attribute specified.
Our goal is to complete our InSpec scan, collect the result as a report file, and then parse that file to determine if we met our own threshold of security. We can do this with the SAF CLI.
You can get more information on a specific topic by running:
saf [TOPIC] -h
+Let's add two steps to our pipeline to use the SAF CLI to understand our InSpec scan results before we verify them against a threshold.
`,4),S=n("code",null,"pipeline.yml",-1),C=n("div",{class:"language-yaml line-numbers-mode","data-ext":"yml"},[n("pre",{class:"language-yaml"},[n("code",null,[n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" VERIFY "),n("span",{class:"token punctuation"},"-"),s(` Display our results summary + `),n("span",{class:"token key atrule"},"uses"),n("span",{class:"token punctuation"},":"),s(` mitre/saf_action@v1 + `),n("span",{class:"token key atrule"},"with"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token key atrule"},"command_string"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string"},'"view summary -i results/pipeline_run.json"'),s(` + +`),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" VERIFY "),n("span",{class:"token punctuation"},"-"),s(` Ensure the scan meets our results threshold + `),n("span",{class:"token key atrule"},"uses"),n("span",{class:"token punctuation"},":"),s(" mitre/saf_action@v1 "),n("span",{class:"token comment"},"# check if the pipeline passes our defined threshold"),s(` + `),n("span",{class:"token key atrule"},"with"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token key atrule"},"command_string"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string"},'"validate threshold -i results/pipeline_run.json -F threshold.yml"'),s(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),T=n("div",{class:"language-yaml line-numbers-mode","data-ext":"yml"},[n("pre",{class:"language-yaml"},[n("code",null,[n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(` Demo Security Validation Gold Image Pipeline + +`),n("span",{class:"token key atrule"},"on"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token key atrule"},"push"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token key atrule"},"branches"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token punctuation"},"["),s("main"),n("span",{class:"token punctuation"},"]"),s(),n("span",{class:"token comment"},"# trigger this action on any push to main branch"),s(` + +`),n("span",{class:"token key atrule"},"jobs"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token key atrule"},"gold-image"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(` Gold Image NGINX + `),n("span",{class:"token key atrule"},"runs-on"),n("span",{class:"token punctuation"},":"),s(" ubuntu"),n("span",{class:"token punctuation"},"-"),n("span",{class:"token number"},"20.04"),s(` + `),n("span",{class:"token key atrule"},"env"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token key atrule"},"CHEF_LICENSE"),n("span",{class:"token punctuation"},":"),s(" accept "),n("span",{class:"token comment"},"# so that we can use InSpec without manually accepting the license"),s(` + `),n("span",{class:"token key atrule"},"PROFILE"),n("span",{class:"token punctuation"},":"),s(" my_nginx "),n("span",{class:"token comment"},"# path to our profile"),s(` + `),n("span",{class:"token key atrule"},"steps"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" PREP "),n("span",{class:"token punctuation"},"-"),s(" Update runner "),n("span",{class:"token comment"},"# updating all dependencies is always a good start"),s(` + `),n("span",{class:"token key atrule"},"run"),n("span",{class:"token punctuation"},":"),s(" sudo apt"),n("span",{class:"token punctuation"},"-"),s(`get update + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" PREP "),n("span",{class:"token punctuation"},"-"),s(` Install InSpec executable + `),n("span",{class:"token key atrule"},"run"),n("span",{class:"token punctuation"},":"),s(" curl https"),n("span",{class:"token punctuation"},":"),s("//omnitruck.chef.io/install.sh "),n("span",{class:"token punctuation"},"|"),s(" sudo bash "),n("span",{class:"token punctuation"},"-"),s("s "),n("span",{class:"token punctuation"},"-"),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token punctuation"},"-"),s("P inspec "),n("span",{class:"token punctuation"},"-"),s(`v 5 + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" PREP "),n("span",{class:"token punctuation"},"-"),s(" Check out this repository "),n("span",{class:"token comment"},"# because that's where our profile is!"),s(` + `),n("span",{class:"token key atrule"},"uses"),n("span",{class:"token punctuation"},":"),s(` actions/checkout@v3 + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" LINT "),n("span",{class:"token punctuation"},"-"),s(" Run InSpec Check "),n("span",{class:"token comment"},"# double-check that we don't have any serious issues in our profile code"),s(` + `),n("span",{class:"token key atrule"},"run"),n("span",{class:"token punctuation"},":"),s(` inspec check $PROFILE + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" DEPLOY "),n("span",{class:"token punctuation"},"-"),s(` Run a Docker container from nginx + `),n("span",{class:"token key atrule"},"run"),n("span",{class:"token punctuation"},":"),s(" docker run "),n("span",{class:"token punctuation"},"-"),s("dit "),n("span",{class:"token punctuation"},"-"),n("span",{class:"token punctuation"},"-"),s("name nginx nginx"),n("span",{class:"token punctuation"},":"),s(`latest + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" DEPLOY "),n("span",{class:"token punctuation"},"-"),s(` Install Python for our nginx container + `),n("span",{class:"token key atrule"},"run"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token punctuation"},"|"),n("span",{class:"token scalar string"},` + docker exec nginx apt-get update -y + docker exec nginx apt-get install -y python3`),s(` + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" HARDEN "),n("span",{class:"token punctuation"},"-"),s(` Fetch Ansible role + `),n("span",{class:"token key atrule"},"run"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token punctuation"},"|"),n("span",{class:"token scalar string"},` + git clone --branch docker https://github.com/mitre/ansible-nginx-stigready-hardening.git || true + chmod 755 ansible-nginx-stigready-hardening`),s(` + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" HARDEN "),n("span",{class:"token punctuation"},"-"),s(` Fetch Ansible requirements + `),n("span",{class:"token key atrule"},"run"),n("span",{class:"token punctuation"},":"),s(" ansible"),n("span",{class:"token punctuation"},"-"),s("galaxy install "),n("span",{class:"token punctuation"},"-"),s("r ansible"),n("span",{class:"token punctuation"},"-"),s("nginx"),n("span",{class:"token punctuation"},"-"),s("stigready"),n("span",{class:"token punctuation"},"-"),s(`hardening/requirements.yml + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" HARDEN "),n("span",{class:"token punctuation"},"-"),s(` Run Ansible hardening + `),n("span",{class:"token key atrule"},"run"),n("span",{class:"token punctuation"},":"),s(" ansible"),n("span",{class:"token punctuation"},"-"),s("playbook "),n("span",{class:"token punctuation"},"-"),n("span",{class:"token punctuation"},"-"),s("inventory=nginx"),n("span",{class:"token punctuation"},","),s(),n("span",{class:"token punctuation"},"-"),n("span",{class:"token punctuation"},"-"),s("connection=docker ansible"),n("span",{class:"token punctuation"},"-"),s("nginx"),n("span",{class:"token punctuation"},"-"),s("stigready"),n("span",{class:"token punctuation"},"-"),s("hardening/hardening"),n("span",{class:"token punctuation"},"-"),s(`playbook.yml + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" VALIDATE "),n("span",{class:"token punctuation"},"-"),s(` Run InSpec + `),n("span",{class:"token key atrule"},"continue-on-error"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token boolean important"},"true"),s(" "),n("span",{class:"token comment"},"# we dont want to stop if our InSpec run finds failures, we want to continue and record the result"),s(` + `),n("span",{class:"token key atrule"},"run"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token punctuation"},"|"),n("span",{class:"token scalar string"},` + inspec exec $PROFILE \\ + --input-file=$PROFILE/inputs.yml \\ + --target docker://nginx \\ + --reporter cli json:results/pipeline_run.json`),s(` + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" VALIDATE "),n("span",{class:"token punctuation"},"-"),s(" Save Test Result JSON "),n("span",{class:"token comment"},"# save our results to the pipeline artifacts, even if the InSpec run found failing tests"),s(` + `),n("span",{class:"token key atrule"},"uses"),n("span",{class:"token punctuation"},":"),s(" actions/upload"),n("span",{class:"token punctuation"},"-"),s(`artifact@v3 + `),n("span",{class:"token key atrule"},"with"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token key atrule"},"path"),n("span",{class:"token punctuation"},":"),s(` results/pipeline_run.json + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" VERIFY "),n("span",{class:"token punctuation"},"-"),s(` Display our results summary + `),n("span",{class:"token key atrule"},"uses"),n("span",{class:"token punctuation"},":"),s(` mitre/saf_action@v1 + `),n("span",{class:"token key atrule"},"with"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token key atrule"},"command_string"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string"},'"view summary -i results/pipeline_run.json"'),s(` + + `),n("span",{class:"token punctuation"},"-"),s(),n("span",{class:"token key atrule"},"name"),n("span",{class:"token punctuation"},":"),s(" VERIFY "),n("span",{class:"token punctuation"},"-"),s(` Ensure the scan meets our results threshold + `),n("span",{class:"token key atrule"},"uses"),n("span",{class:"token punctuation"},":"),s(" mitre/saf_action@v1 "),n("span",{class:"token comment"},"# check if the pipeline passes our defined threshold"),s(` + `),n("span",{class:"token key atrule"},"with"),n("span",{class:"token punctuation"},":"),s(` + `),n("span",{class:"token key atrule"},"command_string"),n("span",{class:"token punctuation"},":"),s(),n("span",{class:"token string"},'"validate threshold -i results/pipeline_run.json -F threshold.yml"'),s(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),F=n("p",null,"A few things to note here:",-1),L={href:"https://github.com/mitre/saf_action",target:"_blank",rel:"noopener noreferrer"},E=n("li",null,[s("We added the "),n("code",null,"summary"),s(" step because it will print us a concise summary inside the pipeline job view itself. That command takes one file argument; the results file we want to summarize.")],-1),R=n("li",null,[s("The "),n("code",null,"validate threshold"),s(" command, however, needs two files -- one is our report file as usual, and the other is a "),n("strong",null,"threshold file"),s(".")],-1),P=l(`Threshold files are what we use to define what "passing" means for our pipeline, since like we said earlier, it's more complicated than failing the pipeline on a failed test.
Consider the following sample threshold file:
# threshold.yml file
+compliance:
+ min: 80
+passed:
+ total:
+ min: 1
+failed:
+ total:
+ max: 2
+This file specifies that we require a minimum of 80% of the tests to pass. We also specify that at least one of them should pass, and that at maximum two of them can fail.
`,5),V={class:"hint-container info"},N=n("p",{class:"hint-container-title"},"Threshold Files Options",-1),O={href:"https://github.com/mitre/saf/wiki/Validation-with-Thresholds",target:"_blank",rel:"noopener noreferrer"},D=n("p",null,[n("em",null,"NOTE: You can name the threshold file something else or put it in a different location. We specify the name and location only for convenience.")],-1),j=l(`This is a sample pipeline, so we are not too worried about being very stringent. For now, let's settle for running the pipeline with no errors (that is, as long as each test runs, we do not care if it passed or failed, but a source code error should still fail the pipeline).
Create a new file called threshold.yml in the main directory to specify the threshold for acceptable test results:
error:
+ total:
+ max: 0
+How could we change this threshold file to ensure that the pipeline run will fail?
And with that, we have a complete pipeline file. Let's commit our changes and see what happens.
`,5),q=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[n("span",{class:"token function"},"git"),s(),n("span",{class:"token function"},"add"),s(` .github +`),n("span",{class:"token function"},"git"),s(" commit "),n("span",{class:"token parameter variable"},"-s"),s(),n("span",{class:"token parameter variable"},"-m"),s(),n("span",{class:"token string"},'"finishing the pipeline"'),s(` +`),n("span",{class:"token function"},"git"),s(` push origin main +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),H=n("div",{class:"language-bash line-numbers-mode","data-ext":"sh"},[n("pre",{class:"language-bash"},[n("code",null,[s("$"),n("span",{class:"token operator"},">"),s(),n("span",{class:"token function"},"git"),s(),n("span",{class:"token function"},"add"),s(),n("span",{class:"token builtin class-name"},"."),s(` +$`),n("span",{class:"token operator"},">"),s(),n("span",{class:"token function"},"git"),s(" commit "),n("span",{class:"token parameter variable"},"-s"),s(),n("span",{class:"token parameter variable"},"-m"),s(),n("span",{class:"token string"},'"finishing the pipeline"'),s(` +`),n("span",{class:"token punctuation"},"["),s("main e796abd"),n("span",{class:"token punctuation"},"]"),s(` finishing the pipeline + `),n("span",{class:"token number"},"2"),s(" files changed, "),n("span",{class:"token number"},"14"),s(" insertions"),n("span",{class:"token punctuation"},"("),s("+"),n("span",{class:"token punctuation"},")"),s(", "),n("span",{class:"token number"},"1"),s(" deletion"),n("span",{class:"token punctuation"},"("),s("-"),n("span",{class:"token punctuation"},")"),s(` + create mode `),n("span",{class:"token number"},"100644"),s(` threshold.yml +$`),n("span",{class:"token operator"},">"),s(),n("span",{class:"token function"},"git"),s(` push origin main +Enumerating objects: `),n("span",{class:"token number"},"10"),s(`, done. +Counting objects: `),n("span",{class:"token number"},"100"),s("% "),n("span",{class:"token punctuation"},"("),n("span",{class:"token number"},"10"),s("/10"),n("span",{class:"token punctuation"},")"),s(`, done. +Delta compression using up to `),n("span",{class:"token number"},"2"),s(` threads +Compressing objects: `),n("span",{class:"token number"},"100"),s("% "),n("span",{class:"token punctuation"},"("),n("span",{class:"token number"},"3"),s("/3"),n("span",{class:"token punctuation"},")"),s(`, done. +Writing objects: `),n("span",{class:"token number"},"100"),s("% "),n("span",{class:"token punctuation"},"("),n("span",{class:"token number"},"6"),s("/6"),n("span",{class:"token punctuation"},")"),s(", "),n("span",{class:"token number"},"720"),s(" bytes "),n("span",{class:"token operator"},"|"),s(),n("span",{class:"token number"},"720.00"),s(` KiB/s, done. +Total `),n("span",{class:"token number"},"6"),s(),n("span",{class:"token punctuation"},"("),s("delta "),n("span",{class:"token number"},"2"),n("span",{class:"token punctuation"},")"),s(", reused "),n("span",{class:"token number"},"1"),s(),n("span",{class:"token punctuation"},"("),s("delta "),n("span",{class:"token number"},"0"),n("span",{class:"token punctuation"},")"),s(", pack-reused "),n("span",{class:"token number"},"0"),s(` +remote: Resolving deltas: `),n("span",{class:"token number"},"100"),s("% "),n("span",{class:"token punctuation"},"("),n("span",{class:"token number"},"2"),s("/2"),n("span",{class:"token punctuation"},")"),s(", completed with "),n("span",{class:"token number"},"2"),s(),n("span",{class:"token builtin class-name"},"local"),s(` objects. +To https://github.com/wdower/saf-training-lab-environment + c4d9c67`),n("span",{class:"token punctuation"},".."),s("e796abd main -"),n("span",{class:"token operator"},">"),s(` main +$`),n("span",{class:"token operator"},">"),s(` +`)])]),n("div",{class:"line-numbers","aria-hidden":"true"},[n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"}),n("div",{class:"line-number"})])],-1),W=l('Let's hop back to our browser and take a look at the output:
There we go! All validation tests passed!
Note in the SAF CLI Summary step, we get a simple YAML output summary of the InSpec scan:
We see five critical tests (remember how we set them all to impact 1.0?) passing, and no failures:
- profileName: my_nginx
+ resultSets:
+ - pipeline_run.json
+ compliance: 100
+ passed:
+ critical: 5
+ high: 0
+ medium: 0
+ low: 0
+ total: 5
+ failed:
+ critical: 0
+ high: 0
+ medium: 0
+ low: 0
+ total: 0
+ skipped:
+ critical: 0
+ high: 0
+ medium: 0
+ low: 0
+ total: 0
+ error:
+ critical: 0
+ high: 0
+ medium: 0
+ low: 0
+ total: 0
+ no_impact:
+ none: 0
+ total: 0
+Note also that our test report is avaiable as an artifact from the overall pipeline run summary view now:
From here, we can download that file and drop it off in somehting like Heimdall or feed into some other security process at our leisure (or we can add a pipeline step to do that for us!).
In a real use case, if our pipeline passed, we would next save our bonafide hardened image to a secure registry where it could be distributed to developers. If the pipeline did not pass, we would have already collected data describing why, in the form of InSpec scan reports that we save as artifacts.
',11);function G(M,Y){const o=u("ExternalLinkIcon"),p=u("RouterLink"),c=u("CodeTabs");return m(),k("div",null,[v,n("p",null,[s("The "),n("a",f,[s("SAF CLI"),i(o)]),s(' is one the tool that the SAF supports to help automate security validation. It is our "kitchen-sink" utility for pipelines. If you took the '),i(p,{to:"/courses/user/"},{default:e(()=>[s("SAF User Class")]),_:1}),s(", you are already familiar with the SAF CLI's "),i(p,{to:"/courses/user/12.html"},{default:e(()=>[s("attestation")]),_:1}),s(" function.")]),y,g,n("p",null,[s("Some SAF CLI capabilities are listed in this diagram, but you can see all of them on the "),n("a",w,[s("SAF CLI documentation"),i(o)]),s(".")]),_,i(c,{id:"33",data:[{id:"Command"},{id:"Output"}]},{title0:e(({value:a,isActive:t})=>[s("Command")]),title1:e(({value:a,isActive:t})=>[s("Output")]),tab0:e(({value:a,isActive:t})=>[x]),tab1:e(({value:a,isActive:t})=>[A]),_:1}),I,i(c,{id:"51",data:[{id:"Adding Verify Steps"},{id:"pipeline.yml after adding verify steps"}],"tab-id":"shell"},{title0:e(({value:a,isActive:t})=>[s("Adding Verify Steps")]),title1:e(({value:a,isActive:t})=>[S,s(" after adding verify steps")]),tab0:e(({value:a,isActive:t})=>[C]),tab1:e(({value:a,isActive:t})=>[T]),_:1},8,["data"]),F,n("ul",null,[n("li",null,[s("Both steps are using the "),n("a",L,[s("SAF CLI GitHub Action"),i(o)]),s(". This way, we don't need to install it directly on the runner; we can just pass in the command string.")]),E,R]),P,n("div",V,[N,n("p",null,[s("To make more specific or detailed thresholds, check out "),n("a",O,[s("this documentation on generating theshold files"),i(o)]),s(".")]),D]),j,i(c,{id:"112",data:[{id:"Committing And Pushing Code"},{id:"Output of Pushing Code"}],"tab-id":"shell"},{title0:e(({value:a,isActive:t})=>[s("Committing And Pushing Code")]),title1:e(({value:a,isActive:t})=>[s("Output of Pushing Code")]),tab0:e(({value:a,isActive:t})=>[q]),tab1:e(({value:a,isActive:t})=>[H]),_:1}),W])}const B=d(b,[["render",G],["__file","11.html.vue"]]);export{B as default};
diff --git a/assets/11.html-KxdFJYc_.js b/assets/11.html-KxdFJYc_.js
new file mode 100644
index 000000000..085542af7
--- /dev/null
+++ b/assets/11.html-KxdFJYc_.js
@@ -0,0 +1 @@
+const e=JSON.parse(`{"key":"v-57193b6c","path":"/courses/beginner/11.html","title":"11. From STIG to Profile","lang":"en-US","frontmatter":{"order":11,"next":"12.md","title":"11. From STIG to Profile","author":"Aaron Lippold","headerDepth":3,"description":"From STIG to Profile You have seen in some of our examples in this class that a robust profile's controls will include a large number of metadata tags: InSpec control with many ...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/beginner/11.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"11. From STIG to Profile"}],["meta",{"property":"og:description","content":"From STIG to Profile You have seen in some of our examples in this class that a robust profile's controls will include a large number of metadata tags: InSpec control with many ..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"11. From STIG to Profile\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"From STIG to Profile","slug":"from-stig-to-profile","link":"#from-stig-to-profile","children":[{"level":3,"title":"How to Get the Pre-made Profile","slug":"how-to-get-the-pre-made-profile","link":"#how-to-get-the-pre-made-profile","children":[]},{"level":3,"title":"Example 'Stub' Control SV-230502","slug":"example-stub-control-sv-230502","link":"#example-stub-control-sv-230502","children":[]}]}],"git":{},"readingTime":{"minutes":10.71,"words":3213},"filePathRelative":"courses/beginner/11.md","autoDesc":true}`);export{e as data};
diff --git a/assets/11.html-QqaRwBGl.js b/assets/11.html-QqaRwBGl.js
new file mode 100644
index 000000000..4f1e451bd
--- /dev/null
+++ b/assets/11.html-QqaRwBGl.js
@@ -0,0 +1 @@
+const e=JSON.parse(`{"key":"v-3bb2d1e5","path":"/courses/user/11.html","title":"11. Comparing Results","lang":"en-US","frontmatter":{"order":11,"next":"12.md","title":"11. Comparing Results","author":"Emily Rodriguez","headerDepth":3,"description":"11. Comparing Results 11.1 Validate the software after hardening Now that we have hardened the software, we need to run InSpec again to see the results. Let's change directories...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/user/11.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"11. Comparing Results"}],["meta",{"property":"og:description","content":"11. Comparing Results 11.1 Validate the software after hardening Now that we have hardened the software, we need to run InSpec again to see the results. Let's change directories..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Emily Rodriguez"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"11. Comparing Results\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Emily Rodriguez\\"}]}"]]},"headers":[{"level":2,"title":"11. Comparing Results","slug":"_11-comparing-results","link":"#_11-comparing-results","children":[{"level":3,"title":"11.1 Validate the software after hardening","slug":"_11-1-validate-the-software-after-hardening","link":"#_11-1-validate-the-software-after-hardening","children":[]},{"level":3,"title":"11.2 CLI Results","slug":"_11-2-cli-results","link":"#_11-2-cli-results","children":[]},{"level":3,"title":"11.3 Download the Results File","slug":"_11-3-download-the-results-file","link":"#_11-3-download-the-results-file","children":[]},{"level":3,"title":"11.4 Visualize the Results in Heimdall","slug":"_11-4-visualize-the-results-in-heimdall","link":"#_11-4-visualize-the-results-in-heimdall","children":[]}]}],"git":{},"readingTime":{"minutes":4.22,"words":1265},"filePathRelative":"courses/user/11.md","autoDesc":true}`);export{e as data};
diff --git a/assets/11.html-kkXZOg1S.js b/assets/11.html-kkXZOg1S.js
new file mode 100644
index 000000000..e0d585d30
--- /dev/null
+++ b/assets/11.html-kkXZOg1S.js
@@ -0,0 +1 @@
+const e=JSON.parse(`{"key":"v-b878871c","path":"/courses/guidance/11.html","title":"11. Exporting Your Content","lang":"en-US","frontmatter":{"order":11,"next":"12.md","title":"11. Exporting Your Content","author":"Will Dower","headerDepth":3,"description":"11.1 Exporting Your Content At this point, we have tailored two requirements from the original SRG into STIG-ready content, and discussed how to peer review them. Let's discuss ...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/guidance/11.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"11. Exporting Your Content"}],["meta",{"property":"og:description","content":"11.1 Exporting Your Content At this point, we have tailored two requirements from the original SRG into STIG-ready content, and discussed how to peer review them. Let's discuss ..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:image","content":"https://mitre.github.io/saf-training/saf-training/"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"name":"twitter:card","content":"summary_large_image"}],["meta",{"name":"twitter:image:alt","content":"11. Exporting Your Content"}],["meta",{"property":"article:author","content":"Will Dower"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"11. Exporting Your Content\\",\\"image\\":[\\"https://mitre.github.io/saf-training/saf-training/\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Will Dower\\"}]}"]]},"headers":[{"level":2,"title":"11.1 Exporting Your Content","slug":"_11-1-exporting-your-content","link":"#_11-1-exporting-your-content","children":[]},{"level":2,"title":"11.2 Exporting the Guidance Document","slug":"_11-2-exporting-the-guidance-document","link":"#_11-2-exporting-the-guidance-document","children":[{"level":3,"title":"11.2.1 Notes on Releasing","slug":"_11-2-1-notes-on-releasing","link":"#_11-2-1-notes-on-releasing","children":[]},{"level":3,"title":"11.2.2 Notes on Exporting","slug":"_11-2-2-notes-on-exporting","link":"#_11-2-2-notes-on-exporting","children":[]}]},{"level":2,"title":"11.3 Diff Viewer","slug":"_11-3-diff-viewer","link":"#_11-3-diff-viewer","children":[{"level":3,"title":"11.3.1 Creating a Different Component","slug":"_11-3-1-creating-a-different-component","link":"#_11-3-1-creating-a-different-component","children":[]}]}],"git":{},"readingTime":{"minutes":2.78,"words":834},"filePathRelative":"courses/guidance/11.md","autoDesc":true}`);export{e as data};
diff --git a/assets/11.html-nXdLMfTA.js b/assets/11.html-nXdLMfTA.js
new file mode 100644
index 000000000..121115f12
--- /dev/null
+++ b/assets/11.html-nXdLMfTA.js
@@ -0,0 +1,65 @@
+import{_ as t}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as o,o as l,c as r,d as e,e as n,b as a,f as i}from"./app-PAvzDPkc.js";const d="/saf-training/assets/Codespaces_Download_Harden_Results-Hq3hWz77.png",c="/saf-training/assets/Heimdall_Select_Menu-S9wQZY4w.png",p="/saf-training/assets/Heimdall_Click_ComparisonView-XvsXjHbd.png",u={},h=i(`Now that we have hardened the software, we need to run InSpec again to see the results.
Let's change directories to get back to the root directory.
cd /workspaces/saf-training-lab-environment/
+Now, rerun the InSpec scan with a different file name by changing the --reporter to have a new file name indicating that these are the hardened results like this: --reporter cli json:./results/nginx_hardened_results.json.
inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx --reporter cli json:./results/nginx_hardened_results.json --input-file inputs.yml
+After running the command, you should see different results than when we ran the vanilla InSpec scan.
inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx --reporter cli json:./results/nginx_hardened_results.json --input-file inputs.yml
+[2022-09-26T12:33:00+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
+...
+ ↺ V-56019: An NGINX web server utilizing mobile code must meet DoD-defined mobile code
+ requirements.
+ ↺ This check is NA because NGINX does not implement mobile code.
+ ↺ V-56021: The NGINX web server must invalidate session identifiers upon hosted
+ application user logout or other session termination.
+ ↺ This test requires a Manual Review: Verify it invalidates session identifiers when a
+ session is terminated by reviewing the NGINX documentation.
+ ↺ V-56025: Cookies exchanged between the NGINX web server and client, such as session
+ cookies, must have security settings that disallow cookie access outside the
+ originating web server and hosted application.
+ ↺ This check is NA because the proxy_cookie_path directive is not configured.
+ ✔ V-56027: The web server must only accept client certificates issued by DoD PKI
+ or DoD-approved PKI Certification Authorities (CAs).
+ ✔ [["/etc/ssl/nginx-selfsigned.pem"]] is expected not to be nil
+ ✔ x509_certificate /etc/ssl/nginx-selfsigned.pem is expected not to be nil
+ ✔ x509_certificate /etc/ssl/nginx-selfsigned.pem subject.C is expected to cmp == "US"
+ ✔ x509_certificate /etc/ssl/nginx-selfsigned.pem subject.O is expected to cmp == "U.S. Government"
+ ✔ DoD is expected to be in "DoD" and "ECA"
+ ↺ V-56029: The NGINX web server must augment re-creation to a stable and known
+ baseline.
+ ↺ This test requires a Manual Review: Interview the SA and ask for documentation on the
+ disaster recovery methods for the NGINX web server in the event of the necessity for rollback.
+ ↺ V-56031: The NGINX web server must encrypt user identifiers and passwords.
+ ↺ This check is NA because NGINX does not manage authentication.
+ ✔ V-56033: The web server must install security-relevant software updates within
+ the configured time period directed by an authoritative source (e.g., IAVM,
+ CTOs, DTMs, and STIGs).
+ ✔ NGINX version v1.23.1 installed is not more then one patch level behind v1.23.0 is expected to cmp >= "1.23.0"
+ ✔ NGINX version v1.23.1 installed is greater then or equal to the organization approved version v1.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.
+ ✔ V-61353: The web server must remove all export ciphers to protect the
+ confidentiality and integrity of transmitted information.
+ ✔ The ssl_prefer_server_cipher should be set to on.
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+ ✔ Each cipher found in configuration should be included in the list of ciphers approved to encrypt data
+
+
+Profile Summary: 62 successful controls, 3 control failures, 24 controls skipped
+Test Summary: 303 successful, 3 failures, 24 skipped
+As you did before, download the results file.
Take some time to explore the hardened results. Filter through different statuses, checkout the alignment to NIST 800-53 controls, and more!
Another valuable view for monitoring changes and showing results is the comparison view.
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.
When updating Benchmark Profiles, adhere to these key principles to maintain alignment with the original Guidance Documents:
Maintain Version Integrity: Never Merge new requirements into older benchmark branches. This will create a 'mixed baseline' that doesn't align with any specific guidance document. Benchmarks, STIGs, and Guidance Documents form a 'proper subset' - they should be treated as 'all or nothing'. Mixing requirements from different versions can invalidate the concept of 'testing to a known benchmark'.
Benchmarks are a Complete Set of Requirements: A Security Benchmark is 'complete and valid' only when all requirements for a specific Release or Major Version are met. Unlike traditional software projects, features and capabilities cannot be incrementally added. A Security Benchmark and its corresponding InSpec Profile are valid only within the scope of a specific 'Release' of that Benchmark.
Release Readiness Is Predefined: A Benchmark is considered 'ready for release' when it meets the expected thresholds, hardening, and validation results. Don't be overwhelmed by the multitude of changes across the files. Instead, focus on the specific requirement you are working on. Understand its expected failure and success states on each of the target testing platforms. This approach prevents you from being overwhelmed and provides solid pivot points as you work through the implementation of the automated tests for each requirement and its 'contexts'.
Use Vendor-Managed Standard Releases: When setting up a test suite, prioritize using vendor-managed standard releases for software installations and baseline configurations. This should be the starting point for both 'vanilla' and 'hardening' workflows. This approach ensures that your initial and ongoing testing, hardening, and validation closely mirror the real-world usage scenarios of your end-users.
By adhering to these principles, you ensure that your updates to Benchmark Profiles are consistent, accurate, and aligned with the original guidance documents.
",3),s=[r];function o(l,c){return t(),n("div",null,s)}const p=e(i,[["render",o],["__file","11.html.vue"]]);export{p as default}; diff --git a/assets/11.html-rnOvxXZY.js b/assets/11.html-rnOvxXZY.js new file mode 100644 index 000000000..f23a01fcf --- /dev/null +++ b/assets/11.html-rnOvxXZY.js @@ -0,0 +1,560 @@ +import{_ as u}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as o,o as p,c as d,d as s,e as n,b as t,w as e,f as c}from"./app-PAvzDPkc.js";const m="/saf-training/assets/Download_STIG_Viewer-zAPfTvLY.png",h="/saf-training/assets/Download_STIG-N5yFp_SQ.png",v={},k=s("h2",{id:"from-stig-to-profile",tabindex:"-1"},[s("a",{class:"header-anchor",href:"#from-stig-to-profile","aria-hidden":"true"},"#"),n(" From STIG to Profile")],-1),S=s("p",null,"You have seen in some of our examples in this class that a robust profile's controls will include a large number of metadata tags:",-1),V={class:"hint-container details"},g=s("summary",null,"InSpec control with many STIG-related tags",-1),f={href:"https://github.com/mitre/redhat-enterprise-linux-7-stig-baseline/blob/main/controls/SV-204392.rb",target:"_blank",rel:"noopener noreferrer"},_=c(`control 'SV-204392' do
+ title 'The Red Hat Enterprise Linux operating system must be configured so that the file permissions, ownership,
+ and group membership of system files and commands match the vendor values.'
+ desc 'Discretionary access control is weakened if a user or group has access permissions to system files and
+ directories greater than the default.'
+ desc 'check', ...
+ desc 'fix', ...
+ impact 0.7
+ tag legacy: ['V-71849', 'SV-86473']
+ tag severity: 'high'
+ tag gtitle: 'SRG-OS-000257-GPOS-00098'
+ tag satisfies: ['SRG-OS-000257-GPOS-00098', 'SRG-OS-000278-GPOS-00108']
+ tag gid: 'V-204392'
+ tag rid: 'SV-204392r880752_rule'
+ tag stig_id: 'RHEL-07-010010'
+ tag fix_id: 'F-36302r880751_fix'
+ tag cci: ['CCI-001494', 'CCI-001496', 'CCI-002165', 'CCI-002235']
+ tag nist: ['AU-9', 'AU-9 (3)', 'AC-3 (4)', 'AC-6 (10)']
+ tag subsystems: ['permissions', 'package', 'rpm']
+ tag 'host'
+ tag 'container'
+
+ describe the_actual_test do # the actual describe block appears on line 54 of this control!
+ ...
+ end
+end
+(The RHEL8 STIG is at version 1, release 5 at time of writing, but may have been updated by the time you downloaded. This will not affect how we use the STIG in this class.)
Timesaver Ahead!
We already converted the XCCDF STIG Benchmark into a starter profile using the saf generate xccdf_benchmark2inspec_stub command using the correct flags, mapping file and other options. In a moment we will show you how to grab our pre-made profile that we generated with the SAF CLI.
wget"},{id:"Output"}],"tab-id":"shell"},{title0:e(({value:l,isActive:a})=>[n("Fetching the pre-made profile with "),z]),title1:e(({value:l,isActive:a})=>[n("Output")]),tab0:e(({value:l,isActive:a})=>[B]),tab1:e(({value:l,isActive:a})=>[$]),_:1}),U,t(i,{id:"75",data:[{id:"Uncompressing the profile"},{id:"Output"}],"tab-id":"shell"},{title0:e(({value:l,isActive:a})=>[n("Uncompressing the profile")]),title1:e(({value:l,isActive:a})=>[n("Output")]),tab0:e(({value:l,isActive:a})=>[M]),tab1:e(({value:l,isActive:a})=>[W]),_:1}),K,Y,t(i,{id:"89",data:[{id:"Stub Generated InSpec Control"},{id:"Completed InSpec Control"}],"tab-id":"shell"},{title0:e(({value:l,isActive:a})=>[n("Stub Generated InSpec Control")]),title1:e(({value:l,isActive:a})=>[n("Completed InSpec Control")]),tab0:e(({value:l,isActive:a})=>[j]),tab1:e(({value:l,isActive:a})=>[J]),_:1}),Q,s("div",Z,[ss,s("p",null,[n("From the real "),s("a",ns,[n("MITRE SAF RHEL8 InSpec profile"),t(r)]),n(". Note that the control accounts for a few more edge cases than what we've done in this class, but it's still recognizably just a bunch of "),es,n(" and "),ls,n(" wrapped in "),as,n(" blocks.")])]),ts,s("div",rs,[is,s("p",null,[n("For more background on STIGs, see the "),t(b,{to:"/courses/guidance/03.html"},{default:e(()=>[n("SAF Guidance content")]),_:1}),n(".")])])])}const ds=u(v,[["render",os],["__file","11.html.vue"]]);export{ds as default};
diff --git a/assets/11.html-skD8zwiy.js b/assets/11.html-skD8zwiy.js
new file mode 100644
index 000000000..e561429d0
--- /dev/null
+++ b/assets/11.html-skD8zwiy.js
@@ -0,0 +1 @@
+const e=JSON.parse('{"key":"v-6200cf3c","path":"/courses/advanced/11.html","title":"11. Verifying Results With The SAF CLI","lang":"en-US","frontmatter":{"order":11,"next":"12.md","title":"11. Verifying Results With The SAF CLI","author":"Will Dower","headerDepth":3,"description":"Verification At this point we have a much more mature workflow file. We have one more activity we need to do -- verification, or checking that the output of our validation run m...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/advanced/11.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"11. Verifying Results With The SAF CLI"}],["meta",{"property":"og:description","content":"Verification At this point we have a much more mature workflow file. We have one more activity we need to do -- verification, or checking that the output of our validation run m..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Will Dower"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"11. Verifying Results With The SAF CLI\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Will Dower\\"}]}"]]},"headers":[{"level":2,"title":"Verification","slug":"verification","link":"#verification","children":[{"level":3,"title":"The SAF CLI","slug":"the-saf-cli","link":"#the-saf-cli","children":[]},{"level":3,"title":"Updating the Workflow File","slug":"updating-the-workflow-file","link":"#updating-the-workflow-file","children":[]}]}],"git":{},"readingTime":{"minutes":5.87,"words":1760},"filePathRelative":"courses/advanced/11.md","autoDesc":true}');export{e as data};
diff --git a/assets/11.html-uDyMJ-ud.js b/assets/11.html-uDyMJ-ud.js
new file mode 100644
index 000000000..710c34b8f
--- /dev/null
+++ b/assets/11.html-uDyMJ-ud.js
@@ -0,0 +1 @@
+const e=JSON.parse('{"key":"v-ac554bf0","path":"/courses/profile-dev-test/11.html","title":"Rules of the Road","lang":"en-US","frontmatter":{"order":11,"next":"12.md","title":"Rules of the Road","author":"Aaron Lippold","description":"When updating Benchmark Profiles, adhere to these key principles to maintain alignment with the original Guidance Documents: 1. Maintain Version Integrity: Never Merge new requi...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/profile-dev-test/11.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Rules of the Road"}],["meta",{"property":"og:description","content":"When updating Benchmark Profiles, adhere to these key principles to maintain alignment with the original Guidance Documents: 1. Maintain Version Integrity: Never Merge new requi..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Rules of the Road\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[],"git":{},"readingTime":{"minutes":1.06,"words":319},"filePathRelative":"courses/profile-dev-test/11.md","autoDesc":true}');export{e as data};
diff --git a/assets/12.html-1CYTXiAL.js b/assets/12.html-1CYTXiAL.js
new file mode 100644
index 000000000..1f6070a51
--- /dev/null
+++ b/assets/12.html-1CYTXiAL.js
@@ -0,0 +1 @@
+import{_ as a}from"./plugin-vue_export-helper-x3n3nnut.js";import{r,o as i,c,d as e,e as t,b as o,w as h}from"./app-PAvzDPkc.js";const u={},l=e("h2",{id:"next-steps",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#next-steps","aria-hidden":"true"},"#"),t(" Next Steps")],-1),d=e("h3",{id:"take-the-class-survey",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#take-the-class-survey","aria-hidden":"true"},"#"),t(" Take the Class Survey")],-1),f={href:"https://forms.office.com/g/W2xtcV2frW",target:"_blank",rel:"noopener noreferrer"},p=e("h3",{id:"save-your-work-on-github",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#save-your-work-on-github","aria-hidden":"true"},"#"),t(" Save your work on GitHub")],-1),_={href:"https://education.github.com/git-cheat-sheet-education.pdf",target:"_blank",rel:"noopener noreferrer"},m={href:"https://learngitbranching.js.org/",target:"_blank",rel:"noopener noreferrer"},g=e("h3",{id:"reference-other-class-content",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#reference-other-class-content","aria-hidden":"true"},"#"),t(" Reference other class content")],-1),b=e("p",null,"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, we encourage you to go back to the User Class or Beginner Security Automation Developer Class (shown in the table of contents on the left).",-1),y=e("h3",{id:"check-out-the-rest-of-mitre-saf-c-s-content",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#check-out-the-rest-of-mitre-saf-c-s-content","aria-hidden":"true"},"#"),t(" Check Out the Rest of MITRE SAF(c)'s Content")],-1),k={href:"https://saf.mitre.org",target:"_blank",rel:"noopener noreferrer"},v=e("h3",{id:"contact-us",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#contact-us","aria-hidden":"true"},"#"),t(" Contact Us")],-1),w=e("p",null,[t("The MITRE SAF(c) team can be contacted at "),e("a",{href:"mailto:saf@groups.mitre.org"},"saf@groups.mitre.org"),t(". 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.")],-1);function x(S,I){const n=r("ExternalLinkIcon"),s=r("RouterLink");return i(),c("div",null,[l,d,e("p",null,[t("Take our brief "),e("a",f,[t("survey"),o(n)]),t(" to give feedback to fuel class improvement.")]),p,e("p",null,[t("If you want to save your work in your remote repository in GitHub, you need to use Git commands. You can reference a "),e("a",_,[t("Git cheat sheet"),o(n)]),t(" or checkout "),e("a",m,[t("this Git tutorial"),o(n)]),t(".")]),g,b,y,e("p",null,[t("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 "),e("a",k,[t("saf.mitre.org"),o(n)]),t(". 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 "),o(s,{to:"/resources/"},{default:h(()=>[t("Resources Page")]),_:1})]),v,w])}const C=a(u,[["render",x],["__file","12.html.vue"]]);export{C as default};
diff --git a/assets/12.html-1aA7mi6b.js b/assets/12.html-1aA7mi6b.js
new file mode 100644
index 000000000..d1fd1f758
--- /dev/null
+++ b/assets/12.html-1aA7mi6b.js
@@ -0,0 +1 @@
+const e=JSON.parse(`{"key":"v-58ce140b","path":"/courses/beginner/12.html","title":"12. Put it in Practice!","lang":"en-US","frontmatter":{"order":12,"next":"13.md","title":"12. Put it in Practice!","author":"Aaron Lippold","headerDepth":3,"description":"Getting Started on the RHEL8 Baseline Let's practice writing a few 'real' controls using a security guidance document. The Steps to write an InSpec Control 1. Read the Control -...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/beginner/12.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"12. Put it in Practice!"}],["meta",{"property":"og:description","content":"Getting Started on the RHEL8 Baseline Let's practice writing a few 'real' controls using a security guidance document. The Steps to write an InSpec Control 1. Read the Control -..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"12. Put it in Practice!\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"Getting Started on the RHEL8 Baseline","slug":"getting-started-on-the-rhel8-baseline","link":"#getting-started-on-the-rhel8-baseline","children":[{"level":3,"title":"Example Control Using login_defs Resource:","slug":"example-control-using-login-defs-resource","link":"#example-control-using-login-defs-resource","children":[]},{"level":3,"title":"Controls We Will Demonstrate","slug":"controls-we-will-demonstrate","link":"#controls-we-will-demonstrate","children":[]},{"level":3,"title":"Suggested Level 1 Controls","slug":"suggested-level-1-controls","link":"#suggested-level-1-controls","children":[]},{"level":3,"title":"Suggested Level 2 Controls","slug":"suggested-level-2-controls","link":"#suggested-level-2-controls","children":[]},{"level":3,"title":"Suggested InSpec Resources to Review","slug":"suggested-inspec-resources-to-review","link":"#suggested-inspec-resources-to-review","children":[]}]},{"level":2,"title":"Completed RHEL8 Profile for Reference","slug":"completed-rhel8-profile-for-reference","link":"#completed-rhel8-profile-for-reference","children":[]}],"git":{},"readingTime":{"minutes":3.69,"words":1107},"filePathRelative":"courses/beginner/12.md","autoDesc":true}`);export{e as data};
diff --git a/assets/12.html-9oj58LSE.js b/assets/12.html-9oj58LSE.js
new file mode 100644
index 000000000..e65b22275
--- /dev/null
+++ b/assets/12.html-9oj58LSE.js
@@ -0,0 +1 @@
+const e=JSON.parse(`{"key":"v-b50ed5de","path":"/courses/guidance/12.html","title":"12. Publishing a STIG","lang":"en-US","frontmatter":{"order":12,"next":"13.md","title":"12. Publishing a STIG","author":"Will Dower","headerDepth":3,"description":"12.1 Notes on Formally Publishing a STIG The STIG Process Most of this section is informed by DISA's own published guidance for the Vendor STIG Process, as well as the experienc...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/guidance/12.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"12. Publishing a STIG"}],["meta",{"property":"og:description","content":"12.1 Notes on Formally Publishing a STIG The STIG Process Most of this section is informed by DISA's own published guidance for the Vendor STIG Process, as well as the experienc..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Will Dower"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"12. Publishing a STIG\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Will Dower\\"}]}"]]},"headers":[{"level":2,"title":"12.1 Notes on Formally Publishing a STIG","slug":"_12-1-notes-on-formally-publishing-a-stig","link":"#_12-1-notes-on-formally-publishing-a-stig","children":[]},{"level":2,"title":"12.2 Starting the Process","slug":"_12-2-starting-the-process","link":"#_12-2-starting-the-process","children":[{"level":3,"title":"12.2.1 Writing Style","slug":"_12-2-1-writing-style","link":"#_12-2-1-writing-style","children":[]}]},{"level":2,"title":"12.3 Stages of STIG Development","slug":"_12-3-stages-of-stig-development","link":"#_12-3-stages-of-stig-development","children":[{"level":3,"title":"12.3.1 Stage 1 STIG Development (The First Ten Requirements)","slug":"_12-3-1-stage-1-stig-development-the-first-ten-requirements","link":"#_12-3-1-stage-1-stig-development-the-first-ten-requirements","children":[]},{"level":3,"title":"12.3.2 Stage 2 STIG Development","slug":"_12-3-2-stage-2-stig-development","link":"#_12-3-2-stage-2-stig-development","children":[]},{"level":3,"title":"12.3.3 Stage 3 STIG Development","slug":"_12-3-3-stage-3-stig-development","link":"#_12-3-3-stage-3-stig-development","children":[]},{"level":3,"title":"12.3.4 Stage 4 STIG Development","slug":"_12-3-4-stage-4-stig-development","link":"#_12-3-4-stage-4-stig-development","children":[]},{"level":3,"title":"12.3.5 STIG Validation","slug":"_12-3-5-stig-validation","link":"#_12-3-5-stig-validation","children":[]},{"level":3,"title":"12.3.6 Review and Approval","slug":"_12-3-6-review-and-approval","link":"#_12-3-6-review-and-approval","children":[]}]}],"git":{},"readingTime":{"minutes":2.47,"words":740},"filePathRelative":"courses/guidance/12.md","autoDesc":true}`);export{e as data};
diff --git a/assets/12.html-SN14diUW.js b/assets/12.html-SN14diUW.js
new file mode 100644
index 000000000..5be1f8b64
--- /dev/null
+++ b/assets/12.html-SN14diUW.js
@@ -0,0 +1 @@
+const e=JSON.parse(`{"key":"v-63b5a7db","path":"/courses/advanced/12.html","title":"12. Next Steps","lang":"en-US","frontmatter":{"order":12,"title":"12. Next Steps","author":"Emily","headerDepth":3,"description":"Next Steps Take the Class Survey Take our brief survey (https://forms.office.com/g/W2xtcV2frW) to give feedback to fuel class improvement. Save your work on GitHub If you want t...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/advanced/12.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"12. Next Steps"}],["meta",{"property":"og:description","content":"Next Steps Take the Class Survey Take our brief survey (https://forms.office.com/g/W2xtcV2frW) to give feedback to fuel class improvement. Save your work on GitHub If you want t..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Emily"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"12. Next Steps\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Emily\\"}]}"]]},"headers":[{"level":2,"title":"Next Steps","slug":"next-steps","link":"#next-steps","children":[{"level":3,"title":"Take the Class Survey","slug":"take-the-class-survey","link":"#take-the-class-survey","children":[]},{"level":3,"title":"Save your work on GitHub","slug":"save-your-work-on-github","link":"#save-your-work-on-github","children":[]},{"level":3,"title":"Reference other class content","slug":"reference-other-class-content","link":"#reference-other-class-content","children":[]},{"level":3,"title":"Check Out the Rest of MITRE SAF(c)'s Content","slug":"check-out-the-rest-of-mitre-saf-c-s-content","link":"#check-out-the-rest-of-mitre-saf-c-s-content","children":[]},{"level":3,"title":"Contact Us","slug":"contact-us","link":"#contact-us","children":[]}]}],"git":{},"readingTime":{"minutes":0.96,"words":289},"filePathRelative":"courses/advanced/12.md","autoDesc":true}`);export{e as data};
diff --git a/assets/12.html-UW4blz-R.js b/assets/12.html-UW4blz-R.js
new file mode 100644
index 000000000..9a01c4cee
--- /dev/null
+++ b/assets/12.html-UW4blz-R.js
@@ -0,0 +1 @@
+import{_ as s}from"./plugin-vue_export-helper-x3n3nnut.js";import{r,o as i,c as a,d as e,e as t,b as n,f as c}from"./app-PAvzDPkc.js";const d={},l=e("p",null,"A patch update involves making minor changes to a profile to fix issues or improve functionality. Here's a step-by-step guide:",-1),u=e("strong",null,"Report the Issue:",-1),h={href:"https://github.com/mitre/redhat-enterprise-linux-8-stig-baseline/issues",target:"_blank",rel:"noopener noreferrer"},p=c("tagged patch release you're targeting for the update.inspec.yml inputs, thresholds, etc. Don't worry about the InSpec version in the inspec.yml - the release process handles that.vanilla and hardened variants of the known bad and known good states of the AWS EC2 and Docker test targets. Also, test your controls outside perfect conditions to ensure they handle non-optimal target environments. Verify that your update considers the container, virtual machine, and 1U machine testing context of applicability.bundle exec rake lint and bundle exec rake lint:autocorrect commands from the test suite to lint your updates.Fixes #ISSUE in your commit messages to automatically close the issue when your PR is merged.Most of this section is informed by DISA's own published guidance for the Vendor STIG Process, as well as the experiences of external teams and Vulcan stakeholders who have undergone the STIG creation process.
We recommend that you review the official Vendor STIG Process guide (see Resources for a copy) if you want to undergo the process.
Using Vulcan for Aritifact Management
DISA will require you to provide your draft content for review in Excel format.
That is to say, DISA's process is completely separate to Vulcan, and they will not need access to it.
Luckily, Vulcan can both export STIG-ready content to Excel format for DISA to ingest, and load reviewed content from DISA as a separate Component for easy comparison.
First and foremost - reach out early!
DISA created the Vendor STIG Process to ensure that the content produced by the vendor community is up to DOD standard. As such, DISA prefers to meet with the STIG-ready content team before the content is written to discuss the characteristics of the software component the team is trying to write guidance for.
DISA will also provide guidance on which SRG (or set of SRGs) should be selected as a foundation.
Do I need to be the actual vendor to publish my content?
Not necessarily. DISA certainly expects that most people who look to formally publish STIG content will be the vendor that created a particular software component, but this is not required.
If you expect that the content you have created for a component for one project would be:
a) useful to the wider security community, or
b) useful to you personally on a later project
then reach out to DISA to formally publish it.
DISA's documentation on the STIG process[1] breaks it down into four development stages after the initial SRG selection, punctuated by frequent updates to and review by the agency. After the external author team finishes STIG development, there are a few more internal reviews at DISA before the final decision is made to publish.
The author team will first fill out a total of 10 of the requirements in the STIG document, where the 10 requirements are a mix of all statuses (Applicable – Configurable, Applicable – Inherently Meets, Applicable – Does Not Meet, and Not Applicable).
If this initial round of requirements are written satisfactorily, the author team can continue work on the STIG content for 30 days before the next work-in-progress review from DISA. The agency may give further feedback on areas to improve at this point before continuing.
The author team can continue writing STIG content for another 30 days (a total of 60 days after the initial decision to proceed) before the next round of work-in-progress review from DISA. The agency may give further feedback on areas to improve at this point before continuing.
After another 30 days (90 days total from the initial decision to proceed) the author team should submit a completed initial draft of the STIG to DISA for a full validation of the content.
Once the full draft is submitted, DISA will validate the contents of the STIG Check and Fix instructions by implementing them against a test system (the author team, if they work for the vendor of a not-yet-released product, may need to work to ensure that DISA can access a test system).
At this point, DISA personnel write up a formal reports to the DISA Authorizing Offical and confirm one last time that the STIG conforms to the style guide. Content that passes this final review is now officially a STIG and can be published to the DOD Cyber Exchange.
Section 3 of the "Vendor STIG Process", Version 4 Release 1. See Resources. ↩︎
desc "check", "Verify all local interactive users on RHEL 8 are assigned a home directory upon creation with
+the following command:
+
+$ sudo grep -i create_home /etc/login.defs
+...
+Remember the matchers
Here, the login_defs resource shows examples using the includes and eq matcher. Here, we use eq because we are looking for only one result from the command, not an array of items.
inspec exec rhel8-baseline-stubs -t docker://redhat8
+| Control | Resource Used |
|---|---|
| SV-230324 | login_defs resource |
| SV-230250 | directory resource |
| SV-230243 | directory looping & file resource |
| SV-230505 | non applicable use case & package resource |
| Control | Resource Used |
|---|---|
| SV-230383 | login_defs resource |
| SV-230249 | directory resource |
| SV-230471 | directory looping & file resource |
| SV-230241 | non applicable use case & package resource |
| Control | Resource Used |
|---|---|
| SV-230281 | parse config file |
| SV-230365 | login_defs resource |
| SV-230264 | file content |
Key Elements in this Profile
impact 0 for NA & Container Aware Controlscontainer aware, andfail fast approach to testing execution.Wait, does this mean that I can cheat on all of these exercises by looking up all the real controls?!
Yes. Feel free. We suggest you at least try thinking through how you'd write this test code without the real baseline, though.
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.
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.
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?
Here is an example of an attested control that we can create based on
saf attest create -o ./results/manual_attestation_results.json
+Enter a control ID or enter 'q' to exit: V-40792
+Attestation explanation: Verified that the server-side session management is configured correctly.
+Frequency (1d/3d/1wk/2wk/1m/3m/6m/1y/1.5y/custom): 3m
+Enter status ((p)assed/(f)ailed): p
+Updated By: Emily Rodriguez
+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.
Use the -h flag to learn about applying attestations.
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
+As we have done before,
nginx_hardened_with_manual_attestations.json file.In the example, a few manual attestations were completed, some of which were recorded as passing and some as failing. You may have chosen to do your manual attestations differently and have different metrics.
You can look at the details to find the attestation information captured. Expand the details for each control to view this data.
A Release Update involves creating a new branch, v#{x}R#{x+1}, from the current main or latest patch release branch. The saf generate delta workflow is then run, which updates the metadata of the controls, inspec.yml, README.md, and other profile elements, while preserving the describe and ruby code logic. This workflow is detailed in the Inspec Delta section. After the initial commit of the new release branch, follow these steps to keep your work organized:
control ids in the updated benchmark. This can be in CSV, Markdown Table, or in the PR overview information section. This helps track completed and pending work. PRs off the v#{x}r#{x+1} can also be linked in the table, especially if using a micro vs massive PR approach.hardening content (ansible, puppet, chef, hardened docker images, hardened vagrant boxes) to meet new requirements. Ensure the CI/CD process still functions with the updated elements, preferably on the PR as well.titles and other labels to reflect the updated release number of the Benchmark.check text or fix text are likely to require inspec code changes. If the check text and fix text of a control remain unchanged, it's likely only a cosmetic update, with no change in the security requirement or validation code.A Major Version Update involves transitioning to a new STIG Benchmark, which introduces a new Rule ID index. This process is more complex than a Release Update due to the need for aligning old requirements (Rule IDs) with the new ones.
For example, when transitioning from RedHat Enterprise Linux 8 v1R12 to Red Hat Enterprise Linux 9 V1R1, the alignment of InSpec tests to the new requirements must be fuzzy matched. This involves using common identifiers such as SRG ID, CCIs, and, if necessary, the title and descriptions.
This is crucial when a single requirement from the old benchmark is split into multiple requirements in the new benchmark, although this is usually a rare occurrence.
",3),h={href:"https://vulcan.mitre.org",target:"_blank",rel:"noopener noreferrer"},u=e("code",null,"Delta",-1),p=e("p",null,[n("The good news is that "),e("strong",null,"these improvements are within reach"),n(". We can leverage the existing work from "),e("code",null,"Vulcan"),n(" and hopefully soon incorporate these improvements into the SAF "),e("code",null,"Delta"),n(" tool as a direct function.")],-1),m=e("p",null,"Once the 'old controls' and 'new controls' are aligned across 'Rule IDs', you can migrate the InSpec / Ruby code into their respective places.",-1),_=e("p",null,[n("Then, you follow the same setup, CI/CD organization, and control update process as in the "),e("code",null,"Release Update"),n(" process and hopfully finding that the actual InSpec code from the previous benchmark is very close to the needed InSpec code for the same 'requirement' in the new Benchmark.")],-1);function f(g,v){const o=s("ExternalLinkIcon");return r(),a("div",null,[d,e("p",null,[n("We use a similar process in our "),e("a",h,[n("MITRE Vulcan"),i(o)]),n(" to align 'Related Controls' in your Vulcan project to existing published STIG documents. However, the "),u,n(" tool currently requires manual intervention, and improvements are needed to automate this process.")]),p,m,_])}const x=t(l,[["render",f],["__file","14.html.vue"]]);export{x as default}; diff --git a/assets/14.html-XM-PcHav.js b/assets/14.html-XM-PcHav.js new file mode 100644 index 000000000..83cec2c38 --- /dev/null +++ b/assets/14.html-XM-PcHav.js @@ -0,0 +1 @@ +import{_ as o}from"./plugin-vue_export-helper-x3n3nnut.js";import{r,o as s,c as n,d as t,e,b as l,f as a}from"./app-PAvzDPkc.js";const c="/saf-training/assets/SAF_Capabilities_Normalize-g0EjxQYS.png",h="/saf-training/assets/Heimdall_Samples-m15bvKmA.png",d="/saf-training/assets/Heimdall_Samples_Select-X7tVD4Jb.png",p="/saf-training/assets/Heimdall_TreeMap_Fuller-Bwbdr8fo.png",u="/saf-training/assets/Heimdall_MultiResults2-UId-VJn7.png",f="/saf-training/assets/Heimdall_MultiResults-OJWUYftF.png",m="/saf-training/assets/Heimdall_Export_Menu-zGjHDWhI.png",g={},_=a('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).
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.
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.
Choose some sample data to add to the full security of a theoretical software stack.
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.
In this big picture view, you can see the whole security posture and filter down, for example, on high failures across all scans. Your results may look different than these pictures depending on what you have loaded in Heimdall
And in the results details, you can see what file - in other words what scan or part of the system, is causing the problem.
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!
Test Kitchen's workflow involves building out suites and platforms using its drivers and provisioners. It follows a create, converge, verify, and destroy cycle:
In our testing workflow, we have defined four test suites to test different deployment patterns in two configurations - vanilla and hardened.
vanilla: This represents a completely stock installation of the testing target, as provided by the product vendor, with no configuration updates beyond what is 'shipped' by the vendor. Apart from the standard Test Kitchen initialization, the system is considered 'stock'.hardened: This configuration is set up using the driver section of the Test Kitchen suite and is executed during the converge phase. The hardened configuration represents the final target configuration state of our test instance, adhering to the recommended configuration of the Benchmark we are working on. For example, it aligns as closely as possible with the Red Hat Enterprise Linux V1R12 recommendations.The following Ruby gems are required to install private Supermarket using the supermarket-omnibus-cookbook:
These should be accessible from your Gem mirror.
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:
#!/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.
`,8);function q(N,G){const t=i("ExternalLinkIcon");return s(),a("div",null,[u,e("div",h,[d,e("p",null,[n("For more information on how to install InSpec on an airgapped system use the "),e("a",m,[n("chef instructions"),o(t)]),n(" as guidance")])]),f,_,e("ol",null,[g,b,k,x,e("li",null,[n("You have an artifact store for file downloads. At a minimum, it should have the following packages available: "),e("ol",null,[y,v,w,e("li",null,[n("An "),e("a",j,[n("install script"),o(t)]),n(" for Chef Infra Client")])])])]),T,S,R,e("ul",null,[e("li",null,[e("a",A,[n("supermarket-omnibus-cookbook"),o(t)])]),e("li",null,[e("a",C,[n("chef-ingredient"),o(t)])]),e("li",null,[e("a",E,[n("hostsfile"),o(t)])])]),I,l(` ## 14. Viewing and Analyzing Results + +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). + +\`\`\` +$ inspec exec /root/my_nginx -t ssh://TARGET_USERNAME:TARGET_PASSWORD@TARGET_IP --reporter cli json:baseline_output.json +\`\`\` + +### 14.1. 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. + +Output json to screen. + +\`\`\` +inspec exec /root/my_nginx --reporter json +or +inspec exec /root/my_nginx --reporter json:- +\`\`\` + +Output yaml to screen + +\`\`\` +inspec exec /root/my_nginx --reporter yaml +or +inspec exec /root/my_nginx --reporter yaml:- +\`\`\` + +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. + +\`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. + +\`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 --. + +\`inspec exec --reporter json junit:/tmp/junit.xml -- profile1 profile2\` + +Output cli to screen and write json to a file. + +\`\`\`json +{ + "reporter": { + "cli": { + "stdout": true + }, + "json": { + "file": "/tmp/output.json", + "stdout": false + } + } +} +\`\`\` + +### 14.2. Supported Reporters + +The following are the current supported reporters: + +- cli +- json +- json-min +- yaml +- documentation +- junit +- progress +- json-rspec +- html + +You can read more about [InSpec Reporters](https://www.inspec.io/docs/reference/reporters/) on the documentation page. + +### 14.3. Putting it all together + +The following command will run the nginx baseline profile from github and use the reporter to output a json, you will need this for the next step loading it into heimdall: + +\`$ inspec exec https://github.com/dev-sec/nginx-baseline -t ssh://TARGET_USERNAME:TARGET_PASSWORD@TARGET_IP --reporter cli json:baseline_output.json\` `)])}const D=r(p,[["render",q],["__file","15.html.vue"]]);export{D as default}; diff --git a/assets/16.html-PdB6Rg-R.js b/assets/16.html-PdB6Rg-R.js new file mode 100644 index 000000000..4a058a482 --- /dev/null +++ b/assets/16.html-PdB6Rg-R.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-9b44d5ba","path":"/courses/profile-dev-test/16.html","title":"Test Kitchen - Create","lang":"en-US","frontmatter":{"order":16,"next":"17.md","title":"Test Kitchen - Create","author":"Aaron Lippold","index":true,"description":"The create stage in Test Kitchen sets up testing environments. It uses standard and patched images from AWS and Red Hat, including AMI EC2 images, Docker containers, and Vagrant...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/profile-dev-test/16.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Test Kitchen - Create"}],["meta",{"property":"og:description","content":"The create stage in Test Kitchen sets up testing environments. It uses standard and patched images from AWS and Red Hat, including AMI EC2 images, Docker containers, and Vagrant..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Test Kitchen - Create\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[],"git":{},"readingTime":{"minutes":0.42,"words":126},"filePathRelative":"courses/profile-dev-test/16.md","autoDesc":true}');export{e as data}; diff --git a/assets/16.html-c-vzbbVY.js b/assets/16.html-c-vzbbVY.js new file mode 100644 index 000000000..ee09e0d44 --- /dev/null +++ b/assets/16.html-c-vzbbVY.js @@ -0,0 +1 @@ +import{_ as s}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as a,o as c,c as r,d as e,e as t,b as o}from"./app-PAvzDPkc.js";const i={},l=e("h1",{id:"test-kitchen-create-stage",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#test-kitchen-create-stage","aria-hidden":"true"},"#"),t(" Test Kitchen Create Stage")],-1),h=e("p",null,[t("The "),e("code",null,"create"),t(" stage in Test Kitchen sets up testing environments. It uses standard and patched images from AWS and Red Hat, including AMI EC2 images, Docker containers, and Vagrant boxes.")],-1),d=e("p",null,"Test Kitchen automatically fetches the latest images from sources like Amazon Marketplace, DockerHub, Vagrant Marketplace, and Bento Hub. You can customize this to use different images, private repositories (like Platform One's Iron Bank), or local images.",-1),_={href:"https://kitchen.ci",target:"_blank",rel:"noopener noreferrer"},u=e("code",null,"kitchen-ec2",-1),m=e("code",null,"kitchen-vagrant",-1),p=e("code",null,"kitchen-sync",-1),f={href:"https://github.com/inspec/kitchen-inspec",target:"_blank",rel:"noopener noreferrer"},k=e("code",null,"kitchen-inspec",-1);function g(b,x){const n=a("ExternalLinkIcon");return c(),r("div",null,[l,h,d,e("p",null,[t("For more details on how Test Kitchen manages images, visit the "),e("a",_,[t("Test Kitchen website"),o(n)]),t(". You can also refer to the GitHub documentation for the "),u,t(", "),m,t(", "),p,t(", and "),e("a",f,[k,o(n)]),t(" project on GitHub.")])])}const B=s(i,[["render",g],["__file","16.html.vue"]]);export{B as default}; diff --git a/assets/16.html-eRejMn1V.js b/assets/16.html-eRejMn1V.js new file mode 100644 index 000000000..7787fe282 --- /dev/null +++ b/assets/16.html-eRejMn1V.js @@ -0,0 +1 @@ +const e=JSON.parse(`{"key":"v-443b0d00","path":"/courses/user/16.html","title":"16. Next Steps","lang":"en-US","frontmatter":{"order":16,"title":"16. Next Steps","author":"Emily","headerDepth":3,"description":"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...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/user/16.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"16. Next Steps"}],["meta",{"property":"og:description","content":"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..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Emily"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"16. Next Steps\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Emily\\"}]}"]]},"headers":[{"level":2,"title":"16. Next Steps","slug":"_16-next-steps","link":"#_16-next-steps","children":[{"level":3,"title":"16.1 Take the Class Survey","slug":"_16-1-take-the-class-survey","link":"#_16-1-take-the-class-survey","children":[]},{"level":3,"title":"16.2 Take the Beginner Security Automation Developer Class","slug":"_16-2-take-the-beginner-security-automation-developer-class","link":"#_16-2-take-the-beginner-security-automation-developer-class","children":[]},{"level":3,"title":"16.3 Check Out the Rest of MITRE SAF(c)'s Content","slug":"_16-3-check-out-the-rest-of-mitre-saf-c-s-content","link":"#_16-3-check-out-the-rest-of-mitre-saf-c-s-content","children":[]},{"level":3,"title":"16.4 Contact Us","slug":"_16-4-contact-us","link":"#_16-4-contact-us","children":[]}]}],"git":{},"readingTime":{"minutes":0.9,"words":269},"filePathRelative":"courses/user/16.md","autoDesc":true}`);export{e as data}; diff --git a/assets/16.html-pDGZD3f7.js b/assets/16.html-pDGZD3f7.js new file mode 100644 index 000000000..ab11331c6 --- /dev/null +++ b/assets/16.html-pDGZD3f7.js @@ -0,0 +1 @@ +import{_ as r}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as s,o as i,c,d as e,e as t,b as o,w as h}from"./app-PAvzDPkc.js";const l={},u=e("h2",{id:"_16-next-steps",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#_16-next-steps","aria-hidden":"true"},"#"),t(" 16. Next Steps")],-1),d=e("h3",{id:"_16-1-take-the-class-survey",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#_16-1-take-the-class-survey","aria-hidden":"true"},"#"),t(" 16.1 Take the Class Survey")],-1),f={href:"https://forms.office.com/g/UxNr3nhtcm",target:"_blank",rel:"noopener noreferrer"},_=e("h3",{id:"_16-2-take-the-beginner-security-automation-developer-class",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#_16-2-take-the-beginner-security-automation-developer-class","aria-hidden":"true"},"#"),t(" 16.2 Take the Beginner Security Automation Developer Class")],-1),p=e("p",null,"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!",-1),m=e("h3",{id:"_16-3-check-out-the-rest-of-mitre-saf-c-s-content",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#_16-3-check-out-the-rest-of-mitre-saf-c-s-content","aria-hidden":"true"},"#"),t(" 16.3 Check Out the Rest of MITRE SAF(c)'s Content")],-1),g={href:"https://saf.mitre.org",target:"_blank",rel:"noopener noreferrer"},y=e("h3",{id:"_16-4-contact-us",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#_16-4-contact-us","aria-hidden":"true"},"#"),t(" 16.4 Contact Us")],-1),b=e("p",null,[t("The MITRE SAF(c) team can be contacted at "),e("a",{href:"mailto:saf@groups.mitre.org"},"saf@groups.mitre.org"),t(". 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.")],-1);function k(v,w){const n=s("ExternalLinkIcon"),a=s("RouterLink");return i(),c("div",null,[u,d,e("p",null,[t("Take our 9 question SAF User Class "),e("a",f,[t("survey"),o(n)]),t(" to give feedback to fuel class improvement.")]),_,p,m,e("p",null,[t("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 "),e("a",g,[t("saf.mitre.org"),o(n)]),t(". 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 "),o(a,{to:"/resources/"},{default:h(()=>[t("Resources Page")]),_:1})]),y,b])}const T=r(l,[["render",k],["__file","16.html.vue"]]);export{T as default}; diff --git a/assets/17.html-KmjmQR7T.js b/assets/17.html-KmjmQR7T.js new file mode 100644 index 000000000..4d2ab3023 --- /dev/null +++ b/assets/17.html-KmjmQR7T.js @@ -0,0 +1 @@ +import{_ as n}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as t,o as r,c as s,d as i,e,b as d,w as c,f as a}from"./app-PAvzDPkc.js";const l={},h=a('The converge stage uses Ansible Playbooks from the Ansible Lockdown project to apply hardening configurations, specifically the RHEL8-STIG playbook, and RedHat managed containers.
For EC2 and Vagrant, we use 'wrapper playbooks' for the 'vanilla' and 'hardened' suites.
requirements.txt, and Ansible Roles.Some tasks in the hardening role were disabled for automated testing, but this doesn't significantly impact our security posture. We can still meet our validation and thresholds.
For more on using these playbooks, running Ansible, or modifying the playbooks, roles, and tasks, see the Ansible Project Website.
',7),p=a('We use RedHat vendor images for both the vanilla and hardened containers.
vanilla: This container uses the registry.access.redhat.com/ubi8/ubi:8.9-1028 image from RedHat's community repositories.hardened: This container uses the registry1.dso.mil/ironbank/redhat/ubi/ubi8 image from Red Hat's Platform One Iron Bank project.The Iron Bank UBI8 image is regularly patched, updated, and hardened according to STIG requirements.
',4);function u(g,m){const o=t("RouterLink");return r(),s("div",null,[h,i("p",null,[e("Find these roles and 'wrapper playbooks' in the "),d(o,{to:"/courses/profile-dev-test/spec/"},{default:c(()=>[e("spec/")]),_:1}),e(" directory.")]),p])}const v=n(l,[["render",u],["__file","17.html.vue"]]);export{v as default}; diff --git a/assets/17.html-q1XWgL_N.js b/assets/17.html-q1XWgL_N.js new file mode 100644 index 000000000..6be9d81d7 --- /dev/null +++ b/assets/17.html-q1XWgL_N.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-97db247c","path":"/courses/profile-dev-test/17.html","title":"Test Kitchen - Converge","lang":"en-US","frontmatter":{"order":17,"next":"16.md","title":"Test Kitchen - Converge","author":"Aaron Lippold","index":true,"description":"The converge stage uses Ansible Playbooks from the Ansible Lockdown project to apply hardening configurations, specifically the RHEL8-STIG playbook, and RedHat managed container...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/profile-dev-test/17.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Test Kitchen - Converge"}],["meta",{"property":"og:description","content":"The converge stage uses Ansible Playbooks from the Ansible Lockdown project to apply hardening configurations, specifically the RHEL8-STIG playbook, and RedHat managed container..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Test Kitchen - Converge\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"EC2 and Vagrant Converge","slug":"ec2-and-vagrant-converge","link":"#ec2-and-vagrant-converge","children":[]},{"level":2,"title":"Container Converge","slug":"container-converge","link":"#container-converge","children":[]}],"git":{},"readingTime":{"minutes":0.7,"words":211},"filePathRelative":"courses/profile-dev-test/17.md","autoDesc":true}');export{e as data}; diff --git a/assets/18.html-6inXR1OS.js b/assets/18.html-6inXR1OS.js new file mode 100644 index 000000000..937203f9d --- /dev/null +++ b/assets/18.html-6inXR1OS.js @@ -0,0 +1 @@ +import{_ as e}from"./plugin-vue_export-helper-x3n3nnut.js";import{o as t,c as a,f as i}from"./app-PAvzDPkc.js";const o={},s=i('The verify stage uses the kitchen-inspec verifier from Test Kitchen to run the profile against the test targets.
For this stage, the profile receives a set of tailored input YAML files. These files adjust the testing for each target, ensuring accurate validation against the expected state and minimizing false results.
There are also specific threshold files for each target environment platform (EC2, container, and Vagrant) in both the vanilla and hardened suites.
The following sections provide a detailed breakdown of these files, their structure, and the workflow organization.
',5),r=[s];function n(c,d){return t(),a("div",null,r)}const f=e(o,[["render",n],["__file","18.html.vue"]]);export{f as default}; diff --git a/assets/18.html-tlb9_esG.js b/assets/18.html-tlb9_esG.js new file mode 100644 index 000000000..45bffb5ab --- /dev/null +++ b/assets/18.html-tlb9_esG.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-9471733e","path":"/courses/profile-dev-test/18.html","title":"Test Kitchen - Validate","lang":"en-US","frontmatter":{"order":18,"next":"19.md","title":"Test Kitchen - Validate","author":"Aaron Lippold","index":true,"description":"The verify stage uses the kitchen-inspec verifier from Test Kitchen to run the profile against the test targets. For this stage, the profile receives a set of tailored input YAM...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/profile-dev-test/18.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Test Kitchen - Validate"}],["meta",{"property":"og:description","content":"The verify stage uses the kitchen-inspec verifier from Test Kitchen to run the profile against the test targets. For this stage, the profile receives a set of tailored input YAM..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Test Kitchen - Validate\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[],"git":{},"readingTime":{"minutes":0.35,"words":106},"filePathRelative":"courses/profile-dev-test/18.md","autoDesc":true}');export{e as data}; diff --git a/assets/19.html-1B95xKZW.js b/assets/19.html-1B95xKZW.js new file mode 100644 index 000000000..6a186a22c --- /dev/null +++ b/assets/19.html-1B95xKZW.js @@ -0,0 +1 @@ +import{_ as e}from"./plugin-vue_export-helper-x3n3nnut.js";import{o as t,c as s,f as o}from"./app-PAvzDPkc.js";const n={},a=o('The destroy stage terminates the EC2 instances, Vagrant boxes, or containers that Test Kitchen created for testing.
Occasionally, the destroy stage may encounter issues if the hosting platforms have altered the state of the provisioned instance during your writing, testing, or debugging sessions. If you face any problems with the destroy stage or any other Test Kitchen commands, verify the following:
Sometimes, the solution can be as simple as checking if the instance is still active.
',5),i=[a];function r(c,h){return t(),s("div",null,i)}const g=e(n,[["render",r],["__file","19.html.vue"]]);export{g as default}; diff --git a/assets/19.html-2LyglPur.js b/assets/19.html-2LyglPur.js new file mode 100644 index 000000000..6f0abe2ee --- /dev/null +++ b/assets/19.html-2LyglPur.js @@ -0,0 +1 @@ +const t=JSON.parse('{"key":"v-9107c200","path":"/courses/profile-dev-test/19.html","title":"Test Kitchen - Destroy","lang":"en-US","frontmatter":{"order":19,"next":"20.md","title":"Test Kitchen - Destroy","author":"Aaron Lippold","description":"The destroy stage terminates the EC2 instances, Vagrant boxes, or containers that Test Kitchen created for testing. Occasionally, the destroy stage may encounter issues if the h...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/profile-dev-test/19.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Test Kitchen - Destroy"}],["meta",{"property":"og:description","content":"The destroy stage terminates the EC2 instances, Vagrant boxes, or containers that Test Kitchen created for testing. Occasionally, the destroy stage may encounter issues if the h..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Test Kitchen - Destroy\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[],"git":{},"readingTime":{"minutes":0.38,"words":113},"filePathRelative":"courses/profile-dev-test/19.md","autoDesc":true}');export{t as data}; diff --git a/assets/20.html-RbtoI_3n.js b/assets/20.html-RbtoI_3n.js new file mode 100644 index 000000000..834449b15 --- /dev/null +++ b/assets/20.html-RbtoI_3n.js @@ -0,0 +1 @@ +import{_ as n}from"./plugin-vue_export-helper-x3n3nnut.js";import{r,o as c,c as i,d as e,e as t,b as a}from"./app-PAvzDPkc.js";const s={},h=e("h1",{id:"the-kitchen-directory",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#the-kitchen-directory","aria-hidden":"true"},"#"),t(" The "),e("code",null,".kitchen/"),t(" Directory")],-1),l={href:"/.kitchen/",target:"_blank",rel:"noopener noreferrer"},d=e("code",null,".kitchen/",-1),_=e("a",{href:"#311-locating-test-target-login-details"},"Finding Your Test Target Login Details",-1),f=e("code",null,".kitchen/",-1);function u(k,m){const o=r("ExternalLinkIcon");return c(),i("div",null,[h,e("p",null,[t("The "),e("a",l,[d,a(o)]),t(" directory contains the state file for Test Kitchen, which is automatically generated when you first run Test Kitchen. Refer to the "),_,t(" section to see how you can use the "),f,t(" directory.")])])}const y=n(s,[["render",u],["__file","20.html.vue"]]);export{y as default}; diff --git a/assets/20.html-fvwmUOh6.js b/assets/20.html-fvwmUOh6.js new file mode 100644 index 000000000..a8c90713a --- /dev/null +++ b/assets/20.html-fvwmUOh6.js @@ -0,0 +1 @@ +const t=JSON.parse('{"key":"v-45f286ac","path":"/courses/profile-dev-test/20.html","title":"Test Kitchen - .kitchen/ directory","lang":"en-US","frontmatter":{"order":20,"next":"21.md","title":"Test Kitchen - .kitchen/ directory","author":"Aaron Lippold","description":"The .kitchen/ (/.kitchen/) directory contains the state file for Test Kitchen, which is automatically generated when you first run Test Kitchen. Refer to the Finding Your Test T...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/profile-dev-test/20.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Test Kitchen - .kitchen/ directory"}],["meta",{"property":"og:description","content":"The .kitchen/ (/.kitchen/) directory contains the state file for Test Kitchen, which is automatically generated when you first run Test Kitchen. Refer to the Finding Your Test T..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Test Kitchen - .kitchen/ directory\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[],"git":{},"readingTime":{"minutes":0.2,"words":61},"filePathRelative":"courses/profile-dev-test/20.md","autoDesc":true}');export{t as data}; diff --git a/assets/21.html-4DDoeaAC.js b/assets/21.html-4DDoeaAC.js new file mode 100644 index 000000000..6882fa3e8 --- /dev/null +++ b/assets/21.html-4DDoeaAC.js @@ -0,0 +1,49 @@ +import{_ as n}from"./plugin-vue_export-helper-x3n3nnut.js";import{o as s,c as e,f as a}from"./app-PAvzDPkc.js";const t={},i=a(`kitchen.yml FileThe kitchen.yml file is the primary configuration file for Test Kitchen. It outlines the shared configuration for all your testing environments, platforms, and the testing framework to be used.
Each of the subsequent kitchen files will inherit the shared settings from this file automatlly and merge them with the setting in the child kitchen file.
kitchen.yml file---
+verifier:
+ name: inspec
+ sudo: true
+ reporter:
+ - cli
+ - json:spec/results/%{platform}_%{suite}.json
+ inspec_tests:
+ - name: RedHat 8 STIG v1r12
+ path: .
+ input_files:
+ - kitchen.inputs.yml
+ <% if ENV['INSPEC_CONTROL'] %>
+ controls:
+ - "<%= ENV['INSPEC_CONTROL'] %>"
+ <% end %>
+ load_plugins: true
+
+suites:
+ - name: vanilla
+ provisioner:
+ playbook: spec/ansible/roles/ansible-role-rhel-vanilla.yml
+ - name: hardened
+ provisioner:
+ playbook: spec/ansible/roles/ansible-role-rhel-hardened.yml
+kitchen.yml file:verifier:
+ name: inspec
+ sudo: true
+ reporter:
+ - cli
+ - json:spec/results/%{platform}_%{suite}.json
+ inspec_tests:
+ - name: RedHat 8 STIG v1r12
+ path: .
+ input_files:
+ - kitchen.inputs.yml
+ <% if ENV['INSPEC_CONTROL'] %>
+ controls:
+ - "<%= ENV['INSPEC_CONTROL'] %>"
+ <% end %>
+ load_plugins: true
+This first section configures the verifier, which is the tool that checks if your system is in the desired state. Here, it's using InSpec.
sudo: true means that InSpec will run with sudo privileges.reporter specifies the formats in which the test results will be reported. Here, it's set to report in the command-line interface (cli) and in a JSON file (json:spec/results/%{platform}_%{suite}.json).inspec_tests specifies the InSpec profiles to run. Here, it's running the "RedHat 8 STIG v1r12" profile located in the current directory (path: .).input_files specifies files that contain input variables for the InSpec profile. Here, it's using the kitchen.inputs.yml file.controls section is dynamically set based on the INSPEC_CONTROL environment variable. If the variable is set, only the specified control will be run.load_plugins: true means that InSpec will load any available plugins.suites:
+ - name: vanilla
+ provisioner:
+ playbook: spec/ansible/roles/ansible-role-rhel-vanilla.yml
+ - name: hardened
+ provisioner:
+ playbook: spec/ansible/roles/ansible-role-rhel-hardened.yml
+This section defines the test suites. Each suite represents a different configuration to test.
name and a provisioner.provisioner section specifies the Ansible playbook to use for the suite. Here, it's using the ansible-role-rhel-vanilla.yml playbook for the "vanilla" suite and the ansible-role-rhel-hardened.yml playbook for the "hardened" suite.kitchen.ymlINSPEC_CONTROL: This variable allows you to specify a single control to run during the bundle exec kitchen verify phase. This is particularly useful for testing or debugging a specific requirement.The workflow of Test Kitchen involves the following steps:
kitchen.ec2.yml FileThe kitchen.ec2.yml file is instrumental in setting up our testing targets within the AWS environment. It outlines the configuration details for these targets, including their VPC assignments and the specific settings for each VPC.
This file leverages the AWS CLI and AWS Credentials configured as described in the previous Required Software section.
Alternatively, if you've set up AWS Environment Variables, the file will use those for AWS interactions.
kitchen.ec2.yml file---
+platforms:
+ - name: rhel-8
+
+driver:
+ name: ec2
+ metadata_options:
+ http_tokens: required
+ http_put_response_hop_limit: 1
+ instance_metadata_tags: enabled
+ instance_type: m5.large
+ associate_public_ip: true
+ interface: public
+ skip_cost_warning: true
+ privileged: true
+ tags:
+ CreatedBy: test-kitchen
+
+provisioner:
+ name: ansible_playbook
+ hosts: all
+ require_chef_for_busser: false
+ require_ruby_for_busser: false
+ ansible_binary_path: /usr/local/bin
+ require_pip3: true
+ ansible_verbose: true
+ roles_path: spec/ansible/roles
+ galaxy_ignore_certs: true
+ requirements_path: spec/ansible/roles/requirements.yml
+ ansible_extra_flags: <%= ENV['ANSIBLE_EXTRA_FLAGS'] %>
+
+lifecycle:
+ pre_converge:
+ - remote: |
+ echo "NOTICE - Installing needed packages"
+ sudo dnf -y clean all
+ sudo dnf -y install --nogpgcheck bc bind-utils redhat-lsb-core vim
+ echo "updating system packages"
+ sudo dnf -y update --nogpgcheck --nobest
+ sudo dnf -y distro-sync
+ echo "NOTICE - Updating the ec2-user to keep sudo working"
+ sudo chage -d $(( $( date +%s ) / 86400 )) ec2-user
+ echo "NOTICE - updating ec2-user sudo config"
+ sudo chmod 600 /etc/sudoers && sudo sed -i'' "/ec2-user/d" /etc/sudoers && sudo chmod 400 /etc/sudoers
+
+transport:
+ name: ssh
+ max_ssh_sessions: 2
+kitchen.ec2.yml fileplatforms:
+ - name: rhel-8
+This section defines the platforms on which your tests will run. In this case, it's Red Hat Enterprise Linux 8.
driver:
+ name: ec2
+ ...
+This section configures the driver, which is responsible for creating and managing the instances. Here, it's set to use Amazon EC2 instances. The various options configure the EC2 instances, such as instance type (m5.large), whether to associate a public IP address (associate_public_ip: true), and various metadata options.
provisioner:
+ name: ansible_playbook
+ ...
+This section configures the provisioner, which is the tool that brings your system to the desired state. Here, it's using Ansible playbooks. The various options configure how Ansible is run, such as the path to the Ansible binary (ansible_binary_path: /usr/local/bin), whether to require pip3 (require_pip3: true), and the path to the roles and requirements files.
lifecycle:
+ pre_converge:
+ - remote: |
+ ...
+This section defines lifecycle hooks, which are commands that run at certain points in the Test Kitchen run. Here, it's running a series of commands before the converge phase (i.e., before applying the infrastructure code). These commands install necessary packages, update system packages, and update the ec2-user configuration.
transport:
+ name: ssh
+ max_ssh_sessions: 2
+This section configures the transport, which is the method Test Kitchen uses to communicate with the instance. Here, it's using SSH and allowing a maximum of 2 SSH sessions.
The workflow of Test Kitchen involves the following steps:
pre_converge lifecycle hook.verifier section.driver section.The transport is used in all these steps to communicate with the instance.
This approach allows for the evaluation of existing containers, even those created by other workflows. It can be leveraged to build a generalized workflow for validating any container against our Benchmark requirements, providing a comprehensive assessment of its security posture.
kitchen.container.yml file---
+# see: https://kitchen.ci/docs/drivers/dokken/
+
+provisioner:
+ name: dummy
+
+driver:
+ name: dokken
+ pull_platform_image: false
+
+transport:
+ name: dokken
+
+platforms:
+ - name: ubi8
+
+suites:
+ - name: vanilla
+ driver:
+ image: <%= ENV['VANILLA_CONTAINER_IMAGE'] || "registry.access.redhat.com/ubi8/ubi:8.9-1028" %>
+ verifier:
+ input_files:
+ - container.vanilla.inputs.yml
+ - name: hardened
+ driver:
+ image: <%= ENV['HARDENED_CONTAINER_IMAGE'] || "registry1.dso.mil/ironbank/redhat/ubi/ubi8" %>
+ verifier:
+ input_files:
+ - container.hardened.inputs.yml
+ # creds_file: './creds.json'
+kitchen.container.yml file:provisioner:
+ name: dummy
+This section configures the provisioner, which is the tool that brings your system to the desired state. Here, it's using a dummy provisioner, which means no provisioning will be done.
driver:
+ name: dokken
+ pull_platform_image: false
+This section configures the driver, which is responsible for creating and managing the instances. Here, it's set to use the Dokken driver, which is designed for running tests in Docker containers. The pull_platform_image: false option means that it won't automatically pull the Docker image for the platform; it will use the image specified in the suite.
transport:
+ name: dokken
+This section configures the transport, which is the method Test Kitchen uses to communicate with the instance. Here, it's using the Dokken transport, which communicates with the Docker container.
platforms:
+ - name: ubi8
+This section defines the platforms on which your tests will run. In this case, it's UBI 8 (Red Hat's Universal Base Image 8).
suites:
+ - name: vanilla
+ driver:
+ image: <%= ENV['VANILLA_CONTAINER_IMAGE'] || "registry.access.redhat.com/ubi8/ubi:8.9-1028" %>
+ verifier:
+ input_files:
+ - container.vanilla.inputs.yml
+ - name: hardened
+ driver:
+ image: <%= ENV['HARDENED_CONTAINER_IMAGE'] || "registry1.dso.mil/ironbank/redhat/ubi/ubi8" %>
+ verifier:
+ input_files:
+ - container.hardened.inputs.yml
+This section defines the test suites. Each suite represents a different configuration to test.
name, a driver, and a verifier.driver section specifies the Docker image to use for the suite. It's dynamically set based on the VANILLA_CONTAINER_IMAGE or HARDENED_CONTAINER_IMAGE environment variable, with a default value if the variable is not set.verifier section specifies files that contain input variables for the InSpec profile.The workflow of Test Kitchen involves the following steps:
verifier section.driver section.The transport is used in all these steps to communicate with the container.
kitchen.container.ymlThe kitchen.container.yml file uses the following environment variables to select the containers used during its hardened and vanilla testing runs. You can test any container using these environment variables, even though standard defaults are set.
VANILLA_CONTAINER_IMAGE: This variable specifies the Docker container image considered 'not hardened'. registry.access.redhat.com/ubi8/ubi:8.9-1028HARDENED_CONTAINER_IMAGE: This variable specifies the Docker container image considered 'hardened'. registry1.dso.mil/ironbank/redhat/ubi/ubi8lint-profile.ymlThis action checks out the repository, installs Ruby and InSpec, then runs bundle exec inspec check . to validate the structure and syntax of the InSpec profile and its Ruby code.
verify-ec2.ymlThis action performs the following steps:
vanilla and hardened test suites.threshold.yml files for each test suite (hardened and vanilla).verify-container.ymlThis action performs similar steps to verify-ec2.yml, but with some differences:
verify-vagrant.yml.exampleThis action is similar to the verify-ec2 workflow, but instead of using a remote AWS EC2 instance in a VPC, it uses a local Vagrant virtual machine as the test target. The user can configure whether to upload the results to our Heimdall Demo server or not by modifing the Github Action.
Before running Delta, it's beneficial to format the profile to match the format Delta will use. This minimizes changes to only those necessary based on the guidance update. Follow these steps:
gem list cookstyle. Create a .rubocop.yml file with the provided example settings or modify these settings via the command line. Run cookstyle -a ./controls and any tests you have for your profile.AllCops:
+ Exclude:
+ - "libraries/**/*"
+
+Layout/LineLength:
+ Max: 1000
+ AllowURI: true
+ IgnoreCopDirectives: true
+
+Naming/FileName:
+ Enabled: false
+
+Metrics/BlockLength:
+ Max: 400
+
+Lint/ConstantDefinitionInBlock:
+ Enabled: false
+
+# Required for Profiles as it can introduce profile errors
+Style/NumericPredicate:
+ Enabled: false
+
+Style/WordArray:
+ Description: "Use %w or %W for an array of words. (https://rubystyle.guide#percent-w)"
+ Enabled: false
+
+Style/RedundantPercentQ:
+ Enabled: true
+
+Style/NestedParenthesizedCalls:
+ Enabled: false
+
+Style/TrailingCommaInHashLiteral:
+ Description: "https://docs.rubocop.org/rubocop/cops_style.html#styletrailingcommainhashliteral"
+ Enabled: true
+ EnforcedStyleForMultiline: no_comma
+
+Style/TrailingCommaInArrayLiteral:
+ Enabled: true
+ EnforcedStyleForMultiline: no_comma
+
+Style/BlockDelimiters:
+ Enabled: false
+
+Lint/AmbiguousBlockAssociation:
+ Enabled: false
+saf generate update_controls4delta to check and update the control IDs with the provided XCCDF guidance. This process checks if the new guidance changes the control numbers and updates them if necessary. This minimizes the Delta output content and improves the visualization of the modifications provided by the Delta process.
The SAF InSpec Delta workflow typically involves two phases, preformatting and delta.
Before starting, ensure you have the latest SAF-CLI, the InSpec Profile JSON file, and the updated guidance file.
saf generate update_controls4delta command. This prepares the profile for the Delta process.saf generate delta [arguments] to start the Delta process.For more information on these commands, refer to the following documentation:
',7),g={href:"https://saf-cli.mitre.org/#delta-supporting-options",target:"_blank",rel:"noopener noreferrer"},_={href:"https://saf-cli.mitre.org/#delta",target:"_blank",rel:"noopener noreferrer"},b=a('Delta focuses on specific modifications migrating the changes from the XCCDF Benchmark Rules to the Profiles controls, and updating the 'metadata' of each of thosin the control ID, title, default desc, check text, and fix text, between the XCCDF Benchmark Rules and the Profile Controls.
It also adjusts the tags and introduces a ref between the impact and tags.
Delta does not modify the Ruby/InSpec code within the control, leaving it intact. Instead, it updates the 'control metadata' using the information from the supplied XCCDF guidance document. This applies to 'matched controls' between the XCCDF Guidance Document and the InSpec profile.
Test Kitchen stores the current host details of your provisioned test targets in the .kitchen/ directory. Here, you'll find a yml file containing your target's hostname, ip address, host details, and login credentials, which could be an ssh pem key or another type of credential.
.kitchen
+├── .kitchen/hardened-container.yml
+├── .kitchen/hardened-rhel-8.pem
+├── .kitchen/hardened-rhel-8.yml
+├── .kitchen/logs
+├── .kitchen/vanilla-container.yml
+├── .kitchen/vanilla-rhel-8.pem
+├── .kitchen/vanilla-rhel-8.yml
+└── .kitchen/vanilla-ubi8.yml
+If your test target reboots or updates its network information, you don't need to execute bundle exec kitchen destroy. Instead, update the corresponding .kitchen/#{suite}-#{target}.yml file with the updated information. This will ensure that your kitchen login, kitchen validate, and other kitchen commands function correctly, as they'll be connecting to the correct location instead of using outdated data.
Since we're using the free-tier for our AWS testing resources instead of a dedicated host, your test targets might shut down or 'reboot in the background' if you stop interacting with them, halt them, put them in a stop state, or leave them overnight. To regain access, edit the .kitchen/#{suite}-#{target}.yml file. As mentioned above, there's no need to recreate your testing targets if you can simply point Test Kitchen to the correct IP address.
pry and pry-byebug for Debugging ControlsWhen developing InSpec controls, it's beneficial to use the kitchen-test suite, the INSPEC_CONTROL environment variable, and pry or pry-byebug. This combination allows you to quickly debug, update, and experiment with your fixes in the context of the InSpec code, without having to run the full test suite.
pry and pry-byebug are powerful tools for debugging Ruby code, including InSpec controls. Here's how you can use them:
require 'pry' or require 'pry-byebug' at the top of your control file.binding.pry at the point in your code where you want to start debugging.binding.pry line, and you can inspect variables, step through the code, and more.!Pro Tip!
binding.pry lines when you're done debugging or you won't have a good 'linting' down the road.inspec shellThe inspec shell command allows you to test your full control update on your test target directly. To do this, you'll need to retrieve the IP address and SSH PEM key for your target instance from the Test Kitchen .kitchen directory. For more details on this, refer to the Finding Your Test Target Login Details section.
Once you have your IP address and SSH PEM key (for AWS target instances), or the container ID (for Docker test instances), you can use the following commands:
bundle exec inspec shell -i #{pem-key} -t ssh://ec2-user@#{ipaddress} --sudobundle exec inspec shell -t docker://#{container-id}kitchen login for Easy Test Review and ModificationThe kitchen login command provides an easy way to review and modify your test target. This tool is particularly useful for introducing test cases, exploring corner cases, and validating both positive and negative test scenarios.
The Department of Defense (DOD) has continually updated its databases that track rules and Security Technical Implementation Guides (STIGs) that house those rules.
Initially, the system was known as the Vulnerability Management System (VMS).
In the STIGs, you might come across data elements that are remnants from these iterations. These include Group Title (gid or gtitle), Vulnerability ID (VulnID), Rule ID (rule_id), STIG ID (stig_id), and others.
A significant change was the shift from using STIG ID to Rule ID in many security scanning tools. This change occurred because the Vulnerability Management System used the STIG_ID as the primary index for the requirements in each Benchmark in VMS.
However, when DISA updated the Vendor STIG Processes and replaced the VMS, they decided to migrate the primary ID from the STIG ID to the Rule ID, tracking changes in the Rules as described above.
Examples of tools that still use either fully or in part the 'STIG ID' vs the 'Rule ID' as a primary index are: the DISA STIG Viewer, Nessus Audit Scans, and Open SCAP client.
While these elements might seem confusing, understanding their historical context is essential.
In our modern profiles, some data from the XCCDF Benchmarks still exist in the document but are not used or rendered in the modern InSpec Profiles. However, in some of the older profiles, you may see many of these data elements as tags in the profile. The intention was to ensure easy and lossless conversion between XCCDF Benchmark and HDF Profile.
It was later realized that since the structure of these data elements was 'static', they could be easily reintroduced when converting back to an XCCDF Benchmark. Therefore, rendering them in the profile was deemed unnecessary.
',12),r=[i];function o(d,c){return t(),n("div",null,r)}const u=e(s,[["render",o],["__file","28.html.vue"]]);export{u as default}; diff --git a/assets/28.html-_tB2aore.js b/assets/28.html-_tB2aore.js new file mode 100644 index 000000000..e1b41aa39 --- /dev/null +++ b/assets/28.html-_tB2aore.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-2aa4fcbc","path":"/courses/profile-dev-test/28.html","title":"Background & Definitions","lang":"en-US","frontmatter":{"order":28,"next":"29.md","title":"Background & Definitions","author":"Aaron Lippold","description":"Background Evolution of STIGs and Security Benchmarks The Department of Defense (DOD) has continually updated its databases that track rules and Security Technical Implementatio...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/profile-dev-test/28.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Background & Definitions"}],["meta",{"property":"og:description","content":"Background Evolution of STIGs and Security Benchmarks The Department of Defense (DOD) has continually updated its databases that track rules and Security Technical Implementatio..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Background & Definitions\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"Background","slug":"background","link":"#background","children":[{"level":3,"title":"Evolution of STIGs and Security Benchmarks","slug":"evolution-of-stigs-and-security-benchmarks","link":"#evolution-of-stigs-and-security-benchmarks","children":[]}]}],"git":{},"readingTime":{"minutes":1.02,"words":306},"filePathRelative":"courses/profile-dev-test/28.md","autoDesc":true}');export{e as data}; diff --git a/assets/29.html-9ri5Q3n2.js b/assets/29.html-9ri5Q3n2.js new file mode 100644 index 000000000..6f74d7e88 --- /dev/null +++ b/assets/29.html-9ri5Q3n2.js @@ -0,0 +1 @@ +import{_ as s}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as n,o as i,c as a,d as e,e as t,b as o,f as l}from"./app-PAvzDPkc.js";const c={},d=e("h1",{id:"terms-definitions",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#terms-definitions","aria-hidden":"true"},"#"),t(" Terms & Definitions")],-1),h=e("li",null,[e("strong",null,"Baseline"),t(": This refers to a set of relevant security controls, such as NIST 800-53 controls or Center for Internet Security Controls. These controls offer high-level security best practices, grouped into common areas of concern.")],-1),u=e("li",null,[e("strong",null,"Benchmark"),t(": This is a set of security controls tailored to a specific type of application or product. These controls are typically categorized into 'high', 'medium', and 'low' levels based on Confidentiality, Integrity, and Availability (C.I.A).")],-1),p={href:"https://public.cyber.mil/stigs/cci/",target:"_blank",rel:"noopener noreferrer"},m=l("v1.12.4 to v1.12.5.r in the string - ('SV-230221) and (r858734_rule)'. The first part remains unique within the major version of a Benchmark document, while the latter part of the string is updated each time the 'Rule' is updated 'release to release' of the Benchmark. For example: 'SV-230221r858734_rule'.You might have noticed that many InSpec resources have a "plural" version. For example, user has a users counterpart, and package has packages.
Plural resources examine platform objects in bulk.
For example,
Plural resources usually include functions to query the set of objects it represents by an attribute, like so:
describe users.where(uid: 0).entries do
+ it { should eq ['root'] }
+ its('uids') { should eq [1234] }
+ its('gids') { should eq [1234] }
+end
+This test queries all users to confirm that the only one with a uid of zero is the root user.
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.
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:
+inspec> etc_hosts.entries
+=>
+[#<struct ip_address="127.0.0.1", primary_name="localhost", all_host_names=["localhost", "localhost.localdomain", "localhost4", "localhost4.localdomain4"]>,
+ #<struct ip_address="::1", primary_name="localhost6", all_host_names=["localhost6", "localhost6.localdomain6"]>,
+ #<struct ip_address="127.0.0.1", primary_name="test1.org", all_host_names=["test1.org"]>,
+ #<struct ip_address="127.0.0.1", primary_name="test2.org", all_host_names=["test2.org"]>,
+ #<struct ip_address="127.0.0.1", primary_name="test3.org", all_host_names=["test3.org"]>,
+ #<struct ip_address="127.0.0.1", primary_name="test4.org", all_host_names=["test4.org"]>]
+
+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.
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.
inspec init profile filtertable-test
+libraries directory as filter.rb.Tips
You can also use inspec init resource <your-resource-name> to create the template for your resource. When following the prompts, you can choose "plural" to create the template for a plural resource.
require 'inspec/utils/filter'
+
+class Filtertable < Inspec.resource(1)
+
+ name "filtertable"
+ supports platform: "linux"
+
+ filter_table = FilterTable.create
+
+ filter_table.register_column(:name, field: :name)
+ filter_table.register_column(:grade, field: :grade)
+ filter_table.register_column(:toys, field: :toys)
+
+ filter_table.register_custom_matcher(:has_bike?) { |filter_table| filter_table.toys.flatten.include?('bike') }
+ filter_table.register_custom_matcher(:has_middle_schooler?) { |filter_table| filter_table.grade.uniq.any?{ |grade| grade >= 6} }
+
+ filter_table.register_custom_property(:bike_count) { |filter_table| filter_table.toys.flatten.include?('bike').count }
+ filter_table.register_custom_property(:middle_schooler_count) { |filter_table| filter_table.where{ grade >= 6 }.count }
+
+ filter_table.install_filter_methods_on_resource(self, :fetch_data)
+
+ def fetch_data
+ # This method should return an array of hashes - the raw data. We'll hardcode it here.
+ [
+ { name: "Sarah", grade: 7, toys: ['car','train','bike']},
+ { name: "John", grade: 4, toys: ['top','bike']},
+ { name: "Donny", grade: 5, toys: ['train','nintento']},
+ { name: "Susan", grade: 7, toys: ['car','gameboy','bike']},
+ ]
+ end
+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.
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.
inspec shell --depends /path/to/profile/root/
+FilterTables organize their data into columns. Your resource will declare a number of columns using the register_column method.
Once you declare the columns that you want in your FilterTable (name, grade, and toys in our example), you need to insert some data into them using the install_filter_methods_on_resource method. That method takes two args -- self and a data structure that is an array of hashes. The array of hashes will be matched up to the columns you defined using the hashes' keys. For our example we hard-coded this data structure, which is returned by the fetch_data method.
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.
has_bike?describe filtertable.where( name: "Donny" ) do
+ it { should have_bike }
+end
+
+Profile: inspec-shell
+Version: (not specified)
+
+ filtertable with name == "Donny"
+ × should have bike
+ expected #has_bike? to return true, got false
+
+Test Summary: 0 successful, 1 failure, 0 skipped
+describe filtertable.where( name: "Sarah" ) do
+ it { should have_bike }
+end
+
+Profile: inspec-shell
+Version: (not specified)
+
+ filtertable with name == "Sarah"
+ ✔ should have bike
+
+Test Summary: 1 successful, 0 failures, 0 skipped
+
+In the simplest examples, we filter the table down to a single student using where (more on where in a minute) and invoke a matcher that checks if that student has a bike in their list of toys. We can write matchers to have whatever logic we like. For example, while has_bike checks if all of the students in the table under test have a bike, while has_middle_schooler checks if any student in the table under test is in the 7th grade or higher.
has_middle_schooler?describe filtertable.where { name =~ /Sarah|John/ } do
+ it { should have_middle_schooler }
+end
+
+Profile: inspec-shell
+Version: (not specified)
+Target ID:
+
+ filtertable with name =~ /Sarah|John/
+ ✔ is expected to have middle schooler
+
+Test Summary: 1 successful, 0 failures, 0 skipped
+
+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.
bike_countdescribe filtertable do
+ its('bike_count') { should eq 3 }
+end
+
+Profile: inspec-shell
+Version: (not specified)
+Target ID:
+
+ filtertable
+ ✔ bike_count is expected to eq 3
+
+Test Summary: 1 successful, 0 failures, 0 skipped
+middle_schooler_countdescribe filtertable do
+ its('middle_schooler_count') { should eq 4 }
+end
+
+Profile: inspec-shell
+Version: (not specified)
+Target ID:
+
+ filtertable
+ × middle_schooler_count is expected to eq 4
+
+ expected: 4
+ got: 2
+
+ (compared using ==)
+
+
+Test Summary: 0 successful, 1 failure, 0 skipped
+
+To get a better feel for how FilterTable works, we suggest you add a few extra features to the sample given above.
Then write some tests to see how your new matchers and properties work.
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.
where methodYou 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.
where as a method with no block and passing hash params, with keys you know are in the raw data, it will fetch the raw data, then filter row-wise and return the resulting Table. describe things.where(color: 'red') do
+ its('count') { should cmp 2 }
+ end
+
+ # Regexes
+ describe things.where(color: /^re/) do
+ its('count') { should cmp 2 }
+ end
+
+ # It eventually falls out to '===' comparison
+ # Here, range membership 1..2
+ describe things.where(thing_id: (1..2)) do
+ its('count') { should cmp 2 }
+ end
+
+ # irregular rows are supported
+ # Only one row has the :tackiness key, with value 'very'.
+ describe things.where(tackiness: 'very') do
+ its('count') { should cmp 1 }
+ end
+
+where method with blocksYou 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.
+ # You can have any logic you want in the block
+ describe things.where { true } do
+ its('count') { should cmp 3 }
+ end
+
+ # You can access any fields you declared using \`register_column\`
+ describe things.where { thing_id > 2 } do
+ its('count') { should cmp 1 }
+ end
+where calls and Tables without re-fetching raw dataThe 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.
# This only calls fetch_data once
+ describe things.where(color: :red).where { thing_id > 2 } do
+ its('count') { should cmp 1 }
+ end
+Some other methods return a Table object, and they may be chained without a re-fetch as well.
entries methodThe 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.
Importantly, note that the return value of entries is not the resource, nor the Table - in other words, you cannot chain it. However, you can call entries on any Table.
If you call entries without chaining it after where, calling entries will trigger the call to the data fetching method.
+ # Access the entries array
+ describe things.entries do
+ # This is Array#count, not the resource's \`count\` method
+ its('count') { should cmp 3}
+ end
+
+ # Access the entries array after chaining off of where
+ describe things.where(color: :red).entries do
+ # This is Array#count, not the resource's or table's \`count\` method
+ its('count') { should cmp 2}
+ end
+
+ # You can access the struct elements as a method, as a hash keyed on symbol, or as a hash keyed on string
+ describe things.entries.first.color do
+ it { should cmp :red }
+ end
+ describe things.entries.first[:color] do
+ it { should cmp :red }
+ end
+ describe things.entries.first['color'] do
+ it { should cmp :red }
+ end
+exist? matcherThis register_custom_matcher call:
filter_table_config.register_custom_matcher(:exist?) { |filter_table| !filter_table.entries.empty? }
+causes a new method to be defined on both the resource class and the Table class. The body of the method is taken from the block that is provided. When the method it called, it will receive the FilterTable::Table instance as its first parameter. (It may also accept a second param, but that doesn't make sense for this method - see thing_ids).
As when you are implementing matchers on a singular resource, the only thing that distinguishes this as a matcher is the fact that it ends in ?.
# Bare call on the matcher (called as a method on the resource)
+ describe things do
+ it { should exist }
+ end
+
+ # Chained on where (called as a method on the Table)
+ describe things.where(color: :red) do
+ it { should exist }
+ end
+count propertyThis register_custom_property call:
filter_table_config.register_custom_property(:count) { |filter_table| filter_table.entries.count }
+causes a new method to be defined on both the resource class and the Table class. As with exists?, the body is taken from the block.
# Bare call on the property (called as a method on the resource)
+ describe things do
+ its('count') { should cmp 3 }
+ end
+
+ # Chained on where (called as a method on the Table)
+ describe things.where(color: :red) do
+ its('count') { should cmp 2 }
+ end
+raw_data methodUnlike 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.
tacky_things = things.where(color: :blue).raw_data.select { |row| row[:tackiness] }
+ tacky_things.map { |row| row[:thing_id] }.each do |thing_id|
+ # Use to audit a singular Thing
+ describe thing(thing_id) do
+ it { should_not be_paisley }
+ end
+ end
+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:
`,52),m={href:"https://github.com/inspec/inspec/blob/63a5fd26a6925b1570ee80e2953d259b58c3012e/lib/inspec/resources/firewalld.rb",target:"_blank",rel:"noopener noreferrer"},h={href:"https://github.com/inspec/inspec/blob/63a5fd26a6925b1570ee80e2953d259b58c3012e/lib/inspec/resources/users.rb",target:"_blank",rel:"noopener noreferrer"},b={href:"https://github.com/inspec/inspec/blob/63a5fd26a6925b1570ee80e2953d259b58c3012e/lib/inspec/resources/shadow.rb",target:"_blank",rel:"noopener noreferrer"};function v(g,y){const a=l("ExternalLinkIcon");return p(),i("div",null,[r,s("p",null,[n("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 "),s("a",u,[n("Firewalld resource"),e(a)]),n(" for an example of a resource that does this -- note the resource is ultimately invoking a shell command ("),d,n(") 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.")]),k,s("ul",null,[s("li",null,[s("a",m,[n("FirewallD"),e(a)])]),s("li",null,[s("a",h,[n("Users"),e(a)])]),s("li",null,[s("a",b,[n("Shadow"),e(a)])])])])}const _=o(c,[["render",v],["__file","Appendix A - Writing Plural Resources.html.vue"]]);export{_ as default}; diff --git a/assets/Appendix A - Writing Plural Resources.html-yPzso6d-.js b/assets/Appendix A - Writing Plural Resources.html-yPzso6d-.js new file mode 100644 index 000000000..c2cefdc02 --- /dev/null +++ b/assets/Appendix A - Writing Plural Resources.html-yPzso6d-.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-32f5f052","path":"/courses/advanced/Appendix%20A%20-%20Writing%20Plural%20Resources.html","title":"Appendix A - Writing Plural Resources","lang":"en-US","frontmatter":{"order":14,"title":"Appendix A - Writing Plural Resources","author":"Aaron Lippold","headerDepth":3,"description":"10. 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. Plural resou...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/advanced/Appendix%20A%20-%20Writing%20Plural%20Resources.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Appendix A - Writing Plural Resources"}],["meta",{"property":"og:description","content":"10. 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. Plural resou..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Appendix A - Writing Plural Resources\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":2,"title":"10. Plural Resources","slug":"_10-plural-resources","link":"#_10-plural-resources","children":[{"level":3,"title":"10.1. Using FilterTable to write a Plural Resource","slug":"_10-1-using-filtertable-to-write-a-plural-resource","link":"#_10-1-using-filtertable-to-write-a-plural-resource","children":[]},{"level":3,"title":"10.2. FilterTable Hands-On","slug":"_10-2-filtertable-hands-on","link":"#_10-2-filtertable-hands-on","children":[]},{"level":3,"title":"10.3. Predefined Methods for FilterTable","slug":"_10-3-predefined-methods-for-filtertable","link":"#_10-3-predefined-methods-for-filtertable","children":[]},{"level":3,"title":"10.4 FilterTable Examples","slug":"_10-4-filtertable-examples","link":"#_10-4-filtertable-examples","children":[]}]}],"git":{},"readingTime":{"minutes":7.71,"words":2312},"filePathRelative":"courses/advanced/Appendix A - Writing Plural Resources.md","autoDesc":true}');export{e as data}; diff --git a/assets/Appendix B - Resource Examples.html-NvdExdec.js b/assets/Appendix B - Resource Examples.html-NvdExdec.js new file mode 100644 index 000000000..637bb4dd3 --- /dev/null +++ b/assets/Appendix B - Resource Examples.html-NvdExdec.js @@ -0,0 +1,486 @@ +import{_ as p}from"./plugin-vue_export-helper-x3n3nnut.js";import{r as o,o as i,c as l,d as n,e as s,b as e,f as t}from"./app-PAvzDPkc.js";const c={},r=t(`As an example we will go through a few custom resources that were built and approved.
---
+title: About the ip6tables Resource
+platform: linux
+---
+
+# ip6tables
+
+Use the \`ip6tables\` Chef InSpec audit resource to test rules that are defined in \`ip6tables\`, which maintains tables of IP packet filtering rules for IPv6. There may be more than one table. Each table contains one (or more) chains (both built-in and custom). A chain is a list of rules that match packets. When the rule matches, the rule defines what target to assign to the packet.
+
+<br>
+
+## Availability
+
+### Installation
+
+This resource is distributed along with Chef InSpec itself. You can use it automatically.
+
+### Version
+
+This resource first became available in v4.6.9 of InSpec.
+
+## Syntax
+
+A \`ip6tables\` resource block declares tests for rules in IP tables:
+
+ describe ip6tables(rule:'name', table:'name', chain: 'name') do
+ it { should have_rule('RULE') }
+ end
+
+where
+
+* \`ip6tables()\` may specify any combination of \`rule\`, \`table\`, or \`chain\`
+* \`rule:'name'\` is the name of a rule that matches a set of packets
+* \`table:'name'\` is the packet matching table against which the test is run
+* \`chain: 'name'\` is the name of a user-defined chain or one of \`ACCEPT\`, \`DROP\`, \`QUEUE\`, or \`RETURN\`
+* \`have_rule('RULE')\` tests that rule in the ip6tables list. This must match the entire line taken from \`ip6tables -S CHAIN\`.
+
+<br>
+
+## Examples
+
+The following examples show how to use this Chef InSpec audit resource.
+
+### Test if the INPUT chain is in default ACCEPT mode
+
+ describe ip6tables do
+ it { should have_rule('-P INPUT ACCEPT') }
+ end
+
+### Test if the INPUT chain from the mangle table is in ACCEPT mode
+
+ describe ip6tables(table:'mangle', chain: 'INPUT') do
+ it { should have_rule('-P INPUT ACCEPT') }
+ end
+
+### Test if there is a rule allowing Postgres (5432/TCP) traffic
+
+ describe ip6tables do
+ it { should have_rule('-A INPUT -p tcp -m tcp -m multiport --dports 5432 -m comment --comment "postgres" -j ACCEPT') }
+ end
+
+Note that the rule specification must exactly match what's in the output of \`ip6tables -S INPUT\`, which will depend on how you've built your rules.
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### have_rule
+
+The \`have_rule\` matcher tests the named rule against the information in the \`ip6tables\` file:
+
+ it { should have_rule('RULE') }
+require "inspec/resources/iis_site"
+require "inspec/resources/inetd_conf"
+require "inspec/resources/interface"
+require "inspec/resources/ip6tables"
+require "inspec/resources/iptables"
+require "inspec/resources/kernel_module"
+require "inspec/resources/kernel_parameter"
+require "inspec/resources/command"
+
+# Usage:
+# describe ip6tables do
+# it { should have_rule('-P INPUT ACCEPT') }
+# end
+#
+# The following serverspec sytax is not implemented:
+# describe ip6tables do
+# it { should have_rule('-P INPUT ACCEPT').with_table('mangle').with_chain('INPUT') }
+# end
+# Please use the new sytax:
+# describe ip6tables(table:'mangle', chain: 'input') do
+# it { should have_rule('-P INPUT ACCEPT') }
+# end
+#
+# Note: Docker containers normally do not have ip6tables installed
+#
+# @see http://ipset.netfilter.org/ip6tables.man.html
+# @see http://ipset.netfilter.org/ip6tables.man.html
+module Inspec::Resources
+ class Ip6Tables < Inspec.resource(1)
+ name "ip6tables"
+ supports platform: "linux"
+ desc "Use the ip6tables InSpec audit resource to test rules that are defined in ip6tables, which maintains tables of IP packet filtering rules. There may be more than one table. Each table contains one (or more) chains (both built-in and custom). A chain is a list of rules that match packets. When the rule matches, the rule defines what target to assign to the packet."
+ example <<~EXAMPLE
+ describe ip6tables do
+ it { should have_rule('-P INPUT ACCEPT') }
+ end
+ EXAMPLE
+
+ def initialize(params = {})
+ @table = params[:table]
+ @chain = params[:chain]
+
+ # we're done if we are on linux
+ return if inspec.os.linux?
+
+ # ensures, all calls are aborted for non-supported os
+ @ip6tables_cache = []
+ skip_resource "The \`ip6tables\` resource is not supported on your OS yet."
+ end
+
+ def has_rule?(rule = nil, _table = nil, _chain = nil)
+ # checks if the rule is part of the ruleset
+ # for now, we expect an exact match
+ retrieve_rules.any? { |line| line.casecmp(rule) == 0 }
+ end
+
+ def retrieve_rules
+ return @ip6tables_cache if defined?(@ip6tables_cache)
+
+ # construct ip6tables command to read all rules
+ bin = find_ip6tables_or_error
+ table_cmd = "-t #{@table}" if @table
+ ip6tables_cmd = format("%s %s -S %s", bin, table_cmd, @chain).strip
+
+ cmd = inspec.command(ip6tables_cmd)
+ return [] if cmd.exit_status.to_i != 0
+
+ # split rules, returns array or rules
+ @ip6tables_cache = cmd.stdout.split("\\n").map(&:strip)
+ end
+
+ def to_s
+ format("Ip6tables %s %s", @table && "table: #{@table}", @chain && "chain: #{@chain}").strip
+ end
+
+ private
+
+ def find_ip6tables_or_error
+ %w{/usr/sbin/ip6tables /sbin/ip6tables ip6tables}.each do |cmd|
+ return cmd if inspec.command(cmd).exist?
+ end
+
+ raise Inspec::Exceptions::ResourceFailed, "Could not find \`ip6tables\`"
+ end
+ end
+end
+case os[:family]
+when 'ubuntu', 'fedora', 'debian', 'suse'
+ describe ip6tables do
+ it { should have_rule('-A INPUT -i eth0 -p tcp -m tcp --dport 80 -m state --state NEW -m comment --comment "http v6 on 80" -j ACCEPT') }
+ it { should_not have_rule('-A INPUT -i eth1 -p tcp -m tcp --dport 80 -j ACCEPT') }
+
+ # single-word comments have their quotes dropped
+ it { should have_rule('-A derby-cognos-web-v6 -p tcp -m tcp --dport 80 -m comment --comment derby-cognos-web-v6 -j ACCEPT') }
+ end
+when 'redhat', 'centos'
+ describe ip6tables do
+ it { should have_rule('-A INPUT -i eth0 -p tcp -m tcp --dport 80 -m state --state NEW -m comment --comment "http v6 on 80" -j ACCEPT') }
+ it { should_not have_rule('-A INPUT -i eth1 -p tcp -m tcp --dport 80 -j ACCEPT') }
+ end
+
+ describe ip6tables do
+ it { should have_rule('-A derby-cognos-web-v6 -p tcp -m tcp --dport 80 -m comment --comment "derby-cognos-web-v6" -j ACCEPT') }
+ end if os[:release] == 6
+
+ describe ip6tables do
+ it { should have_rule('-A derby-cognos-web-v6 -p tcp -m tcp --dport 80 -m comment --comment derby-cognos-web-v6 -j ACCEPT') }
+ end if os[:release] == 7
+end
+require "helper"
+require "inspec/resource"
+require "inspec/resources/ip6tables"
+
+describe "Inspec::Resources::Ip6tables" do
+
+ # ubuntu 14.04
+ it "verify ip6tables on ubuntu" do
+ resource = MockLoader.new(:ubuntu1404).load_resource("ip6tables")
+ _(resource.has_rule?("-P OUTPUT ACCEPT")).must_equal true
+ _(resource.has_rule?("-P OUTPUT DROP")).must_equal false
+ end
+
+ it "verify ip6tables with comments on ubuntu" do
+ resource = MockLoader.new(:ubuntu1404).load_resource("ip6tables")
+ _(resource.has_rule?('-A INPUT -i eth0 -p tcp -m tcp --dport 80 -m state --state NEW -m comment --comment "http-v6 like its 1990" -j ACCEPT')).must_equal true
+ end
+
+ it "verify ip6tables on windows" do
+ resource = MockLoader.new(:windows).load_resource("ip6tables")
+ _(resource.has_rule?("-P OUTPUT ACCEPT")).must_equal false
+ _(resource.has_rule?("-P OUTPUT DROP")).must_equal false
+ end
+
+ # undefined
+ it "verify ip6tables on unsupported os" do
+ resource = MockLoader.new(:undefined).load_resource("ip6tables")
+ _(resource.has_rule?("-P OUTPUT ACCEPT")).must_equal false
+ _(resource.has_rule?("-P OUTPUT DROP")).must_equal false
+ end
+
+end
+---
+title: The Nginx Resource
+---
+
+# nginx
+
+Use the \`nginx\` InSpec audit resource to test the fields and validity of nginx.
+
+Nginx resource extracts and exposes data reported by the command 'nginx -V'
+
+## Syntax
+
+An \`nginx\` InSpec audit resource block extracts configuration settings that should be tested:
+
+ describe nginx do
+ its('attribute') { should eq 'value' }
+ end
+
+ describe nginx('path to nginx') do
+ its('attribute') { should eq 'value' }
+ end
+
+where
+
+* \`'attribute'\` is a configuration parsed from result of the command 'nginx -V'
+* \`'value'\` is the value that is expected of the attribute
+
+## Supported Properties
+
+* 'compiler_info', 'error_log_path', 'http_client_body_temp_path', 'http_fastcgi_temp_path', 'http_log_path', 'http_proxy_temp_path', 'http_scgi_temp_path', 'http_uwsgi_temp_path', 'lock_path', 'modules', 'modules_path', 'openssl_version', 'prefix', 'sbin_path', 'service', 'support_info', 'version'
+
+## Property Examples and Return Types
+
+### version(String)
+
+\`version\` returns a string of the version of the running nginx instance
+
+ describe nginx do
+ its('version') { should eq '1.12.0' }
+ end
+
+### modules(String)
+
+\`modules\` returns a array modules in the running nginx instance
+
+ describe nginx do
+ its('modules') { should include 'my_module' }
+ end
+
+### openssl_version(Hash)
+
+\`openssl_version \` returns a hash with 'version' and 'date' as keys
+
+ describe nginx do
+ its('openssl_version.date') { should eq '11 Feb 2013' }
+ end
+
+### compiler_info(Hash)
+
+\`compiler_info \` returns a hash with 'compiler' , version' and 'date' as keys
+
+ describe nginx do
+ its('compiler_info.compiler') { should eq 'gcc' }
+ end
+
+### support_info(String)
+
+\`support_info \` returns a string containing supported protocols
+
+ describe nginx do
+ its('support_info') { should match /TLS/ }
+ end
+require 'resources/mysql'
+require 'resources/mysql_conf'
+require 'resources/mysql_session'
+require 'resources/nginx'
+require 'resources/nginx_conf'
+require 'resources/npm'
+require 'resources/ntp_conf'
+# encoding: utf-8
+# author: Aaron Lippold, lippold@gmail.com
+# author: Rony Xavier, rx294@gmail.com
+
+require 'pathname'
+require 'hashie/mash'
+
+module Inspec::Resources
+ class Nginx < Inspec.resource(1)
+ name 'nginx'
+ desc 'Use the nginx InSpec audit resource to test information about your NGINX instance.'
+ example "
+ describe nginx do
+ its('conf_path') { should cmp '/etc/nginx/nginx.conf' }
+ end
+ describe nginx('/etc/sbin/') do
+ its('version') { should be >= '1.0.0' }
+ end
+ describe nginx do
+ its('modules') { should include 'my_module' }
+ end
+ "
+ attr_reader :params, :bin_dir
+
+ def initialize(nginx_path = '/usr/sbin/nginx')
+ return skip_resource 'The \`nginx\` resource is not yet available on your OS.' if inspec.os.windows?
+ return skip_resource 'The \`nginx\` binary not found in the path provided.' unless inspec.command(nginx_path).exist?
+
+ cmd = inspec.command("#{nginx_path} -V 2>&1")
+ if !cmd.exit_status.zero?
+ return skip_resource 'Error using the command nginx -V'
+ end
+ @data = cmd.stdout
+ @params = {}
+ read_content
+ end
+
+ %w{compiler_info error_log_path http_client_body_temp_path http_fastcgi_temp_path http_log_path http_proxy_temp_path http_scgi_temp_path http_uwsgi_temp_path lock_path modules_path openssl_version prefix sbin_path service support_info version}.each do |property|
+ define_method(property.to_sym) do
+ @params[property.to_sym]
+ end
+ end
+
+ def openssl_version
+ result = @data.scan(/built with OpenSSL\\s(\\S+)\\s(\\d+\\s\\S+\\s\\d{4})/).flatten
+ Hashie::Mash.new({ 'version' => result[0], 'date' => result[1] })
+ end
+
+ def compiler_info
+ result = @data.scan(/built by (\\S+)\\s(\\S+)\\s(\\S+)/).flatten
+ Hashie::Mash.new({ 'compiler' => result[0], 'version' => result[1], 'date' => result[2] })
+ end
+
+ def support_info
+ support_info = @data.scan(/(.*\\S+) support enabled/).flatten
+ support_info.empty? ? nil : support_info.join(' ')
+ end
+
+ def modules
+ @data.scan(/--with-(\\S+)_module/).flatten
+ end
+
+ def to_s
+ 'Nginx Environment'
+ end
+
+ private
+
+ def read_content
+ parse_config
+ parse_path
+ parse_http_path
+ end
+
+ def parse_config
+ @params[:prefix] = @data.scan(/--prefix=(\\S+)\\s/).flatten.first
+ @params[:service] = 'nginx'
+ @params[:version] = @data.scan(%r{nginx version: nginx\\/(\\S+)\\s}).flatten.first
+ end
+
+ def parse_path
+ @params[:sbin_path] = @data.scan(/--sbin-path=(\\S+)\\s/).flatten.first
+ @params[:modules_path] = @data.scan(/--modules-path=(\\S+)\\s/).flatten.first
+ @params[:error_log_path] = @data.scan(/--error-log-path=(\\S+)\\s/).flatten.first
+ @params[:http_log_path] = @data.scan(/--http-log-path=(\\S+)\\s/).flatten.first
+ @params[:lock_path] = @data.scan(/--lock-path=(\\S+)\\s/).flatten.first
+ end
+
+ def parse_http_path
+ @params[:http_client_body_temp_path] = @data.scan(/--http-client-body-temp-path=(\\S+)\\s/).flatten.first
+ @params[:http_proxy_temp_path] = @data.scan(/--http-proxy-temp-path=(\\S+)\\s/).flatten.first
+ @params[:http_fastcgi_temp_path] = @data.scan(/--http-fastcgi-temp-path=(\\S+)\\s/).flatten.first
+ @params[:http_uwsgi_temp_path] = @data.scan(/--http-uwsgi-temp-path=(\\S+)\\s/).flatten.first
+ @params[:http_scgi_temp_path] = @data.scan(/--http-scgi-temp-path=(\\S+)\\s/).flatten.first
+ end
+ end
+end
+# encoding: utf-8
+# author: Aaron Lippold, lippold@gmail.com
+# author: Rony Xavier, rx294@nyu.edu
+
+require 'helper'
+require 'inspec/resource'
+
+describe 'Inspec::Resources::Nginx' do
+ describe 'NGINX Methods' do
+ it 'Verify nginx parsing \`support_info\` - \`TLS SNI\`' do
+ resource = load_resource('nginx')
+ _(resource.support_info).must_match 'TLS SNI'
+ end
+ it 'Verify nginx parsing \`openssl_version\` - \`1.0.1e-fips/11 Feb 2013\`' do
+ resource = load_resource('nginx')
+ _(resource.openssl_version.date).must_match '11 Feb 2013'
+ _(resource.openssl_version.version).must_match '1.0.1e-fips'
+ end
+ it 'Verify nginx parsing \`compiler_info\` - \`gcc 4.8.5 20150623 (Red Hat 4.8.5-4) (GCC)\`' do
+ resource = load_resource('nginx')
+ _(resource.compiler_info.compiler).must_match 'gcc'
+ _(resource.compiler_info.version).must_match '4.8.5'
+ _(resource.compiler_info.date).must_match '20150623'
+ end
+ it 'Verify nginx parsing \`version\` - 1.12.0' do
+ resource = load_resource('nginx')
+ _(resource.version).must_match '1.12.0'
+ end
+ it 'Verify nginx_module parsing with custom path\`version\` - 1.12.0' do
+ resource = load_resource('nginx','/usr/sbin/nginx')
+ _(resource.version).must_match '1.12.0'
+ end
+ it 'Verify nginx_module parsing with a broken custom path\`version\` - 1.12.0' do
+ resource = load_resource('nginx','/usr/sbin/nginx')
+ _(resource.version).must_match '1.12.0'
+ end
+ it 'Verify nginx parsing \`service\` - \`nginx\`' do
+ resource = load_resource('nginx')
+ _(resource.service).must_match 'nginx'
+ end
+ it 'Verify nginx parsing \`modules\` - \`nginx\`' do
+ resource = load_resource('nginx')
+ _(resource.modules).must_include 'http_addition'
+ end
+ it 'Verify nginx parsing \`prefix\` - \`/etc/nginx\`' do
+ resource = load_resource('nginx')
+ _(resource.prefix).must_match '/etc/nginx'
+ end
+ it 'Verify nginx parsing \`sbin_path\` - \`/usr/sbin/nginx\`' do
+ resource = load_resource('nginx')
+ _(resource.sbin_path).must_match '/usr/sbin/nginx'
+ end
+ it 'Verify nginx parsing \`modules_path\` - \`/usr/lib64/nginx/modules\`' do
+ resource = load_resource('nginx')
+ _(resource.modules_path).must_match '/usr/lib64/nginx/modules'
+ end
+ it 'Verify nginx parsing \`error_log_path\` - \`/var/log/nginx/error.log\`' do
+ resource = load_resource('nginx')
+ _(resource.error_log_path).must_match '/var/log/nginx/error.log'
+ end
+ it 'Verify nginx parsing \`error_log_path\` - \`/var/log/nginx/access.log\`' do
+ resource = load_resource('nginx')
+ _(resource.http_log_path).must_match '/var/log/nginx/access.log'
+ end
+ it 'Verify nginx parsing \`lock_path\` - \`/var/run/nginx.lock\`' do
+ resource = load_resource('nginx')
+ _(resource.lock_path).must_match '/var/run/nginx.lock'
+ end
+ it 'Verify nginx parsing \`http_client_body_temp_path\` - \`/var/cache/nginx/client_temp\`' do
+ resource = load_resource('nginx')
+ _(resource.http_client_body_temp_path).must_match '/var/cache/nginx/client_temp'
+ end
+ it 'Verify nginx parsing \`http_proxy_temp_path\` - \`/var/cache/nginx/proxy_temp\`' do
+ resource = load_resource('nginx')
+ _(resource.http_proxy_temp_path).must_match '/var/cache/nginx/proxy_temp'
+ end
+ it 'Verify nginx parsing \`http_fastcgi_temp_path\` - \`/var/cache/nginx/fastcgi_temp\`' do
+ resource = load_resource('nginx')
+ _(resource.http_fastcgi_temp_path).must_match '/var/cache/nginx/fastcgi_temp'
+ end
+ it 'Verify nginx parsing \`http_uwsgi_temp_path\` - \`/var/cache/nginx/uwsgi_temp\`' do
+ resource = load_resource('nginx')
+ _(resource.http_uwsgi_temp_path).must_match '/var/cache/nginx/uwsgi_temp'
+ end
+ it 'Verify nginx parsing \`http_scgi_temp_path\` - \`/var/cache/nginx/scgi_temp\`' do
+ resource = load_resource('nginx')
+ _(resource.http_scgi_temp_path).must_match '/var/cache/nginx/scgi_temp'
+ end
+ it 'Verify nginx parsing \`http_scgi_temp_path\` - \`/var/cache/nginx/scgi_temp\`' do
+ resource = load_resource('nginx')
+ _(resource.http_scgi_temp_path).must_match '/var/cache/nginx/scgi_temp'
+ end
+ end
+end
+InSpec's source code's top level directory looks like:
$ tree inspec -L 1 -d
+inspec
+├── contrib
+├── docs
+├── etc
+├── examples
+├── habitat
+├── inspec-bin
+├── kitchen
+├── lib
+├── omnibus
+├── support
+├── tasks
+├── test
+└── www
+
+13 directories
+The 3 key directories we need to focus on here are the docs/ directory, the lib/ directory and finally the test/ directory. When developing a resource for upstream InSpec, you must:
The resource contents
When creating this resource.rb file or in this scenario the file.rb, it would be developed and written the same exact way if you had put it in the libraries directory for a local resource. If you already developed the resource for local use, but want to push it to upstream, you can copy and paste the file directly to the following location:
$ tree -L 1 lib/inspec/resources/
+lib/inspec/resources/
+...
+├── file.rb
+...
+
+0 directories, 104 files
+This is the helper file you need to adjust for the file resource:
$ tree -L 1 lib/inspec/
+lib/inspec/
+...
+├── resources.rb
+...
+
+10 directories, 47 files
+The resource helper
When adding this line of code, be sure to place the resources in alphabetical order as shown in the example below.
In the resources.rb file you would add the following line:
require "inspec/resources/etc_hosts"
+require "inspec/resources/file"
+require "inspec/resources/filesystem"
+Next you would need to write out your unit and integration tests:
$ tree test/integration/default/controls/
+test/integration/default/controls/
+...
+├── file_spec.rb
+...
+
+0 directories, 42 files
+$ tree test/unit/resources/
+test/unit/resources/
+...
+├── file_test.rb
+...
+
+0 directories, 145 files
+$ tree docs/resources/
+docs/resources/
+...
+├── file.md.erb
+...
+
+0 directories, 156 files
+This pipeline is intended to validate that the RHEL7 InSpec profile itself functions correctly. We're not too concerned with whether out "hardened" box is actually hardened; we just want to know if InSpec is assessing it correctly.
Why Vanilla and Hardened?
Having two test suites, where one is hardened and one is not, can be useful for seeing the differences between how a profile behaves on different types of systems.
It also has the added bonus of simultaneously validating that whatever tool we use for hardening is working correctly.
Modularity in Automation
We will demonstrate the automation process through this example, but note that the different orchestration tools, configuration mangement tools, and targets can be traded out for different uses while following the same automation flow and security automation framework.
name: EC2 Testing Matrix
+
+on:
+ push:
+ branches: [ main ]
+ pull_request:
+ branches: [ main ]
+
+jobs:
+ my-job:
+ name: Validate my profile
+ runs-on: ubuntu-latest
+ env:
+ CHEF_LICENSE: accept-silent
+ KITCHEN_LOCAL_YAML: kitchen.ec2.yml
+ LC_ALL: "en_US.UTF-8"
+ strategy:
+ matrix:
+ suite: ['vanilla', 'hardened']
+ fail-fast: false
+ steps:
+ - name: add needed packages
+ run: sudo apt-get install -y jq
+ - name: Configure AWS credentials
+ env:
+ AWS_SG_ID: ${{ secrets.SAF_AWS_SG_ID }}
+ AWS_SUBNET_ID: ${{ secrets.SAF_AWS_SUBNET_ID }}
+ uses: aws-actions/configure-aws-credentials@v1
+ with:
+ aws-access-key-id: ${{ secrets.SAF_AWS_ACCESS_KEY_ID }}
+ aws-secret-access-key: ${{ secrets.SAF_AWS_SECRET_ACCESS_KEY }}
+ aws-region: us-east-1
+ - name: Check out repository
+ uses: actions/checkout@v2
+ - name: Clone full repository so we can push
+ run: git fetch --prune --unshallow
+ - name: Setup Ruby
+ uses: ruby/setup-ruby@v1
+ with:
+ ruby-version: '2.7'
+ - name: Disable ri and rdoc
+ run: 'echo "gem: --no-ri --no-rdoc" >> ~/.gemrc'
+ - run: bundle install
+ - name: Regenerate current \`profile.json\`
+ run: |
+ bundle exec inspec json . | jq . > profile.json
+ - name: Lint the Inspec profile
+ run: bundle exec inspec check .
+ - name: Run kitchen test
+ run: bundle exec kitchen test --destroy=always ${{ matrix.suite }}-rhel-7 || true
+ - name: Display our ${{ matrix.suite }} results summary
+ uses: mitre/saf_action@v1
+ with:
+ command_string: 'view summary -i spec/results/ec2_rhel-7_\${{ matrix.suite }}.json'
+ - name: Ensure the scan meets our ${{ matrix.suite }} results threshold
+ uses: mitre/saf_action@v1
+ with:
+ command_string: 'validate threshold -i spec/results/ec2_rhel-7_\${{ matrix.suite }}.json -F \${{ matrix.suite }}.threshold.yml'
+ - name: Save Test Result JSON
+ uses: actions/upload-artifact@v2
+ with:
+ path: spec/results/
+The two machines are then tested by running an InSpec profile. The results are viewed and validated against a threshold to allow the pipeline to automatically pass or fail based on whether the results meet those thresholds. The SAF CLI is used to view and validate.
`,6),b={class:"hint-container tip"},y=n("p",{class:"hint-container-title"},"Use Examples to Help Automate",-1),_={href:"https://github.com/mitre/redhat-enterprise-linux-7-stig-baseline/",target:"_blank",rel:"noopener noreferrer"},f={href:"https://github.com/mitre/redhat-enterprise-linux-7-stig-baseline/actions",target:"_blank",rel:"noopener noreferrer"},g=n("h3",{id:"_5-2-pipeline-example-with-manual-attestations",tabindex:"-1"},[n("a",{class:"header-anchor",href:"#_5-2-pipeline-example-with-manual-attestations","aria-hidden":"true"},"#"),s(" 5.2. Pipeline Example with Manual Attestations")],-1),w=n("p",null,"You could also add manual attestations with the SAF CLI to the pipeline to combine applicable manual attestations to the automated test results to determine a more full and accurate look at the overall security posture. SAF supports the validation of all controls including both automatable controls and manual attestation of those controls that cannot be automated. This expands the SAF’s coverage across interview, examination, and policy controls.",-1),x=n("p",null,"In a general sense we can use the SAF CLI to manage security data in the pipeline, supporting activities for managing POA&Ms.",-1),S=n("figure",null,[n("img",{src:k,alt:"The CI Pipeline - Attestation",tabindex:"0",loading:"lazy"}),n("figcaption",null,"The CI Pipeline - Attestation")],-1);function A(C,E){const e=t("ExternalLinkIcon"),p=t("RouterLink");return o(),l("div",null,[m,n("p",null,[s("Below is a "),n("a",v,[s("RedHat 7 example"),a(e)]),s(" of an automated pipeline that creates and configures two machines with the RedHat 7 operating system - one of which is set up as a vanilla configuration, and one of which is hardened using hardening scripts run by the Chef configuration management tool called kitchen.")]),h,n("div",b,[y,n("p",null,[s("To get more information on setting up the whole automation pipeline for your use case, use examples, such as the "),n("a",_,[s("RedHat 7 repository"),a(e)]),s(". You can view results of the workflows in the "),n("a",f,[s("Actions tab"),a(e)]),s(".")])]),g,w,x,n("p",null,[s("To practice doing manual attestations, take a look at the "),a(p,{to:"/courses/user/12.html"},{default:c(()=>[s("User Class")]),_:1}),s(".")]),S])}const L=i(d,[["render",A],["__file","Appendix D - Example Pipeline for Validating an InSpec Profile.html.vue"]]);export{L as default}; diff --git a/assets/Appendix D - Example Pipeline for Validating an InSpec Profile.html-osNKVVHI.js b/assets/Appendix D - Example Pipeline for Validating an InSpec Profile.html-osNKVVHI.js new file mode 100644 index 000000000..2a119c86b --- /dev/null +++ b/assets/Appendix D - Example Pipeline for Validating an InSpec Profile.html-osNKVVHI.js @@ -0,0 +1 @@ +const e=JSON.parse('{"key":"v-4faaa59d","path":"/courses/advanced/Appendix%20D%20-%20Example%20Pipeline%20for%20Validating%20an%20InSpec%20Profile.html","title":"Appendix D - Example Pipeline for Validating an InSpec Profile","lang":"en-US","frontmatter":{"order":17,"title":"Appendix D - Example Pipeline for Validating an InSpec Profile","author":"Aaron Lippold","headerDepth":3,"description":"RHEL7 Pipeline example Below is a RedHat 7 example (https://github.com/mitre/redhat-enterprise-linux-7-stig-baseline/blob/master/.github/workflows/verify-ec2.yml) of an automate...","head":[["meta",{"property":"og:url","content":"https://mitre.github.io/saf-training/saf-training/courses/advanced/Appendix%20D%20-%20Example%20Pipeline%20for%20Validating%20an%20InSpec%20Profile.html"}],["meta",{"property":"og:site_name","content":"MITRE SAF Training"}],["meta",{"property":"og:title","content":"Appendix D - Example Pipeline for Validating an InSpec Profile"}],["meta",{"property":"og:description","content":"RHEL7 Pipeline example Below is a RedHat 7 example (https://github.com/mitre/redhat-enterprise-linux-7-stig-baseline/blob/master/.github/workflows/verify-ec2.yml) of an automate..."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"en-US"}],["meta",{"property":"article:author","content":"Aaron Lippold"}],["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Appendix D - Example Pipeline for Validating an InSpec Profile\\",\\"image\\":[\\"\\"],\\"dateModified\\":null,\\"author\\":[{\\"@type\\":\\"Person\\",\\"name\\":\\"Aaron Lippold\\"}]}"]]},"headers":[{"level":3,"title":"RHEL7 Pipeline example","slug":"rhel7-pipeline-example","link":"#rhel7-pipeline-example","children":[]},{"level":3,"title":"5.2. Pipeline Example with Manual Attestations","slug":"_5-2-pipeline-example-with-manual-attestations","link":"#_5-2-pipeline-example-with-manual-attestations","children":[]}],"git":{},"readingTime":{"minutes":2.17,"words":651},"filePathRelative":"courses/advanced/Appendix D - Example Pipeline for Validating an InSpec Profile.md","autoDesc":true}');export{e as data}; diff --git a/assets/Appendix E - More Resource Examples.html-9JW9f5Xc.js b/assets/Appendix E - More Resource Examples.html-9JW9f5Xc.js new file mode 100644 index 000000000..45c68d84d --- /dev/null +++ b/assets/Appendix E - More Resource Examples.html-9JW9f5Xc.js @@ -0,0 +1,421 @@ +import{_ as s}from"./plugin-vue_export-helper-x3n3nnut.js";import{o as n,c as a,f as e}from"./app-PAvzDPkc.js";const t={},p=e(`# copyright: 2015, Vulcano Security GmbH
+
+require "shellwords"
+require "inspec/utils/parser"
+
+module Inspec::Resources
+ module FilePermissionsSelector
+ def select_file_perms_style(os)
+ if os.unix?
+ UnixFilePermissions.new(inspec)
+ elsif os.windows?
+ WindowsFilePermissions.new(inspec)
+ end
+ end
+ end
+
+ # TODO: rename file_resource.rb
+ class FileResource < Inspec.resource(1)
+ include FilePermissionsSelector
+ include LinuxMountParser
+
+ name "file"
+ supports platform: "unix"
+ supports platform: "windows"
+ desc "Use the file InSpec audit resource to test all system file types, including files, directories, symbolic links, named pipes, sockets, character devices, block devices, and doors."
+ example <<~EXAMPLE
+ describe file('path') do
+ it { should exist }
+ it { should be_file }
+ it { should be_readable }
+ it { should be_writable }
+ it { should be_executable.by_user('root') }
+ it { should be_owned_by 'root' }
+ its('mode') { should cmp '0644' }
+ end
+ EXAMPLE
+
+ attr_reader :file, :mount_options
+ def initialize(path)
+ # select permissions style
+ @perms_provider = select_file_perms_style(inspec.os)
+ @file = inspec.backend.file(path)
+ end
+
+ %w{
+ type exist? file? block_device? character_device? socket? directory?
+ symlink? pipe? mode mode? owner owned_by? group grouped_into?
+ link_path shallow_link_path linked_to? mtime size selinux_label immutable?
+ product_version file_version version? md5sum sha256sum
+ path basename source source_path uid gid
+ }.each do |m|
+ define_method m do |*args|
+ file.send(m, *args)
+ end
+ end
+
+ def content
+ res = file.content
+ return nil if res.nil?
+
+ res.force_encoding("utf-8")
+ end
+
+ def contain(*_)
+ raise "Contain is not supported. Please use standard RSpec matchers."
+ end
+
+ def readable?(by_usergroup, by_specific_user)
+ return false unless exist?
+ return skip_resource "\`readable?\` is not supported on your OS yet." if @perms_provider.nil?
+
+ file_permission_granted?("read", by_usergroup, by_specific_user)
+ end
+
+ def writable?(by_usergroup, by_specific_user)
+ return false unless exist?
+ return skip_resource "\`writable?\` is not supported on your OS yet." if @perms_provider.nil?
+
+ file_permission_granted?("write", by_usergroup, by_specific_user)
+ end
+
+ def executable?(by_usergroup, by_specific_user)
+ return false unless exist?
+ return skip_resource "\`executable?\` is not supported on your OS yet." if @perms_provider.nil?
+
+ file_permission_granted?("execute", by_usergroup, by_specific_user)
+ end
+
+ def allowed?(permission, opts = {})
+ return false unless exist?
+ return skip_resource "\`allowed?\` is not supported on your OS yet." if @perms_provider.nil?
+
+ file_permission_granted?(permission, opts[:by], opts[:by_user])
+ end
+
+ def mounted?(expected_options = nil, identical = false)
+ mounted = file.mounted
+
+ # return if no additional parameters have been provided
+ return file.mounted? if expected_options.nil?
+
+ # deprecation warning, this functionality will be removed in future version
+ Inspec.deprecate(:file_resource_be_mounted_matchers, "The file resource \`be_mounted.with\` and \`be_mounted.only_with\` matchers are deprecated. Please use the \`mount\` resource instead")
+
+ # we cannot read mount data on non-Linux systems
+ return nil unless inspec.os.linux?
+
+ # parse content if we are on linux
+ @mount_options ||= parse_mount_options(mounted.stdout, true)
+
+ if identical
+ # check if the options should be identical
+ @mount_options == expected_options
+ else
+ # otherwise compare the selected values
+ @mount_options.contains(expected_options)
+ end
+ end
+
+ def suid
+ (mode & 04000) > 0
+ end
+
+ alias setuid? suid
+
+ def sgid
+ (mode & 02000) > 0
+ end
+
+ alias setgid? sgid
+
+ def sticky
+ (mode & 01000) > 0
+ end
+
+ alias sticky? sticky
+
+ def more_permissive_than?(max_mode = nil)
+ raise Inspec::Exceptions::ResourceFailed, "The file" + file.path + "doesn't seem to exist" unless exist?
+ raise ArgumentError, "You must proivde a value for the \`maximum allowable permission\` for the file." if max_mode.nil?
+ raise ArgumentError, "You must proivde the \`maximum permission target\` as a \`String\`, you provided: " + max_mode.class.to_s unless max_mode.is_a?(String)
+ raise ArgumentError, "The value of the \`maximum permission target\` should be a valid file mode in 4-ditgit octal format: for example, \`0644\` or \`0777\`" unless /(0)?([0-7])([0-7])([0-7])/.match?(max_mode)
+
+ # Using the files mode and a few bit-wise calculations we can ensure a
+ # file is no more permisive than desired.
+ #
+ # 1. Calculate the inverse of the desired mode (e.g., 0644) by XOR it with
+ # 0777 (all 1s). We are interested in the bits that are currently 0 since
+ # it indicates that the actual mode is more permissive than the desired mode.
+ # Conversely, we dont care about the bits that are currently 1 because they
+ # cannot be any more permissive and we can safely ignore them.
+ #
+ # 2. Calculate the above result of ANDing the actual mode and the inverse
+ # mode. This will determine if any of the bits that would indicate a more
+ # permissive mode are set in the actual mode.
+ #
+ # 3. If the result is 0000, the files mode is equal
+ # to or less permissive than the desired mode (PASS). Otherwise, the files
+ # mode is more permissive than the desired mode (FAIL).
+
+ max_mode = max_mode.to_i(8)
+ inv_mode = 0777 ^ max_mode
+
+ inv_mode & file.mode != 0
+ end
+
+ def to_s
+ "File #{source_path}"
+ end
+
+ private
+
+ def file_permission_granted?(access_type, by_usergroup, by_specific_user)
+ raise "\`file_permission_granted?\` is not supported on your OS" if @perms_provider.nil?
+
+ if by_specific_user.nil? || by_specific_user.empty?
+ @perms_provider.check_file_permission_by_mask(file, access_type, by_usergroup, by_specific_user)
+ else
+ @perms_provider.check_file_permission_by_user(access_type, by_specific_user, source_path)
+ end
+ end
+ end
+
+ class FilePermissions
+ attr_reader :inspec
+ def initialize(inspec)
+ @inspec = inspec
+ end
+ end
+
+ class UnixFilePermissions < FilePermissions
+ def permission_flag(access_type)
+ case access_type
+ when "read"
+ "r"
+ when "write"
+ "w"
+ when "execute"
+ "x"
+ else
+ raise "Invalid access_type provided"
+ end
+ end
+
+ def usergroup_for(usergroup, specific_user)
+ if usergroup == "others"
+ "other"
+ elsif (usergroup.nil? || usergroup.empty?) && specific_user.nil?
+ "all"
+ else
+ usergroup
+ end
+ end
+
+ def check_file_permission_by_mask(file, access_type, usergroup, specific_user)
+ usergroup = usergroup_for(usergroup, specific_user)
+ flag = permission_flag(access_type)
+ mask = file.unix_mode_mask(usergroup, flag)
+ raise "Invalid usergroup/owner provided" if mask.nil?
+
+ (file.mode & mask) != 0
+ end
+
+ def check_file_permission_by_user(access_type, user, path)
+ flag = permission_flag(access_type)
+ if inspec.os.linux?
+ perm_cmd = "su -s /bin/sh -c \\"test -#{flag} #{path}\\" #{user}"
+ elsif inspec.os.bsd? || inspec.os.solaris?
+ perm_cmd = "sudo -u #{user} test -#{flag} #{path}"
+ elsif inspec.os.aix?
+ perm_cmd = "su #{user} -c test -#{flag} #{path}"
+ elsif inspec.os.hpux?
+ perm_cmd = "su #{user} -c \\"test -#{flag} #{path}\\""
+ else
+ return skip_resource "The \`file\` resource does not support \`by_user\` on your OS."
+ end
+
+ cmd = inspec.command(perm_cmd)
+ cmd.exit_status == 0 ? true : false
+ end
+ end
+
+ class WindowsFilePermissions < FilePermissions
+ def check_file_permission_by_mask(_file, _access_type, _usergroup, _specific_user)
+ raise "\`check_file_permission_by_mask\` is not supported on Windows"
+ end
+
+ def more_permissive_than?(*)
+ raise Inspec::Exceptions::ResourceSkipped, "The \`more_permissive_than?\` matcher is not supported on your OS yet."
+ end
+
+ def check_file_permission_by_user(access_type, user, path)
+ access_rule = translate_perm_names(access_type)
+ access_rule = convert_to_powershell_array(access_rule)
+
+ cmd = inspec.command("@(@((Get-Acl '#{path}').access | Where-Object {$_.AccessControlType -eq 'Allow' -and $_.IdentityReference -eq '#{user}' }) | Where-Object {($_.FileSystemRights.ToString().Split(',') | % {$_.trim()} | ? {#{access_rule} -contains $_}) -ne $null}) | measure | % { $_.Count }")
+ cmd.stdout.chomp == "0" ? false : true
+ end
+
+ private
+
+ def convert_to_powershell_array(arr)
+ if arr.empty?
+ "@()"
+ else
+ %{@('#{arr.join("', '")}')}
+ end
+ end
+
+ # Translates a developer-friendly string into a list of acceptable
+ # FileSystemRights that match it, because Windows has a fun heirarchy
+ # of permissions that are able to be noted in multiple ways.
+ #
+ # See also: https://www.codeproject.com/Reference/871338/AccessControl-FileSystemRights-Permissions-Table
+ def translate_perm_names(access_type)
+ names = translate_common_perms(access_type)
+ names ||= translate_granular_perms(access_type)
+ names ||= translate_uncommon_perms(access_type)
+ raise "Invalid access_type provided" unless names
+
+ names
+ end
+
+ def translate_common_perms(access_type)
+ case access_type
+ when "full-control"
+ %w{FullControl}
+ when "modify"
+ translate_perm_names("full-control") + %w{Modify}
+ when "read"
+ translate_perm_names("modify") + %w{ReadAndExecute Read}
+ when "write"
+ translate_perm_names("modify") + %w{Write}
+ when "execute"
+ translate_perm_names("modify") + %w{ReadAndExecute ExecuteFile Traverse}
+ when "delete"
+ translate_perm_names("modify") + %w{Delete}
+ end
+ end
+
+ def translate_uncommon_perms(access_type)
+ case access_type
+ when "delete-subdirectories-and-files"
+ translate_perm_names("full-control") + %w{DeleteSubdirectoriesAndFiles}
+ when "change-permissions"
+ translate_perm_names("full-control") + %w{ChangePermissions}
+ when "take-ownership"
+ translate_perm_names("full-control") + %w{TakeOwnership}
+ when "synchronize"
+ translate_perm_names("full-control") + %w{Synchronize}
+ end
+ end
+
+ def translate_granular_perms(access_type)
+ case access_type
+ when "write-data", "create-files"
+ translate_perm_names("write") + %w{WriteData CreateFiles}
+ when "append-data", "create-directories"
+ translate_perm_names("write") + %w{CreateDirectories AppendData}
+ when "write-extended-attributes"
+ translate_perm_names("write") + %w{WriteExtendedAttributes}
+ when "write-attributes"
+ translate_perm_names("write") + %w{WriteAttributes}
+ when "read-data", "list-directory"
+ translate_perm_names("read") + %w{ReadData ListDirectory}
+ when "read-attributes"
+ translate_perm_names("read") + %w{ReadAttributes}
+ when "read-extended-attributes"
+ translate_perm_names("read") + %w{ReadExtendedAttributes}
+ when "read-permissions"
+ translate_perm_names("read") + %w{ReadPermissions}
+ end
+ end
+ end
+end
+require "inspec/resources/file"
+
+module Inspec::Resources
+ class Directory < FileResource
+ name "directory"
+ supports platform: "unix"
+ supports platform: "windows"
+ desc "Use the directory InSpec audit resource to test if the file type is a directory. This is equivalent to using the file InSpec audit resource and the be_directory matcher, but provides a simpler and more direct way to test directories. All of the matchers available to file may be used with directory."
+ example <<~EXAMPLE
+ describe directory('path') do
+ it { should be_directory }
+ end
+ EXAMPLE
+
+ def exist?
+ file.exist? && file.directory?
+ end
+
+ def to_s
+ "Directory #{source_path}"
+ end
+ end
+end
+require "inspec/utils/parser"
+require "inspec/utils/file_reader"
+
+class EtcHosts < Inspec.resource(1)
+ name "etc_hosts"
+ supports platform: "linux"
+ supports platform: "bsd"
+ supports platform: "windows"
+ desc 'Use the etc_hosts InSpec audit resource to find an
+ ip_address and its associated hosts'
+ example <<~EXAMPLE
+ describe etc_hosts.where { ip_address == '127.0.0.1' } do
+ its('ip_address') { should cmp '127.0.0.1' }
+ its('primary_name') { should cmp 'localhost' }
+ its('all_host_names') { should eq [['localhost', 'localhost.localdomain', 'localhost4', 'localhost4.localdomain4']] }
+ end
+ EXAMPLE
+
+ attr_reader :params
+
+ include CommentParser
+ include FileReader
+
+ DEFAULT_UNIX_PATH = "/etc/hosts".freeze
+ DEFAULT_WINDOWS_PATH = 'C:\\windows\\system32\\drivers\\etc\\hosts'.freeze
+
+ def initialize(hosts_path = nil)
+ content = read_file_content(hosts_path || default_hosts_file_path)
+
+ @params = parse_conf(content.lines)
+ end
+
+ FilterTable.create
+ .register_column(:ip_address, field: "ip_address")
+ .register_column(:primary_name, field: "primary_name")
+ .register_column(:all_host_names, field: "all_host_names")
+ .install_filter_methods_on_resource(self, :params)
+
+ private
+
+ def default_hosts_file_path
+ inspec.os.windows? ? DEFAULT_WINDOWS_PATH : DEFAULT_UNIX_PATH
+ end
+
+ def parse_conf(lines)
+ lines.reject(&:empty?).reject(&comment?).map(&parse_data).map(&format_data)
+ end
+
+ def comment?
+ parse_options = { comment_char: "#", standalone_comments: false }
+
+ ->(data) { parse_comment_line(data, parse_options).first.empty? }
+ end
+
+ def parse_data
+ ->(data) { [data.split[0], data.split[1], data.split[1..-1]] }
+ end
+
+ def format_data
+ ->(data) { %w{ip_address primary_name all_host_names}.zip(data).to_h }
+ end
+end
+# RedHat, Ubuntu, and macOS
+$ curl https://omnitruck.chef.io/install.sh | sudo bash -s -- -P inspec
+Another option is to install InSpec via a command line:
When installing from source, gem dependencies may require ruby build tools to be installed.
For CentOS/RedHat/Fedora:$ yum -y install ruby ruby-devel make gcc gcc-c++
For Debian/Ubuntu:$ apt-get -y install ruby ruby-dev gcc g++ make
Now we’re on to the good stuff. Let’s install InSpec:
To install inspec from rubygems:$ gem install inspec
Install the following gems:
$ gem install bundler
+$ gem install test-kitchen
+Once InSpec is installed, run inspec version to verify that the installation was successful.
# RedHat, Ubuntu, and macOS
+$ curl https://omnitruck.chef.io/install.sh | sudo bash -s -- -P inspec
+Another option is to install InSpec via a command line:
Before I could install InSpec, I needed to have the latest version of Ruby installed. And before I could install the latest version of Ruby, I had to install Homebrew, the OS X package manager.
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+$ brew install rbenv ruby-build
+Add rbenv to bash so that it loads every time you open a terminal
$ echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.bash_profile
+$ source ~/.bash_profile
+
+$ rbenv install 2.7.2
+$ rbenv global 2.7.2
+Close terminal and reopen.
$ ruby -v
+Now we’re on to the good stuff. Let’s install InSpec:
$ gem install inspec
+Install the following gems:
$ gem install bundler
+$ gem install test-kitchen
+Once InSpec is installed, run inspec version to verify that the installation was successful.
Add Ruby executables to your PATH and Associate .rb and .rbw files with this Ruby installationenter. When this is complete close the command prompt$ ruby -v, then press enter $ gem install json --platform=ruby, then press enter # Windows (PowerShell)
+. { iwr -useb https://omnitruck.chef.io/install.ps1 } | iex; install -project inspec
+$ gem install inspec, then press enter$ gem install bundler, then press enter$ gem install test-kitchen, then press enterOnce InSpec is installed, run $ inspec version to verify that the installation was successful.
In the beginner class, we explained the structure and output of InSpec Profiles. Let's review some content, then practice by revisiting, running, and viewing results of an InSpec profile.
Remember that a profile is a set of automated tests that usually relates directly back to a Security Requirements Benchmark.
Profiles have two (2) required elements:
inspec.yml filecontrols directoryand optional elements such as:
libraries directoryfiles directoryinputs.yml fileREADME.md fileInSpec can create the profile structure for you using the following command:
$ inspec init profile my_inspec_profile
+This will give you the required files along with some optional files.
$ tree my_inspec_profile
+
+ my_inspec_profile
+ ├── README.md
+ ├── controls
+ │ └── example.rb
+ └── inspec.yml
+Let's take a look at the default ruby file in the controls directory.
title 'sample section'
+
+# you can also use plain tests
+describe file('/tmp') do
+ it { should be_directory }
+end
+
+# you add controls here
+control 'tmp-1.0' do # A unique ID for this control
+ impact 0.7 # The criticality, if this control fails.
+ title 'Create /tmp directory' # A human-readable title
+ desc 'An optional description...'
+ describe file('/tmp') do # The actual test
+ it { should be_directory }
+ end
+end
+This example shows two tests. Both tests check for the existence of the /tmp directory. The second test provides additional information about the test. Let's break down each component.
control (line 9) is followed by the control's name. Each control in a profile has a unique name.impact (line 10) measures the relative importance of the test and must be a value between 0.0 and 1.0.title (line 11) defines the control's purpose.desc (line 12) provides a more complete description of what the control checks for.describe (lines 13 — 15) defines the test. Here, the test checks for the existence of the /tmp directory.As with many test frameworks, InSpec code resembles natural language. Here's the format of a describe block.
describe < entity > do
+ it { < expectation > }
+end
+Resources And Matchers
InSpec uses resources like the file resource to aid in control development. These resources can often be used as the < entity > in the describe block. Find a list of resources in the InSpec documentation
InSpec uses matchers like the cmp or eq to aid in control development. These matchers can often be used as the < expectation > in the describe block where the expectation is checking a requirement of that entity. Find a list of matchers in the InSpec documentation
Let's take a look at the default inspec.yml.
name: my_inspec_profile
+title: InSpec Profile
+maintainer: The Authors
+copyright: The Authors
+copyright_email: you@example.com
+license: Apache-2.0
+summary: An InSpec Compliance Profile
+version: 0.1.0
+supports:
+ platform: os
+
+# Optional sections
+
+depends:
+ - name: < name of the profile from which you can include controls >
+ path: < relative path to that profile >
+
+gem_dependencies:
+ - name: < name of the gem >
+ version: < version of the gem >
+
+inputs:
+ - name: < name of the input >
+ desc: < description of the input >
+ type: < data type of the input (String, Array, Numeric, Hash) >
+ value: < default value for the input >
+This example shows default metadata of the InSpec profile along with the optional sections. Find more information about inputs and overlays in the beginner class.
Tips
version (line 8) is the version of that inspec profile. The best practice is for the version to be bumped after making changes to the profile to pull the latest updates.
| inspec.yml | inputs.yml |
|---|---|
| Required | Optional |
| Should not be renamed | Can be renamed |
| Needs to be at the root of the profile | Can be anywhere |
Automatically used during executioninspec exec profile1 | Needs to be passed in during executioninspec exec profile1 --input-file <path> |
| Purpose is to define default input values and profile metadata | Purpose is to override default input values with parameters for the local environments |
| Defined by the author of the profile | Defined by the user of the profile |
- name: superusers
+ desc: 'List of users with admin privileges'
+ type: Array
+ value:
+ - 'admin'
+ - 'root'
+superusers:
+ - 'codespaces'
+ - 'kali'
+