Code Quality and Security Scanning

The tools differ in what they know. A formatter knows only the syntax tree. terraform validate knows the schema of every provider in the configuration. A linter such as TFLint knows conventions and, with a provider ruleset, which instance types or regions exist. A security scanner knows a catalogue of insecure configurations. A cost estimator knows a price list. The cheapest checks run first and the slowest or most opinionated run last.

The left half runs on every commit through pre-commit hooks and must be fast enough that nobody disables it. The right half runs in the pull request pipeline, where a few minutes are acceptable and where the results can be published as SARIF annotations or as a pull request comment.

terraform fmt rewrites configuration files to the canonical layout described in the style guide: two-space indentation, aligned = signs within a block, and consistent spacing. It changes only whitespace and never the meaning of the code, which is why it is safe to run automatically. Its usage is terraform fmt [options] [target...], where a target is a directory, a file, or a single dash - to read from standard input.

The documented exit status is 0 when the input is properly formatted, and non-zero when -check finds improperly formatted input. The page does not document any other exit codes, so scripts should only test for zero versus non-zero.

The output above is illustrative and abbreviated, not copied from an official page; in particular the exact non-zero value is not documented.

Source: Terraform Docs — terraform fmt

Two habits make fmt painless. Run terraform fmt -recursive before committing (the pre-commit hook below does it for you), and make CI run terraform fmt -check -recursive so a badly formatted pull request fails fast with a precise message. fmt also formats .tfvars files and, in OpenTofu, .tofu files; tofu fmt accepts the same flags.

terraform validate checks that the configuration is syntactically valid and internally consistent, regardless of variable values or existing state. It is meant for reusable modules too: it verifies attribute names and value types against each provider’s schema. It does not contact remote services, so it will not notice that a bucket name is already taken or that a remote state backend is unreachable. It does need an initialised working directory because the provider schemas come from the installed plugins; to initialise without touching a backend, run terraform init -backend=false.

With -json the output is one object with format_version (1.0 as of Terraform 1.1.0), valid, error_count, warning_count and a diagnostics array. Each diagnostic carries a severity (error or warning), a summary, an optional detail, an optional range (file name plus start and end byte, line and column) and an optional snippet. Consumers should ignore severities they do not recognise, and should treat non-JSON standard output as a generic failure, because early errors that happen before validation begins may not be JSON.

Source: Terraform Docs — terraform validate

validate is the first check that needs the provider plugins, so in a pipeline it is also the step that proves the provider requirements resolve. tofu validate behaves the same way. The expression-level checks it cannot do (does this variable have a sensible value, does this resource satisfy a business rule) belong to Lifecycle, Validation and Checks and to tests.

TFLint is a pluggable linter for Terraform. It reads the configuration, evaluates variables and module calls, and runs rules supplied by rulesets. A ruleset is a plugin: one is bundled in the binary (the Terraform language ruleset) and the provider-specific ones (AWS, Google Cloud, AzureRM) are installed with tflint --init.

terraform-docs generates documentation from a module’s source: inputs, outputs, providers, requirements, resources and the module’s header. It is the tool behind most README tables in the public registry, and it is what keeps the README of a Bookshelf module from drifting away from its variables. It is installed with Homebrew (brew install terraform-docs), Scoop, Chocolatey, a release binary, go install github.com/terraform-docs/terraform-docs@v0.24.0, or the container image quay.io/terraform-docs/terraform-docs.

Formatters include markdown (with the table and document variants), asciidoc (with table and document), json, yaml, toml, xml, pretty, tfvars hcl and tfvars json; md, adoc, tbl and doc are accepted as short names. Because this site is written in AsciiDoc, the asciidoc table formatter is the one to remember. The header comes from main.tf by default, and --header-from accepts .adoc, .md, .tf, .tofu and .txt files.

The configuration file is .terraform-docs.yml, found in the module root, in a .config/ folder, in the current directory or in $HOME/.tfdocs.d/; -c or --config selects another file, and CLI flags override the file. formatter is the only required option.

Source: terraform-docs — Configuration

The output.mode is inject (the default) or replace. With inject, only the text between the begin and end comments is replaced; the file is created if it does not exist and the block is appended if the comments are missing. With replace, the whole file is rewritten, so hand-written content is lost. The template must contain the begin comment, the {{ .Content }} slug (spaces inside the braces are mandatory) and the end comment, and for AsciiDoc output the comments may be written // BEGIN_TF_DOCS and // END_TF_DOCS.

Source: terraform-docs — asciidoc table

--output-check is listed among the inherited options (default false) with the description "check if content of output file is up to date", which is exactly what a CI job needs. Avoid recursive.enabled: true in a config file that the pre-commit hook will use: pre-commit-terraform warns that it can cause unexpected behaviour. terraform-docs 0.12.0 or later is required for the terraform_docs hook, and the tool’s own compatibility table maps terraform-docs >= 0.13 to Terraform >= 0.15.

The pre-commit framework runs checks on the files in a commit before it is created. pre-commit-terraform is a collection of hooks for it that wrap the tools in this page, and it works with Terraform, OpenTofu and Terragrunt. It can be used as standalone Git hooks or as the container image ghcr.io/antonbabenko/pre-commit-terraform.

The hooks listed in its README include terraform_fmt, terraform_validate, terraform_docs, terraform_docs_without_aggregate_type_defaults, terraform_providers_lock, terraform_tflint, terraform_trivy, terraform_checkov, infracost_breakdown, terragrunt_fmt, terragrunt_validate, tfupdate and terrascan. Several are marked deprecated: terraform_tfsec (use terraform_trivy), checkov (use terraform_checkov) and terraform_docs_replace. Each hook requires its underlying tool to be on the PATH (for example tflint, terraform-docs, trivy, checkov, and jq for terraform_validate --retry-once-with-cleanup and for infracost_breakdown).

Source: pre-commit-terraform — README

Installing it into a clone is pre-commit install, and pre-commit run -a runs every hook against all files, not only the changed ones. Three details from the README matter in practice.

Other useful switches are PCT_LOG=trace for debugging and PRE_COMMIT_COLOR=never to disable colour.

The docs hook also takes --hook-config options. --path-to-file, --add-to-existing-file, --create-file-if-not-exist and --use-standard-markers control where the documentation goes, and --custom-marker-begin and --custom-marker-end let it use other comment styles; for AsciiDoc the README suggests // BEGIN_TF_DOCS and // END_TF_DOCS.

Checkov is a static analysis tool for infrastructure as code. For Terraform it parses the HCL, builds a graph of resources and their connections, and runs a catalogue of policies, each with an ID such as CKV_AWS_21 ("Ensure all data stored in the S3 bucket have versioning enabled"). It also scans CloudFormation, Kubernetes manifests, Helm charts, Dockerfiles and more, which is useful on a repository that mixes them. It is installed with pip install checkov (a virtual environment is recommended on Debian 12), brew install checkov, or run from a container.

Trivy from Aqua Security is a scanner for containers, filesystems, repositories, Kubernetes and infrastructure as code. Its IaC engine began as tfsec. The tfsec repository now states that the project has been consolidated into Trivy, that Trivy offers "the same excellent Terraform scanning engine" with more integrations, and that tfsec "will continue to remain available for the time being" while engineering attention goes to Trivy. For new work use Trivy; for existing tfsec users there is a migration guide, and pre-commit-terraform has marked its terraform_tfsec hook as deprecated in favour of terraform_trivy.

Source: tfsec — tfsec to Trivy migration

Both tools read Terraform statically and ship a large catalogue; the choice is mostly about ecosystem. Checkov’s strength is its graph-based YAML policies and Python checks, and its baseline feature; Trivy’s is a single binary that also scans container images, secrets and dependencies, plus Rego for custom rules. Many teams run both in CI because their catalogues overlap but do not coincide, and accept some duplicate findings; the ignore mechanisms are separate, so a deliberate exception must be recorded in both. Neither can see runtime state or drift, and neither replaces least-privilege IAM design or the policies that HCP Terraform evaluates at plan time.

Infracost estimates the monthly cost of Terraform (and Terragrunt, CloudFormation and AWS CDK) changes before they are applied, so the price of a pull request is a review comment rather than a surprise on the bill. The project describes itself as supporting over 1,100 resources across AWS, Azure and Google Cloud.

Infracost went through a major rewrite. The current CLI (the infracost/cli repository, observed v2.18.2) is installed with brew install infracost or the project’s install script, authenticates with infracost auth login (or the INFRACOST_CLI_AUTHENTICATION_TOKEN variable in non-interactive environments), and is used with infracost setup, infracost scan and infracost inspect --summary. infracost scan takes a directory (the current one by default) and auto-detects the IaC type, or reads projects from an infracost.yml. The older 0.10 line used infracost breakdown, infracost diff and infracost comment, and some third-party material, including the pre-commit-terraform infracost_breakdown hook, still shows those commands; check which major your installation is before copying a recipe.

Source: Infracost Docs — Get started

In a pull request workflow the documented pattern checks out the base and head commits side by side and runs a diff inside the Infracost CI image. The token is a repository secret, and GITHUB_TOKEN must be mapped into the environment or diff exits before scanning.

Source: Infracost Docs — GitHub Actions

A red check does not block merging by itself; to block, mark the job as a required status check in the branch ruleset. The infracost/actions repository offers diff and scan actions as an alternative (infracost/actions/diff@v5 and infracost/actions/scan@v5), and recommends the Infracost GitHub App where an organisation allows it. Infracost has free and paid plans (budgets, tagging policies and guardrails live in Infracost Cloud); consult the pricing page before relying on a feature in a pipeline. The estimate covers resources the tool knows; usage-based resources such as requests or data transfer need a usage file, and the figure is an estimate, not a bill.

Terraform configurations depend on providers, modules, the Terraform or OpenTofu version, GitHub Actions and, with .terraform.lock.hcl, on exact provider hashes. Static tools cannot tell you that a provider has a security fix; a bot that opens pull requests can.

A Makefile gives the team one vocabulary (make check) that works the same locally and in CI, and documents which tools the repository expects. This one is original to Bookshelf and illustrative. Recipe lines must start with a tab.

Source: Terraform Docs — terraform fmt

The -chdir global option, the -backend=false and -input=false flags, and the tfplan.json pipeline were described earlier on this page and in CLI Essentials. Keep the plan JSON out of version control and out of build artifacts that outlive the job, because it can contain secret values; add tfplan* to .gitignore.

The GitHub Actions job below runs the same ladder. It uses hashicorp/setup-terraform (current major v4 at the time of writing, where older material says v3), terraform-linters/setup-tflint (v6) and, for OpenTofu, opentofu/setup-opentofu (v2). The fuller pipeline, with plans commented on the pull request, approvals and OIDC credentials, is built in CI/CD and Automation.

Source: hashicorp/setup-terraform — README

The GITHUB_TOKEN in the TFLint step avoids anonymous GitHub API rate limits when tflint --init downloads ruleset plugins. terraform_wrapper: false avoids the wrapper that captures standard output, which interferes with commands that print machine-readable output. The tofu_wrapper input name for opentofu/setup-opentofu follows that action’s convention and should be confirmed on its README before use. In the matrix, opentofu/setup-opentofu and the tofu binary run the same fmt and validate commands, which is a cheap way to detect accidental use of a Terraform-only feature.

Adopting everything on a mature repository at once produces a wall of findings and a team that learns to ignore them. A sequence that works:

Every suppression should carry a reason and, where the tool supports it, an expiry (exp: in .trivyignore). Review the suppressions periodically: a skipped check that nobody remembers is a hole in the net.

The two books this section draws on predate several of these: they teach tfsec rather than Trivy, and cover the TFLint and Checkov command lines of their time. Where they differ from the official documentation cited here, the official documentation wins.