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. This is not always what we want to have happen. Be sure that all of your generated reports have unique names!

Additional Reporter Examples for Reference

Output JSON to screen

Command

inspec exec my_nginx --reporter json

Alternative Command

inspec exec my_nginx --reporter json:-

Output YAML to screen

Command

inspec exec my_nginx --reporter yaml

Alternative Command

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 --enhanced-outcomes