All jobs

Add Trivy Scanning to a Terraform Module's CI

Yes. An agent adds the terraform_trivy pre-commit hook to your Terraform module, turns Trivy on in the hook workflow, triages the first findings, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent begins with how this repository already checks itself, because a scanner that runs outside that path is one more thing to maintain. In a module laid out like terraform-aws-modules/terraform-aws-s3-bucket, .pre-commit-config.yaml pins antonbabenko/pre-commit-terraform at v1.108.1 and runs terraform_fmt, terraform_wrapper_module_for_each, terraform_docs, terraform_tflint with a fixed list of --only rules, and terraform_validate. .github/workflows/pre-commit.yml runs on pull requests: a collectInputs job lists the directories, preCommitMinVersions runs only terraform_validate in each at the lowest Terraform the module supports, and preCommitMaxVersion runs the whole config once at the highest, through clowdhaus/terraform-composite-actions/pre-commit@v1.14.0 with install-hcledit: true.

That composite action is where Trivy gets installed. The agent reads its action.yml at the pinned tag and finds install-trivy, off by default, with a trivy-version input; the same file also offers install-tfsec, which is the older scanner Trivy absorbed. So the change is two edits: terraform_trivy added to the hook list after terraform_validate, with arguments that skip downloaded modules and .terraform directories so the scan reads the module's own files, and install-trivy: true with a pinned version on the max-version job. The min-version job is left alone, since it runs only terraform_validate by design.

Then the agent runs the hook itself. In its sandbox it installs pre-commit, the Terraform release the max job would pick, and the Trivy binary at the version it pinned, and runs pre-commit run terraform_trivy --all-files. A module whose whole purpose is to expose S3 options will produce findings in examples/, where a bucket may be created without logging or with an ACL on purpose. For each the agent decides between a change to the example and an inline ignore comment with the reason, and keeps the module's root main.tf, variables.tf and outputs.tf as they are unless a finding is about a real default. Nothing is silenced wholesale.

One detail from release.yml: a push to the default branch cuts a release only when a .tf, .py or .tpl file changed, so a pull request that touches .pre-commit-config.yaml and the workflow alone publishes no version, while one that edits an example does. The pull request description says which of the two it is, and terraform_docs and terraform_fmt run over the examples it touched, since the max-version job would otherwise rewrite them.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add Trivy scanning to this Terraform module's CI. Read .pre-commit-config.yaml, .github/workflows/pre-commit.yml, .github/workflows/release.yml, versions.tf and the examples directory first, and read the action.yml of the pre-commit composite action at the tag the workflow pins to see how it installs Trivy. Add the terraform_trivy hook after terraform_validate with arguments that skip downloaded modules and .terraform directories, and turn on Trivy with a pinned version on the job that runs the full hook list. Install pre-commit, Terraform and Trivy in your sandbox, run pre-commit run terraform_trivy --all-files, and for each finding either fix the example or add an inline ignore with the reason; do not change the root module's defaults. Run terraform_fmt and terraform_docs on anything you touched. Quote the scan output. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request with .pre-commit-config.yaml and .github/workflows/pre-commit.yml changed, plus whichever example files the first scan touched, each with either a fix or an ignore comment naming the finding and why it is accepted there. The description quotes the terraform_trivy run before and after the triage, so a reviewer sees what the scanner found and what is left.

The Pre-Commit workflow runs on the pull request, and the max-version job now installs Trivy and runs the hook, so the checks tab shows the scan passing on the pull request's own files. The run's record keeps the local scan output and every file it read, including the composite action's action.yml.

Before merging, a reviewer reads each ignore comment and decides whether the example should instead change, and whether the pinned Trivy version should follow the one the composite action defaults to.

Run it on every new module repository

An organisation that keeps one repository per module sends one POST /o/{org}/sessions per repository with this body and the repository in resources, from a script. Each run reads that module's own hook list and workflow, so a module that already installs tfsec gets Trivy in its place and the old input removed, and each opens its own pull request.

Send a request_id, a UUID, with each call so a retried request returns the run it already started. Give the key a webhook_url and Rush POSTs run.completed when a run's turn ends, with session_url to read the pull request from, or run.failed when the scan could not be run.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Adding a scanner is easy; adding it so that the first run is green for a reason is the work, because every finding in examples/ needs a judgement about whether the example is wrong or the scanner is. The agent runs the hook in its own sandbox at the versions CI will use, reads each finding against the file, and writes the reason next to the ignore, so the pull request carries the triage and not only the config.

The scan output stays with the run and the pull request quotes it twice, before and after, so a reviewer sees what was found rather than a claim that it passes. Across every module repository a team maintains, the same request runs in parallel, one sandbox and one pull request each.

Frequently asked questions

Why run Trivy through pre-commit rather than a separate action?

Because this repository already runs every check through pre-commit-terraform and the composite action that installs its tools, and that action has an install-trivy input. One more hook in the list is the path the workflow already knows; a second workflow would run on a different Terraform version and a different file list.

Will the min-version job run Trivy too?

No. That job passes terraform_validate as the only hook on purpose, to check the module at the oldest Terraform it supports. Trivy runs once, on the job that runs the full hook list at the highest version.

Why skip downloaded modules?

The examples pull the root module and others into .terraform during terraform init, and scanning those copies reports each finding twice and some against code this repository does not own. The hook's arguments keep the scan to the files in the pull request.

Does this change the module's behaviour?

Not unless a finding is about a real default, and the prompt says not to change the root module. Example fixes and ignore comments do not alter what the module creates, and the pull request says whether a release will be cut from it.

More Terraform jobs

The same job on other stacks

More jobs like this: Hand off a long task

Keep reading