config-lint

A command line tool to validate configurations using rules specified in a YAML file. The configurations files can be one of several formats, such as Terraform, JSON, YAML. There is a built-in set of rules provided for Terraform. Custom files are used for other formats.

Installation

You can use Homebrew to install the latest version:

brew tap stelligent/tap
brew install config-lint

Alternatively, you can install manually from the releases.

Run

The program has a set of built-in rules for scanning the following types of files:

• Terraform

The program can also read files from a separate YAML file, and can scan these types of files:

• Terraform
• Kubernetes
• LintRules
• YAML
• JSON

Example invocations

Validate Terraform files with built-in rules

config-lint -terraform example-files/config

Validate Terraform files with custom rules

config-lint -rules examples-files/rules/terraform.yml example-files/config

Validate Kubernetes files

config-lint -rules example-files/rules/kubernetes.yml example-files/config

Validate LintRules files

This type of linting allows the tool to lint its own rules.

config-lint -rules example-files/rules/lint-rules.yml example-files/rules

Validate a custom YAML file

config-lint -rules example-files/rules/generic-yaml.yml example-files/config/generic.config

Using STDIN

You can use "-" for the filename if you want the configuration data read from STDIN.

cat example-files/resources/s3.tf | config-lint -terraform -

Options

Here are all the different command line options that can be used with config-lint. You can also view them via the -help option.

• -debug - Debug logging

• -exclude value - Filename patterns to exclude

• -exclude-from value - Filename containing patterns to exclude

• -ids string - Run only the rules in this comma separated list

• -ignore-ids string - Ignore the rules in this comma separated list

• -profile string- Provide default options

• -query string - JMESPath expression to query the results

• -rules value - Rules file, can be specified multiple times

• -search string - JMESPath expression to evaluation against the files

• -tags string - Run only tests with tags in this comma separated list

• -terraform - Use built-in rules for Terraform

• -validate - Validate rules file

• -var value - Variable values for rules with ValueFrom.Variable

• -verbose - Output a verbose report

• -version - Get program version

Rules

A YAML file that specifies what kinds of files to process, and what validations to perform, documented here.

Operations

The rules contain a list of expressions that use operations that are documented here.

Examples

See here for examples of custom rules.

Output

The program outputs a JSON string with the results. The JSON object has the following attributes:

• FilesScanned - a list of the filenames evaluated
• Violations - an object whose keys are the severity of any violations detected. The value for each key is an array with an entry for every violation of that severity.

Using -query to limit the output

You can limit the output by specifying a JMESPath expression for the -query command line option. For example, if you just wanted to see the ResourceId attribute for failed checks, you can do the following:

./config-lint -rules example-files/rules/terraform.yml -query 'Violations.FAILURE[].ResourceId' example-files/config/*

Exit Code

If at least one rule with a severity of FAILURE was triggered the exit code will be 1, otherwise it will be 0.

Profiles

You can use a profile to control the default options.

Developing new rules using -search

Each rule requires a JMESPath key that it will use to search resources. Documentation for JMESPATH is here: http://jmespath.org/

The expressions can be tricky to get right, so this tool provides a -search option which takes a JMESPath expression. The expression is evaluated against all the resources in the files provided on the command line. The results are written to stdout.

This example will scan the example terraform file and print the "ami" attribute for each resource:

./config-lint -rules example-files/rules/terraform.yml -search 'ami' example-files/config/terraform.tf

If you specify -search, the rules files is only used to determine the type of configuration files. The files will not be scanned for violations.

Design

The overall design in described here.

VS Code Remote Development

The preferred method of developing is to use the VS Code Remote development functionality.

• Install the VS Code Remote Development extension pack
• Open the repo in VS Code
• When prompted "Folder contains a dev container configuration file. Reopen folder to develop in a container" click the "Reopen in Container" button
• When opening in the future use the "config-lint [Dev Container]" option

Local Development

Prerequisites

• Install golang
• Add the output of the following command to your PATH

echo "$(go env GOPATH)/bin"

Build Command Line tool

make all

The binary is located at .release/config-lint

Tests

Tests are located in the assertion directory. To run all tests:

make test

To run the Terraform builtin rules tests:

make testtf

Linting

To lint all files (using golint):

make lint

Releasing

To release a new version, run make bumpversion to increment the patch version and push a tag to GitHub to start the release process.