tfsec custom rules and CI integration

Custom rules

# .tfsec/custom_checks.yml
checks:
  - code: CUS001
    description: Ensure all EC2 instances have a cost_center tag
    impact: Untagged resources cannot be allocated to cost centers
    resolution: Add a cost_center tag
    requiredTypes:
      - resource
    requiredLabels:
      - aws_instance
    severity: HIGH
    matchSpec:
      name: tags
      action: contains
      value: cost_center
    errorMessage: EC2 instance is missing cost_center tag

CI integration

jobs:
  tfsec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: aquasecurity/tfsec-action@v1.0.3
        with:
          additional_args: --minimum-severity HIGH
          format: sarif
          output_file_path: tfsec.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: tfsec.sarif

tfsec (legacy) - migration reference

Companion reference for trivy-config. tfsec is transitioning to Trivy per Aqua Security's own guidance - the host skill is the forward path, and tfsec's checks ship inside trivy config. Keep this reference for an existing Terraform-only tfsec stack while the migration lands.

Overview

Per tfsec-home (opens in new window), tfsec is transitioning to Trivy, Aqua Security's consolidated scanner. For new projects, evaluate Trivy first; tfsec remains stable for existing usage.

When to use

• Existing tfsec project; team isn't ready to migrate to Trivy.
• Terraform-only stack; want a focused Terraform-specific scanner.
• A specific tfsec rule covers something Trivy doesn't yet.

How to use

1. Install tfsec via Homebrew or the release binary (Step 1).
2. Run tfsec . against the Terraform tree, starting at --minimum-severity HIGH to keep the signal high (Step 2).
3. Emit SARIF for GitHub Code Scanning, or JUnit / Markdown for CI and PR comments (Step 3).
4. Triage findings - fix real issues, annotate intentional exceptions with justified tfsec:ignore: comments (Step 4).
5. Verify: re-run tfsec . --minimum-severity HIGH after remediation and assert it reports no HIGH findings before merging; if any remain, fix or justify-ignore them and re-run.
6. Add custom YAML rules for team-specific policy, then wire the scan into CI (Steps 5-6).
7. Confirm cloud coverage; fall back to OPA / Conftest for unsupported clouds (Step 7).
8. Plan the Trivy migration for new work, and combine with Checkov / KICS for overlapping coverage (Steps 8-9).

Step 1 - Install

# macOS
brew install tfsec

# Linux
curl -L https://github.com/aquasecurity/tfsec/releases/latest/download/tfsec-linux-amd64 \
  -o /usr/local/bin/tfsec
chmod +x /usr/local/bin/tfsec

Step 2 - Run

# Scan current directory
tfsec .

# Scan specific path
tfsec ./terraform/

# Concise output
tfsec . --concise-output

# Specific severity threshold
tfsec . --minimum-severity HIGH

Step 3 - Output formats

Per tfsec-home (opens in new window): "JSON and SARIF output capabilities for integration with external tools and workflows."

# JSON
tfsec . -f json > tfsec.json

# SARIF (GitHub Code Scanning)
tfsec . -f sarif -O tfsec.sarif

# JUnit XML
tfsec . -f junit -O tfsec.xml

# Markdown (PR comments)
tfsec . -f markdown

Step 4 - Skip checks

# Skip specific checks
tfsec . -e aws-s3-enable-bucket-encryption,aws-s3-enable-versioning

# Skip everything matching a pattern
tfsec . -e aws-s3-*

Inline:

# main.tf
resource "aws_s3_bucket" "public_data" {
  # tfsec:ignore:aws-s3-enable-bucket-encryption Public dataset, not encrypted by design
  # tfsec:ignore:aws-s3-enable-bucket-logging Public CDN, no audit logging needed
  bucket = "my-public-data"
  acl    = "public-read"
}

Step 5 - Custom rules

Author custom YAML rules for team-specific policy the built-in set misses: tfsec-custom-rules-and-ci.md (opens in new window).

Step 6 - CI integration

Run the official tfsec action with SARIF upload to GitHub Code Scanning: tfsec-custom-rules-and-ci.md (opens in new window).

Step 7 - Supported clouds

Per tfsec-home (opens in new window), tfsec covers AWS (S3, EC2, RDS, IAM, Lambda, API Gateway, and 30+ services), Azure (App Service, Storage, Database, Container, Key Vault), Google Cloud (Compute, GKE, SQL, Storage, IAM, BigQuery), plus Kubernetes, OpenStack, Oracle, DigitalOcean, and CloudStack.

For unsupported clouds, fall back to OPA / Conftest with custom Rego per policy-as-code-runner.

Step 8 - Migration to Trivy

Per tfsec-home (opens in new window) guidance:

# Install Trivy
brew install trivy   # or apt-get / etc.

# Trivy includes tfsec's checks under `trivy config`
trivy config ./terraform/

The migration is mostly mechanical - Trivy ingests the same .tf files; rule names may differ.

Step 9 - Combine with Checkov + KICS

Multiple scanners catch overlapping but non-identical issues. tfsec is faster and Terraform-specific; Checkov (checkov-policy) is broader; the KICS tool adds different rule classes.

tfsec . -f json > tfsec.json
checkov -d . -o json > checkov.json
kics scan -p . --report-formats json
# unify results across the three scanners

Worked example

A team runs tfsec on an AWS Terraform module while planning a Trivy migration.

1. brew install tfsec, then tfsec ./terraform/ --minimum-severity HIGH to focus on the worst findings first.
2. tfsec flags an unencrypted S3 bucket (aws-s3-enable-bucket-encryption) as HIGH.
3. The bucket is a public dataset by design, so the author adds # tfsec:ignore:aws-s3-enable-bucket-encryption Public dataset, not encrypted by design inline.
4. CI runs aquasecurity/tfsec-action@v1.0.3 with format: sarif; the SARIF upload posts remaining findings to the Security tab.
5. Ahead of the switch they dry-run trivy config ./terraform/ and confirm the same .tf files scan under Trivy.

Result: HIGH-severity misconfigurations gate the build, intentional exceptions are documented inline, and the Trivy forward-path is validated before switching.

Anti-patterns

Limitations

• Terraform-only. Doesn't scan Kubernetes / Dockerfile / CloudFormation directly (Trivy expands).
• Maintenance pace slowing. Per tfsec-home (opens in new window), tfsec gets bug fixes but not new features.
• Some new cloud services lag in coverage. Newer AWS / Azure resources may not have rules yet.
• No baseline support out of the box. Adopt against legacy via skip annotations or wrapper scripts.

References

• tfs (opens in new window) - tfsec overview, transition-to-Trivy positioning, developer-friendly output, AWS / Azure / GCP / Kubernetes / OpenStack / Oracle / DigitalOcean / CloudStack support, JSON / SARIF output.
• Custom YAML rules + CI workflow: tfsec-custom-rules-and-ci.md (opens in new window).
• checkov-policy - sister scanner.
• policy-as-code-runner - custom OPA / Rego policies (for unsupported clouds or custom rules).

trivy-config - deep reference

Long inline blocks moved out of the SKILL.md spine to keep the core scan flow lean. Version pins referenced below live in the Pinned versions section of SKILL.md.

Custom Rego policy - full example

Per trivy.dev custom checks docs (opens in new window), each policy file requires a unique package declaration and a METADATA annotation block:

# policies/require_cost_center_tag.rego
# METADATA
# title: "EC2 instances must have cost_center tag"
# description: "Untagged resources cannot be allocated to cost centers"
# schemas:
#   - input: schema["cloud"]
# custom:
#   id: USER-TF-001
#   severity: HIGH
#   input:
#     selector:
#       - type: cloud

package user.terraform.USER-TF-001

import rego.v1

deny contains res if {
    instance := input.aws.ec2.instances[_]
    not instance.tags["cost_center"]
    res := result.new(
        sprintf("EC2 instance '%s' missing cost_center tag", [instance.id.value]),
        instance,
    )
}

The --namespaces value (here: user) must match the first segment of the package path. Supported input.selector types include cloud (Terraform / CloudFormation), kubernetes, dockerfile, yaml, json, toml, and terraform-raw.

GitHub Actions workflow - full YAML

SARIF output integrates directly with GitHub Code Scanning. The if: always() on the upload step ensures findings appear in the Security tab even when the scan step exits non-zero:

# .github/workflows/trivy-iac.yml
jobs:
  trivy-config:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v5

      - name: Run Trivy config scan
        uses: aquasecurity/trivy-action@0.31.0
        with:
          scan-type: config
          scan-ref: .
          severity: HIGH,CRITICAL
          exit-code: 1
          format: sarif
          output: trivy.sarif
          ignore-unfixed: true

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: trivy.sarif