8. Generating InSpec Results
Generating InSpec Results
Try it out!
InSpec allows you to send your test results to one or more reporters, or output formats. The following command outputs results to both the terminal (cli
) and to a JSON report file (json:baseline_output.json
).
inspec exec my_nginx -t docker://nginx --reporter cli json:baseline_output.json
Generating good report filenames in practice
When using InSpec in practice, most users aggregate report files from multiple systems over time, so we recommend that you generate reports that specify:
- the target they were run against
- a timestamp
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.
Additional Reporter Examples for Reference
Output JSON to screen
inspec exec my_nginx --reporter json
inspec exec my_nginx --reporter json:-
Output YAML to screen
inspec exec my_nginx --reporter yaml
inspec exec my_nginx --reporter yaml:-
Output to screen and to a JSON file
inspec exec my_nginx --reporter cli json:tmp/output.json
Output only to files - a junit and HTML file
inspec exec my_nginx --reporter junit2:tmp/junit.xml html:www/index.html
Output JSON to the terminal and make a junit file
inspec exec my_nginx --reporter json junit2:tmp/junit.xml | tee out.json
Using a configuration file instead of the --reporter flag
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
}
}
}
You can read more about this at https://docs.chef.io/inspec/config/
Supported Reporters
The following are supported reporters:
- cli
- json
- json-min
- yaml
- documentation
- junit2
- progress
- progress-bar
- json-rspec
- html2
- automate
- json-automate
You can read more here: https://www.inspec.io/docs/reference/reporters/
Enhanced Outcomes
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)
.
Running Profiles from Network Locations
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
Pulling Profiles from the Network
We suggest that, when possible, you host your profile code on a version control system accessible from the internet (e.g. GitHub). That way, you are always running an up-to-date version of the code.
Note that "an up-to-date version" does not necessarily mean "run the main
branch of the profile as it exists on GitHub." You can make use of releases in your code repository, and then use the link to a stable release (GitHub example) as your input to inspec exec
. This conforms to best practices in automation -- avoid running any code that has not been thoroughly vetted as part of an offical release.
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
See the exec command docs for details.
Practice Running InSpec Using a Profile From GitHub
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