Skip to main content

5. Create a Custom Resource - The Git Example

Aaron LippoldJune 28, 2022About 9 min

Let's practice creating our own custom resource. Suppose we want to write tests that examine the current state of a local Git repository. We will create a git resource that can handle all of InSpec's interactions with a Git repo under the hood, allowing us to focus on writing clean and easy-to-read code within a control.

Create a New InSpec Profile

Let's start by creating a new profile:

Command
inspec init profile my_git

Develop Example Use-case Tests

To write resources, we first need to know 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:

tar xzvf resources/git_test_target.tar.gz

This will generate a git_test_target repository which we will use for these examples.

Now let's write some tests and confirm that they run. You can put these tests in the example.rb file generated in the controls folder of your my_git InSpec profile. These tests are written using the command resource which is provided by InSpec. We will write a git resource in this section to improve this test.

Inputs review

The git_dir input will be used in our profile. It needs to contain the path of the .git folder you are assessing. Usually, you'd want to put a default location for that input in your inspec.yml, such as ./.git, that the user of your profile could overwrite with an inputfile, but for expediency's sake we're going to hardcode it to the .git folder inside of your git_test_target repository. The value in the codeblock below should be correct, but it's always good to doublecheck by using the cd command to navigate inside of the .git folder in the git_test_target repository and then using the pwd command to get the full path.

inspec.yml
name: my_git
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: git_dir
    type: String
    value: /workspaces/saf-training-lab-environment/git_test_target/.git
Command
inspec exec my_git

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.

Rewrite a Test

Let's rewrite the first test in our example file to make it more readable by inventing a git resource that can simplify our test as follows:

# The following branches should exist
describe git(git_dir) do
  its('branches') { should include 'main' }
end

Now let's run the profile.

Command
inspec exec my_git

We should get an error because the git method and resource are not defined yet. We should fix that.

Develop the git resource

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 my_git InSpec profile directory. The content of the file should look like this:

class Git < Inspec.resource(1)
    name 'git'
end

This is - technically - a valid resource! It was very easy to write, but it is not particularly useful for testing. Let's run our tests again to see why not.

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.

Run the profile again.

Command
inspec exec my_git

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:

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:

Command
inspec exec my_git

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:

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.

Command
inspec exec my_git

Now the error message says that the branches method is returning a null value which is a problem because it actually needs to return something, like an array, that implements the predicate method include?. A predicate method is one that evaluates a condition, in this case whether a given branch is "included" in the set of branches, and returns true or false accordingly.

To resolve this problem, we can use the inspec helper method to invoke the built-in command resource to extract this data as shown below:

class Git < Inspec.resource(1)
    name 'git'

    def initialize(path)
        @path = path
    end

    def branches
        inspec.command("git --git-dir #{@path} branch --format='%(refname:short)'").stdout.lines.map(&:strip)
    end

end

You might notice some similarities between this code and what we originally started with in our example.rb file - this is intentional! Resources are used to encapsulate complicated behaviors, such as the mechanics of dealing with niche git subcommands, and expose clean interfaces for use by control authors.

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 branches should exist
describe git(git_dir) do
  its('branches') { should include 'main' }
  its('branches') { should include 'testBranch' }
  its('current_branch') { should eq 'main' }
end
Command
inspec exec my_git

Let's head over to the git.rb file to create the current_branch method we are invoking in the above test:

class Git < Inspec.resource(1)
    name 'git'

    def initialize(path)
        @path = path
    end

    def branches
        inspec.command("git --git-dir #{@path} branch --format='%(refname:short)'").stdout.lines.map(&:strip)
    end

    def current_branch
        inspec.command("git --git-dir #{@path} branch --show-current").stdout.strip
    end

end

1337 h4x0rs

While InSpec controls are intended on being easy to read by both software/cybersecurity engineers AND assessors, InSpec resources are an opportunity to flex those programming muscles and use that arcane sysadmin knowledge to do things in the most optimal way.

Here's an alternative implementation for current_branch:

def current_branch
    branch_name = inspec.command("git --git-dir #{@path} branch").stdout.gsub(" ", "").split("\n").find do |name|
        name.start_with?('*')
    end
    branch_name[1..-1]
end

Note how this iterates over the baseline git branch output which looks like this:

$ git branch
* main
  testBranch

And then we do some fancy stuff with string manipulation while searching for the magic string that starts with an asterisk (which marks the current branch). We're able to leverage the full power of Ruby here!

However, if you're a command line expert (or read the docs!), you'd know that you could just pass a single additional flag to the git branch function that spits out the exact answer that we want - don't get carried away when a simple solution exists!

Now we can run the profile again.

Command
inspec exec my_git

All the tests should pass!

Exercise!

As a solo exercise, try to create a method in the git.rb file to check what the last commit is.

This is Test-Driven Development!

Did you notice the overall arc of how we wrote this resource? We started with a set of tests before we even wrote any resource code, so we knew we would start out with a failing profile.

However, that failing profile helped us define how we should build our resource. Since we knew what sort of tests we wanted to be able to run, we knew what functions we needed to write to support them in the git resource. Test-driven development is an excellent method of defining requirements for your code before you even start writing it!

Run the InSpec shell with a custom resource

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.

Command
inspec shell --depends my_git

Warning

Note that we are passing in the profile directory to the --depends flag, and not the profile's libraries directory. In our example, it's inspec shell --depends my_git and not inspec shell --depends my_git/libraries.

If you edit the resource class file, you'll need to exit the shell and re-launch it for the updates to be available.

From here, we can examine our custom resource in a sandbox in the same way that we do with core resources.

Edit this page on GitHub
Last update: 12/23/2024, 9:39:20 PM
Contributors: Amndeep Singh Mann,Shivani Karikar,Will,wdower,p-oneil,Aaron Lippold,Will Dower,Emily Rodriguez,wdower,Emily Rodriguez
Apache-2.0 | Copyright © 2022 - The MITRE Corporation
Copyright © 2024 Aaron Lippold