tfsec

What it is and where it fits 🎯#

tfsec is Terraform-specific static analysis for security misconfigurations — it reads .tf source directly and needs no plan/apply, so it can run in a pre-commit hook or on every PR with zero cloud credentials or state access required.

Installation#

curl -s https://raw.githubusercontent.com/aquasecurity/tfsec/master/scripts/install_linux.sh | bash
# installs to /usr/local/bin by default — needs sudo, or download the release binary directly and place it
# on your own PATH (e.g. ~/.local/bin) if you don't have sudo:
curl -sL -o tfsec https://github.com/aquasecurity/tfsec/releases/latest/download/tfsec-linux-amd64
chmod +x tfsec && mv tfsec ~/.local/bin/

go install github.com/aquasecurity/tfsec/cmd/tfsec@latest    # if you have a Go toolchain

tfsec --version

Scanning#

tfsec .                                       # scan the current directory recursively
tfsec /path/to/terraform
tfsec --minimum-severity HIGH .               # CRITICAL, HIGH, MEDIUM, or LOW

CI gating — the inverted default worth remembering#

tfsec . --soft-fail                            # run checks but always exit 0 — reporting-only mode
tfsec .                                        # default: non-zero exit if any (non-ignored) issue is found

Excluding checks and paths#

tfsec . --exclude aws-s3-enable-bucket-encryption,aws-s3-enable-versioning
tfsec . --exclude-path .terraform --exclude-path modules/vendored
tfsec . --exclude-downloaded-modules            # skip anything pulled into .terraform/modules

Inline suppression, directly above the offending resource block:

#tfsec:ignore:aws-s3-enable-bucket-encryption
resource "aws_s3_bucket" "example" {
  # ...
}

Output formats#

tfsec . --format json --out results.json
tfsec . --format sarif --out results.sarif      # for GitHub code scanning
tfsec . --format junit --out results.xml
tfsec . --concise-output                         # summary only, no code snippets
tfsec . --include-passed                          # show passing checks too, not just failures

Sample lovely (default) output shape — illustrative, actual check IDs depend on what's in the scanned Terraform:

Custom checks#

tfsec . --custom-check-dir ./custom-checks       # load org-specific Rego/JSON checks alongside built-ins

A custom check is a small JSON/YAML document describing a Rego-backed rule:

{
  "checks": [
    {
      "code": "CUS001",
      "description": "Ensure all resources are tagged with an owner",
      "requiredTypes": ["resource"],
      "requiredLabels": ["aws_instance", "aws_s3_bucket"],
      "severity": "MEDIUM",
      "matchSpec": {
        "name": "tags",
        "action": "notContains",
        "value": "owner"
      },
      "errorMessage": "Resource is missing a required 'owner' tag"
    }
  ]
}

tfsec vs. the other IaC scanners in this series#

Adoption checklist for a new Terraform repo#

• Run tfsec . once, unfiltered, to see the real baseline finding count before deciding on a rollout plan
• Decide severity threshold for the initial hard gate (--minimum-severity HIGH is a common starting point)
• Add inline #tfsec:ignore comments only for genuinely reviewed, accepted exceptions — not as a way to silence noise quickly
• Wire the CI step in with SARIF output so findings show up as inline PR annotations, not just a pass/fail badge
• Revisit the severity threshold quarterly as the backlog of lower-severity findings gets addressed

Real-world scenario: gating new Terraform without a wall of legacy findings#

A large existing Terraform codebase adopting tfsec for the first time often has too many pre-existing findings to fix before the first PR merges. --soft-fail on the whole repo defeats the purpose; a more targeted approach scopes the hard gate to what actually changed:

# CI step: only fail on findings in files this PR actually touched
git diff --name-only origin/main...HEAD -- '*.tf' > changed.txt
if [ -s changed.txt ]; then
  tfsec $(cat changed.txt | xargs dirname | sort -u)
fi

Real-world scenario: GitHub Actions CI recipe#

# .github/workflows/tfsec.yml
name: tfsec
on: [pull_request]
jobs:
  tfsec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aquasecurity/tfsec-sarif-action@v0.1.4
        with:
          sarif_file: tfsec.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: tfsec.sarif

A sample of frequently-hit built-in checks#

tfsec's --help doesn't expose a flag to list every check from the CLI itself — check the online checks catalog linked from the official docs for the full, current list. The built-in catalog grows and check IDs occasionally get renamed across releases, so treat the table above as a taste of what tfsec catches, not an exhaustive reference.

Common pitfalls#

• Assuming the same "reports, doesn't gate" default as Trivy/Grype — see the NOTE above; tfsec is the opposite.
• Not knowing tfsec is in maintenance mode — planning new custom-check investment against tfsec's Rego format when that investment would carry forward more safely against Trivy's actively developed check bundle.
• Inline #tfsec:ignore comments accumulating with no review process — like any suppression mechanism, worth periodically auditing (grep -rn 'tfsec:ignore') rather than letting them silently pile up.

Exit codes#

0 clean, or --soft-fail set · non-zero when findings exist and --soft-fail is not set.

Full flag reference#

Troubleshooting#

"tfsec found nothing, but I know this file has an issue" — check whether the resource lives inside a downloaded module (.terraform/modules/); --exclude-downloaded-modules is off by default in most setups, but a project-level config might have it on. Also confirm the file has a .tf extension tfsec actually scans recursively from the given directory — tfsec . from the wrong working directory silently scans nothing.

"A check keeps firing even though I added #tfsec:ignore" — the comment must be directly above the resource block, not the argument line; a misplaced ignore comment is a silent no-op, not an error.

"Results look different between my laptop and CI" — confirm both are running the exact same tfsec version (tfsec --version); check bundle content and defaults have changed release to release even during the maintenance-mode period, so a floating "latest" in CI vs. a pinned local install is a common source of drift.

Real-world scenario: migrating an existing tfsec CI gate to Trivy#

Given tfsec's maintenance-mode status, a team with tfsec already wired into CI has a natural migration path that doesn't require a big-bang cutover:

# Run both in parallel for a sprint, comparing findings
tfsec . --format json --out tfsec-results.json
trivy config . --format json --output trivy-results.json
# Once trivy's findings are confirmed to be a superset (or an acceptable equivalent), drop the tfsec step

Because Trivy's Terraform checks are literally sourced from tfsec's own check library, this comparison usually converges quickly — most differences come down to check-ID naming rather than genuinely different coverage, but it's worth confirming on a security-critical repo before removing the older gate entirely.

When to reach for something else#

trivy config now covers the same Terraform check library tfsec does, actively maintained, plus other IaC formats in the same run — see the Trivy IaC/SBOM cheat-sheet page. Checkov remains a genuinely distinct option for teams whose IaC footprint includes Ansible, Bicep, or Serverless Framework, which neither tfsec nor Trivy's config scanner cover as of this writing.