4. How to Get Started - InSpec Commands & Docs

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

Use the InSpec executable with the command inspec exec to run a profile against a system. The generic command is below, but take a look at our breakdown on How To Run InSpec for the MITRE SAF User course for more information.

inspec exec WHERE_IS_THE_PROFILE -t WHAT_IS_THE_TARGET --more-flags EXTRA_STUFF --reporter WHAT_SHOULD_INSPEC_DO_WITH_THE_RESULTS

Want to try it out?

You can run a sample InSpec command against the nginx target running in the development lab environment using your my_nginx profile. Remember, this profile only has one sample control right now.

Run InSpec

inspec exec my_nginx -t docker://nginx --reporter cli

Expected Output

Profile:   InSpec Profile (my_nginx)
Version:   0.1.0
Target:    docker://31e4ea1be052a9bcc137003e77cbc7f0a4a3149576a2ce65354092424b0d3a89
Target ID: 761efa53-ee0a-5ea0-a459-b2a5d287b531

  ✔  tmp-1.0: Create /tmp directory
     ✔  File /tmp is expected to be directory

  File /tmp
     ✔  is expected to be directory

Profile Summary: 1 successful control, 0 control failures, 0 controls skipped
Test Summary: 2 successful, 0 failures, 0 skipped

How to Write InSpec

The inspec exec command is used to run or execute InSpec profiles. Now, let's talk about InSpec's existing documentation and features to support writing those InSpec profiles.

Good InSpec tests will use resources, many of which are already built in, to easily describe some part of the system. Remember the file resource as an example from the previous section. Additionally, tests should use matchers to implement the logic check of an expected result. The previous example used be_directory as a matcher. There are a number of built-in matchers: be_in, be_readable, cmp, include, to list a few.

Make Writing InSpec Easier with Built-in Resources

InSpec features dozens of resources and matchers that come predefined in the language. These resources are a core benefit to using InSpec because they allow you to leverage existing stable code to write simple and consistent tests.

When writing profiles, refer back to the documentation for resources. They often give you an example of how to write a test that matches your current problem.

Finding Documentation

• Explore the InSpec documentation to see which resources and matchers are available, including descriptions of their attributes and examples of their use.
• Examine the source code to see what's available. For example, you can see how file and other InSpec resources are implemented.
• Reference examples, such as profiles provided on Chef Supermarket, as a guide.
• Explore InSpec interactively using the InSpec shell.

The InSpec shell

The InSpec shell enables you to explore InSpec interactively. In this part, you'll use the InSpec shell to discover which resources can be used to test your NGINX configuration.

You are not required to use the InSpec shell to develop your profiles, but some users (including this course's instructors) find the InSpec shell to be a useful way to get immediate feedback and explore what's available. You can also use the InSpec shell to debug your tests; the shell lets you write and execute describe blocks in-line.

What is the InSpec Shell?

InSpec shell is based on a tool called pry. pry is an interactive debugging environment for Ruby.

Entering the InSpec shell

Run inspec shell to enter the interactive session.

InSpec Shell Command

inspec shell

Output - Enter the InSpec Shell

Welcome to the interactive InSpec Shell
To find out how to use it, type: help

You are currently running on:

    Name:      ubuntu
    Families:  debian, linux, unix, os
    Release:   20.04
    Arch:      x86_64

Run help to see what commands are available.

Command - help

help

Output - help

inspec> help
You are currently running on:

    Name:      ubuntu
    Families:  debian, linux, unix, os
    Release:   20.04
    Arch:      x86_64

Available commands:

    `[resource]` - run resource on target machine
    `help resources` - show all available resources that can be used as commands
    `help [resource]` - information about a specific resource
    `help matchers` - show information about common matchers
    `exit` - exit the InSpec shell

You can use resources in this environment to test the target machine. For example:

    command('uname -a').stdout
    file('/proc/cpuinfo').content => "value"

Run help resources to see which resources are available.

Command

help resources

Output

inspec> help resources

         - aide_conf
         - apache
         - apache_conf
         - apt
         - audit_policy
         - auditd
         - auditd_conf
         ...
         - file
         ...
        - xml
        - yaml
        - yum
        - zfs_dataset
        - zfs_pool

You see file and other resources listed.

Using the InSpec Shell

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.

Command - describe block

describe file('/tmp') do
  it { should be_directory }
end

Output - describe block

inspec> describe file('/tmp') do
inspec>   it { should be_directory }  
inspec> end  

Profile:   inspec-shell
Version:   (not specified)
Target ID: 

  File /tmp
     ✔  is expected to be directory

Test Summary: 1 successful, 0 failures, 0 skipped

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.

Exploring Resources

file example

You can also use the InSpec shell to explore resources, in addition to referencing the resource documentation. Here, we can use the InSpec shell to see how the file resource functions.
Run this command to list which methods are available to the file resource.

Command - file resource

file('/tmp').class.superclass.instance_methods(false).sort

Output - file resource

inspec> file('/tmp').class.superclass.instance_methods(false).sort

        => [:allowed?,
         :basename,
         :block_device?,
         :character_device?,
         :contain,
         :content,
         :directory?,
         ...
         :sticky,
         :sticky?,
         :suid,
         :symlink?,
         :to_s,
         :type,
         :uid,
         :version?,
         :writable?]

You can use the arrow or Page Up and Page Down keys to scroll through the list. When you're done, press Q.

Exploring Resources in the InSpec Shell

Let'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.

Using Ruby Predicate Methods

Given what we have just learned, the best practice in InSpec is to return something that evaluates to true or false.
The ? (or be_ in InSpec) makes your method a Ruby Predicate Method. See Ruby predicate methods to learn more.

nginx example

Now'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.
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.

In 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.

Command - resources

help resources

Output - resources

inspec> help resources

         - aide_conf
         - apache
         - apache_conf
         - apt
         ...
         - nginx
         - nginx_conf
         ...
         - xml
         - yaml
         - yum
         - yumrepo
         - zfs_dataset
         - zfs_pool

Run nginx.methods. This will list all of the available methods for the nginx resource. You can see the version and modules methods. These will be useful to us in the next section.

Command - nginx methods

nginx.methods

Output - nginx methods

=> [:params,
 :bin_dir,
 :prefix,
 :openssl_version,
 :compiler_info,
 :support_info,
 ...
 :http_scgi_temp_path,
 :version,
 :resource_id,
 :to_s,
 :service,
 ...
  :equal?,
 :__id__,
 :instance_eval,
 :instance_exec]

Run nginx.version to see what result you get.

Expected Error Ahead

Recall that you're working on your workstation environment, which does not have NGINX installed.

Command - nginx version

nginx.version

Output - nginx version

inspec> nginx.version
NoMethodError: undefined method `[]' for nil:NilClass
from /opt/inspec/embedded/lib/ruby/gems/2.4.0/gems/inspec-2.0.17/lib/resources/nginx.rb:39:in `block (2 levels) in <class:Nginx>'

We can verify this with Inspec by running the following command:

Command - nginx installed

package('nginx').installed?

Output - nginx installed

inspec> package('nginx').installed?

        => false

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:

Command - docker

docker ps

Output - docker

CONTAINER ID   IMAGE          COMMAND                  CREATED          STATUS          PORTS                NAMES
d4bcef5bb9e3   nginx:latest   "/docker-entrypoint.…"   23 seconds ago   Up 22 seconds   80/tcp               nifty_shtern
4f0ceb9b5974   nginx:latest   "/docker-entrypoint.…"   2 months ago     Up 45 seconds   0.0.0.0:80->80/tcp   nginx

We can enter the InSpec shell on the nginx container instead of our lab environment host machine that we did before.
Run inspec shell, this time providing the -t argument to connect the shell session to the target container.

Command - shell into container

inspec shell -t docker://nginx

Alternate Command

inspec shell -t docker://CONTAINER_ID

Output - shell into container

Welcome to the interactive InSpec Shell
To find out how to use it, type: help

You are currently running on:

    Name:      debian
    Families:  debian, linux, unix, os
    Release:   12.2
    Arch:      x86_64

InSpec is agentless

Remember that the target does not have InSpec installed on it. Your shell session exists on the workstation; InSpec routes commands to the target instance over Docker.

Check that the nginx package is intalled, this time on the target container.

Command - package installed

package('nginx').installed?

Output - package installed

inspec> package('nginx').installed?

        => true

Now, let's get the version of NGINX that is installed on the target, run: nginx.version. You can see that version 1.23.3 was installed on our container.

Command - version

nginx.version

Output - version

inspec> nginx.version
=> "1.25.3"

To complete the example, let's see which modules are enabled on the nginx container. Run nginx.modules to list the installed NGINX modules.

Command - nginx modules

nginx.modules

Output - nginx modules

=> ["http_addition",
 "http_auth_request",
 "http_dav",
 "http_flv",
 "http_gunzip",
 "http_gzip_static",
 "http_mp4",
 "http_random_index",
 "http_realip",
 "http_secure_link",
 "http_slice",
 "http_ssl",
 "http_stub_status",
 "http_sub",
 "http_v2",
 "mail_ssl",
 "stream_realip",
 "stream_ssl",
 "stream_ssl_preread"]

Looking at the nginx_conf resource

The nginx_conf resource examines the contents of the NGINX configuration file, /etc/nginx/nginx.conf.

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.

Command - file methods

file('/tmp').class.superclass.instance_methods(false).sort

Output - file methods

        => [:allowed?,
         :directory?,
         :executable?,
         :exist?,
         :file,
         :file?,
         :file_version,
         :gid,
         :group,
         :grouped_into?,
         ...
         :owned_by?,
         ...
         :readable?,
         ...
         :to_s,
         :type,
         :uid,
         :version?,
         :writable?]

To check whether shell access has been provided to non-admin users, because we want to test attributes of users, you'll use the users resource.

Command - users methods

users.class.superclass.instance_methods(false).sort

Output - users methods

        => [:count, 
        :disabled, 
        :disabled?, 
        :enabled?, 
        :entries, 
        :exist?, 
        :exists?, 
        :gids, 
        :groupnames, 
        :groups, 
        :homes, 
        :maxdays, 
        :mindays, 
        :raw_data, 
        :shells, 
        :to_s, 
        :uids, 
        :usernames, 
        :warndays, 
        :where]

Exit the InSpec shell session with the exit command.

exit