Want to Contribute? Check open issues and contributing notes.

• How to install
  • 1. Install dependencies
  • 2. Install the pre-commit hook globally
  • 3. Add configs and hooks
  • 4. Run
• Available Hooks
• Hooks usage notes and examples
  • checkov
  • terraform_docs
  • terraform_docs_replace
  • terraform_providers_lock
  • terraform_tflint
  • terraform_tfsec
  • terraform_validate
• Authors
• License

• 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 for checkov hook.
• terraform-docs required for terraform_docs hooks.
• terragrunt required for terragrunt_validate hook.
• terrascan required for terrascan hook.
• TFLint required for terraform_tflint hook.
• TFSec required for terraform_tfsec hook.

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 .

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

brew install pre-commit terraform-docs tflint tfsec coreutils checkov terrascan
terrascan init

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

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 pre-commit hook has been installed 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 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:

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",
  ]

1. terraform_docs and terraform_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.

2. It is possible to pass additional arguments to shell scripts when using terraform_docs and terraform_docs_without_aggregate_type_defaults. Send pull-request with the new hook if there is something missing.

For these hooks you need to specify all arguments as one:

- 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 name of the file that gets created/modified.

Example:

- id: terraform_docs_replace
  args:
    - --sort-by-required
    - --dest=TEST.md

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

2. When you have multiple directories and want to run tflint in all of them and share single config file it is impractical to hard-code the path to .tflint.hcl file. The solution is to use __GIT_WORKING_DIR__ placeholder which will be replaced by terraform_tflint hooks with Git working directory (repo root) at run time. For example:

   - id: terraform_tflint
     args:
       - --args=--config=__GIT_WORKING_DIR__/.tflint.hcl

1. 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 flag

   Example:

   - 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 underlying tfsec tool can run against changed files in this directory, ignoring any other folders at the root level

2. 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
   }

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

1. terraform_validate supports custom arguments so you can pass supported -no-color or -json flags:

    - id: terraform_validate
      args:
        - --args=-json
        - --args=-no-color

2. 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"

3. 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 repo root

   terraform_validate hook will try to reinitialize them before running terraform validate command.

   Warning: If you use Terraform workspaces, DO NOT use this workaround (details). Wait to force-init option implementation

1. The hook requires Terraform 0.14 or later.

2. The hook invokes two operations that can be really slow: terraform init (in case .terraform directory is not initialised) and 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.

3. terraform_providers_lock supports custom arguments.

   Example:

   hooks:
     - id: terraform_providers_lock
       args: ['--args=-platform=windows_amd64']

   In order to pass multiple args, try the following:

    - id: terraform_providers_lock
      args:
         - '--args=-platform=windows_amd64'
         - '--args=-platform=darwin_amd64'

4. It may happen that Terraform working directory (.terraform) already exists but is outdated (e.g. not initialized modules, wrong version of Terraform, etc). To solve this problem you can find and delete all .terraform directories in your repository using this command:

   find . -type d -name .terraform -prune -print -exec rm -rf {} \;

   terraform_providers_lock hook will try to reinitialize them before running terraform providers lock command.

This repository is managed by Anton Babenko with help from these awesome contributors:

MIT licensed. See LICENSE for full details.