8. Running InSpec (NGINX Example)

8.1 Example Running an InSpec Profile Directly from GitHub

In this module, we use NGINX for learning purposes. If you're interested in NGINX specifically, you may be interested in the MITRE nginx-stigready-baseline profile on GitHub.

Alternative Profiles

Alternatively, you may also check out the DevSec Nginx Baseline profile on Chef Supermarket.

To execute the Chef Supermarket profile on your target system, run this inspec supermarket exec command.

Sometimes, there are multiple profiles available for the same software component. This could be because different people or teams wrote automation content, or because one profile is based on one set of guidance (such as a DISA STIG) and another profile is based on different guidance (such as a CIS Benchmark).

If you see multiple profiles available and are unsure which to use, read the READMEs in each to see what guidance they are based on to understand what is most useful for your situation. You can also run multiple profiles and compare the results to see which is more informative for your assessment. Lastly, you can always reach out to saf@groups.mitre.org if you have more questions.

8.2 Forming the InSpec Command

• Since we are using the profile from GitHub, we will use the GitHub link https://github.com/mitre/nginx-stigready-baseline to specify the profile.
• Because we are using a Docker container that is running in our lab environment, we can specify the target as -t docker://nginx.
• We can choose to output the results to the command line and to a file like this: --reporter cli json:./results/nginx_vanilla_results.json
• We can add the inputs file that we created so the profile is tailored to our environment like this: --input-file inputs.yml

To execute this command to run the GitHub profile on your target system, run this inspec exec command:

inspec exec https://github.com/mitre/nginx-stigready-baseline -t docker://nginx --input-file inputs.yml --reporter cli json:./results/nginx_vanilla_results.json

8.3 Run the Command

Enter the command from the previous step in your terminal and press enter. It will take a moment to start running.

8.3.1 CLI (Command Line) Results

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 than or equal to the organization approved version v1.23.1 is expected to cmp >= "1.23.1"
  ✔  V-56035: The NGINX web server must display a default hosted application web page, not
    a directory listing, when a requested web page cannot be found.
     ✔  The root directory /usr/share/nginx/html should include the default index.html file.
  ↺  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.

8.3.2 Results saved to a file

You should also see your results in a JSON file located in /results folder with the name that you specified in the command, for example nginx_vanilla_results.json. If you are using the lab environment GitHub codespaces, you should see it on the left of your screen under files. Right-click that file and click "Download" so that you have this file locally for the next steps.

More on --reporter Options

Different --reporter Options

InSpec allows you to output your test results to one or more reporters. You can configure the reporter(s) using either the --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 my_nginx -t ssh://TARGET_USERNAME:TARGET_PASSWORD@TARGET_IP --reporter cli json:baseline_output.json

Syntax

You can specify one or more reporters using the --reporter CLI flag. You can also specify an output by appending a path separated by a colon.

Output JSON to screen.

inspec exec my_nginx --reporter json
or
inspec exec my_nginx --reporter json:-

Output YAML to screen

inspec exec my_nginx --reporter yaml
or
inspec exec my_nginx --reporter yaml:-

Output CLI to screen and write JSON to a file.

inspec exec my_nginx --reporter cli json:/tmp/output.json

Output nothing to screen and write JUnit and HTML to a file.

inspec exec 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 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
    }
  }
}

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 on the documentation page.