Collection of git hooks for Terraform to be used with pre-commit framework
Want to Contribute? Check open issues and contributing notes.
pre-commit
,terraform
,git
, POSIX compatible shell, Internet connection (on first run), x86_64 compatible operation system, Some hardware where this OS will run, Electricity for hardware and internet connection, Some basic physical laws, Hope that it all will works.checkov
required forcheckov
hook.terraform-docs
required forterraform_docs
hooks.terragrunt
required forterragrunt_validate
hook.terrascan
required forterrascan
hook.TFLint
required forterraform_tflint
hook.TFSec
required forterraform_tfsec
hook.
Docker
If no --build-arg
is specified, then the latest versions of pre-commit
and terraform
will be installed.
git clone [email protected]:antonbabenko/pre-commit-terraform.git
cd pre-commit-terraform
# Install all tools with latest versions:
docker build -t pre-commit --build-arg INSTALL_ALL=true .
You can specify needed tool versions by providing --build-arg
's.
If you'd like you can use the latest
versions:
docker build -t pre-commit \
--build-arg PRE_COMMIT_VERSION=latest \
--build-arg TERRAFORM_VERSION=latest \
--build-arg CHECKOV_VERSION=2.0.405 \
--build-arg TERRAFORM_DOCS_VERSION=0.15.0 \
--build-arg TERRAGRUNT_VERSION=latest \
--build-arg TERRASCAN_VERSION=1.10.0 \
--build-arg TFLINT_VERSION=0.31.0 \
--build-arg TFSEC_VERSION=latest \
.
To disable the pre-commit color output, set -e PRE_COMMIT_COLOR=never
.
MacOS
coreutils
required for terraform_validate
hook on macOS (due to use of realpath
).
brew install pre-commit terraform-docs tflint tfsec coreutils checkov terrascan
terrascan init
Ubuntu 18.04
sudo apt update
sudo apt install -y unzip software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install -y python3.7 python3-pip
python3 -m pip install --upgrade pip
pip3 install --no-cache-dir pre-commit
python3.7 -m pip install -U checkov
curl -L "$(curl -s https://api.github.com/repos/terraform-docs/terraform-docs/releases/latest | grep -o -E -m 1 "https://.+?-linux-amd64.tar.gz")" > terraform-docs.tgz && tar -xzf terraform-docs.tgz && rm terraform-docs.tgz && chmod +x terraform-docs && sudo mv terraform-docs /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/terraform-linters/tflint/releases/latest | grep -o -E -m 1 "https://.+?_linux_amd64.zip")" > tflint.zip && unzip tflint.zip && rm tflint.zip && sudo mv tflint /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/aquasecurity/tfsec/releases/latest | grep -o -E -m 1 "https://.+?tfsec-linux-amd64")" > tfsec && chmod +x tfsec && sudo mv tfsec /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/accurics/terrascan/releases/latest | grep -o -E -m 1 "https://.+?_Linux_x86_64.tar.gz")" > terrascan.tar.gz && tar -xzf terrascan.tar.gz terrascan && rm terrascan.tar.gz && sudo mv terrascan /usr/bin/ && terrascan init
Ubuntu 20.04
sudo apt update
sudo apt install -y unzip software-properties-common python3 python3-pip
python3 -m pip install --upgrade pip
pip3 install --no-cache-dir pre-commit
pip3 install --no-cache-dir checkov
curl -L "$(curl -s https://api.github.com/repos/terraform-docs/terraform-docs/releases/latest | grep -o -E -m 1 "https://.+?-linux-amd64.tar.gz")" > terraform-docs.tgz && tar -xzf terraform-docs.tgz terraform-docs && rm terraform-docs.tgz && chmod +x terraform-docs && sudo mv terraform-docs /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/accurics/terrascan/releases/latest | grep -o -E -m 1 "https://.+?_Linux_x86_64.tar.gz")" > terrascan.tar.gz && tar -xzf terrascan.tar.gz terrascan && rm terrascan.tar.gz && sudo mv terrascan /usr/bin/ && terrascan init
curl -L "$(curl -s https://api.github.com/repos/terraform-linters/tflint/releases/latest | grep -o -E -m 1 "https://.+?_linux_amd64.zip")" > tflint.zip && unzip tflint.zip && rm tflint.zip && sudo mv tflint /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/aquasecurity/tfsec/releases/latest | grep -o -E -m 1 "https://.+?tfsec-linux-amd64")" > tfsec && chmod +x tfsec && sudo mv tfsec /usr/bin/
Note: not needed if you use the Docker image
DIR=~/.git-template
git config --global init.templateDir ${DIR}
pre-commit init-templatedir -t pre-commit ${DIR}
Step into the repository you want to have the pre-commit hooks installed and run:
git init
cat <<EOF > .pre-commit-config.yaml
repos:
- repo: git://github.com/antonbabenko/pre-commit-terraform
rev: <VERSION> # Get the latest from: https://github.com/antonbabenko/pre-commit-terraform/releases
hooks:
- id: terraform_fmt
- id: terraform_docs
EOF
After the pre-commit hook has been installing you can run it manually on all files in the repository.
Local installation:
pre-commit run -a
Docker:
docker run -v $(pwd):/lint -w /lint pre-commit run -a
You be able to list tools versions when needed
TAG=latest && docker run --entrypoint cat pre-commit:$TAG /usr/bin/tools_versions_info
There are several pre-commit hooks to keep Terraform configurations (both *.tf
and *.tfvars
) and Terragrunt configurations (*.hcl
) in a good shape:
Hook name | Description | Dependencies Install instructions here |
---|---|---|
checkov |
checkov static analysis of terraform templates to spot potential security issues. Hook notes | checkov Ubuntu deps: python3 , python3-pip |
terraform_docs_replace |
Runs terraform-docs and pipes the output directly to README.md |
python3 , terraform-docs |
terraform_docs_without_ aggregate_type_defaults |
Inserts input and output documentation into README.md without aggregate type defaults. Hook notes same as for terraform_docs |
terraform-docs |
terraform_docs |
Inserts input and output documentation into README.md . Recommended. Hook notes |
terraform-docs |
terraform_fmt |
Rewrites all Terraform configuration files to a canonical format. Hook notes | - |
terraform_providers_lock |
Updates provider signatures in dependency lock files. Hook notes | - |
terraform_tflint |
Validates all Terraform configuration files with TFLint. Available TFLint rules. Hook notes. | tflint |
terraform_tfsec |
TFSec static analysis of terraform templates to spot potential security issues. Hook notes | tfsec |
terraform_validate |
Validates all Terraform configuration files. Hook notes | - |
terragrunt_fmt |
Rewrites all Terragrunt configuration files (*.hcl ) to a canonical format. |
terragrunt |
terragrunt_validate |
Validates all Terragrunt configuration files (*.hcl ) |
terragrunt |
terrascan |
terrascan Detect compliance and security violations. | terrascan |
Check the source file to know arguments used for each hook.
For checkov you need to specify each argument separately:
- id: checkov
args: [
"-d", ".",
"--skip-check", "CKV2_AWS_8",
]
-
terraform_docs
andterraform_docs_without_aggregate_type_defaults
will insert/update documentation generated by terraform-docs framed by markers:<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK --> <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
if they are present in
README.md
. -
It is possible to pass additional arguments to shell scripts when using
terraform_docs
andterraform_docs_without_aggregate_type_defaults
. Send pull-request with the new hook if something is missing. -
It is possible to automatically:
- create docfile (and PATH to it)
- extend exiting docs files, by appending markers to the end of file (see p.1)
- use different than
README.md
docfile name.
- id: terraform_docs args: - --hook-config=--path-to-file=README.md # Valid UNIX path. I.e. ../TFDOC.md or docs/README.md etc. - --hook-config=--add-to-exiting-file=true # Boolean. true or false - --hook-config=--create-file-if-not-exist=true # Boolean. true or false
-
You can provide arguments to terraform_doc. Eg. for configuration:
- id: terraform_docs args: - --args=--config=.terraform-docs.yml
-
If you need some exotic settings, it can be be done too. I.e. this one generates HCL files:
- id: terraform_docs args: - tfvars hcl --output-file terraform.tfvars.model .
terraform_docs_replace
replaces the entire README.md rather than doing string replacement between markers. Put your additional documentation at the top of your main.tf
for it to be pulled in. The optional --dest
argument lets you change the filename that gets created/modified.
Example:
- id: terraform_docs_replace
args:
- --sort-by-required
- --dest=TEST.md
-
terraform_fmt
supports custom arguments so you can pass supported flags. Eg:- id: terraform_fmt args: - --args=-no-color - --args=-diff - --args=-write=false
-
The hook requires Terraform 0.14 or later.
-
The hook invokes two operations that can be really slow:
terraform init
(in case.terraform
directory is not initialised)terraform providers lock
.
Both operations require downloading data from remote Terraform registries, and not all of that downloaded data or meta-data is currently being cached by Terraform.
-
terraform_providers_lock
supports custom arguments:- id: terraform_providers_lock args: - '--args=-platform=windows_amd64' - '--args=-platform=darwin_amd64'
-
It may happen that Terraform working directory (
.terraform
) already exists but not in the best condition (eg, not initialized modules, wrong version of Terraform, etc.). To solve this problem, you can find and delete all.terraform
directories in your repository:echo " function rm_terraform { find . -name ".terraform*" -print0 | xargs -0 rm -r } " >>~/.bashrc # Reload shell and use `rm_terraform` command in the repo root
terraform_providers_lock
hook will try to reinitialize them before running theterraform providers lock
command.
-
terraform_tflint
supports custom arguments so you can enable module inspection, deep check mode, etc.Example:
- id: terraform_tflint args: - --args=--deep - --args=--enable-rule=terraform_documented_variables
-
When you have multiple directories and want to run
tflint
in all of them and share a single config file, it is impractical to hard-code the path to.tflint.hcl
file. The solution is to use the__GIT_WORKING_DIR__
placeholder which will be replaced byterraform_tflint
hooks with Git working directory (repo root) at run time. For example:- id: terraform_tflint args: - --args=--config=__GIT_WORKING_DIR__/.tflint.hcl
-
terraform_tfsec
will consume modified files that pre-commit passes to it, so you can perform whitelisting of directories or files to run against via files pre-commit flagExample:
- id: terraform_tfsec files: ^prd-infra/
The above will tell pre-commit to pass down files from the
prd-infra/
folder only such that the underlyingtfsec
tool can run against changed files in this directory, ignoring any other folders at the root level -
To ignore specific warnings, follow the convention from the documentation.
Example:
resource "aws_security_group_rule" "my-rule" { type = "ingress" cidr_blocks = ["0.0.0.0/0"] #tfsec:ignore:AWS006 }
-
terraform_tfsec
supports custom arguments so you can pass supported--no-color
or--format
(output),-e
(exclude checks) flags:- id: terraform_tfsec args: - > --args=--format json --no-color -e aws-s3-enable-bucket-logging,aws-s3-specify-public-access-block
-
Like terraform_tflint,
__GIT_WORKING_DIR__
can be used when specifying files relative to the git working directory:
Example:
```yaml
- id: terraform_tfsec
args: [--args=--config-file=__GIT_WORKING_DIR__/.tfsec.json]
```
-
terraform_validate
supports custom arguments so you can pass supported-no-color
or-json
flags:- id: terraform_validate args: - --args=-json - --args=-no-color
-
terraform_validate
also supports custom environment variables passed to the pre-commit runtime:- id: terraform_validate args: - --envs=AWS_DEFAULT_REGION="us-west-2" - --envs=AWS_ACCESS_KEY_ID="anaccesskey" - --envs=AWS_SECRET_ACCESS_KEY="asecretkey"
-
It may happen that Terraform working directory (
.terraform
) already exists but not in the best condition (eg, not initialized modules, wrong version of Terraform, etc.). To solve this problem, you can find and delete all.terraform
directories in your repository:echo " function rm_terraform { find . -name ".terraform*" -print0 | xargs -0 rm -r } " >>~/.bashrc # Reload shell and use `rm_terraform` command in the repo root
terraform_validate
hook will try to reinitialize them before running theterraform validate
command.Warning: If you use Terraform workspaces, DO NOT use this workaround (details). Wait to
force-init
option implementation
This repository is managed by Anton Babenko with help from these awesome contributors:
MIT licensed. See LICENSE for full details.