All jobs

Add Checkov Scanning to a Terraform Module's CI

Yes. An agent adds Checkov to your Terraform module's pre-commit hooks and CI, triages every finding with a reason, and opens a PR that passes the new scan.

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 reads how the module is already checked. In a module shaped like terraform-aws-modules/terraform-aws-vpc, .pre-commit-config.yaml runs the antonbabenko/pre-commit-terraform hooks terraform_fmt, terraform_wrapper_module_for_each, terraform_docs, terraform_tflint with a fixed list of --only rules, and terraform_validate, and .github/workflows/pre-commit.yml runs those hooks in CI across every directory the clowdhaus composite action finds, with TFLINT_VERSION and TERRAFORM_DOCS_VERSION pinned at the top of the file. There is no security scanner: no checkov, tfsec or trivy anywhere in the tree. The same hook collection offers terraform_checkov, so the agent adds the scanner where the other checks live rather than as a separate workflow.

It then runs Checkov once on everything to see what it will say before deciding anything. The root module declares aws_vpc, aws_default_security_group, aws_default_vpc, aws_flow_log in vpc-flow-logs.tf and seven aws_subnet resources, and the module's defaults matter to the result: enable_flow_log defaults to false, so CKV2_AWS_11, which wants an aws_flow_log connected to each VPC, fires on a module that only creates one when asked; manage_default_security_group defaults to true with empty ingress and egress lists, which is what CKV2_AWS_12 wants; map_public_ip_on_launch defaults to false, so CKV_AWS_130 on the public subnets passes; and aws_default_vpc, which exists for the manage-default-vpc example, trips CKV_AWS_148 by its presence. The thirteen directories under examples/ and the wrappers/ directory are scanned too, since the workflow visits them.

Each finding gets one of two treatments, written down. A finding that reflects a real default the maintainers chose, such as flow logs being opt-in for a reusable module, is skipped with an inline #checkov:skip=CKV2_AWS_11: comment carrying the reason, on the resource it applies to, so the next reader sees why. A finding a change can fix without altering the module's behaviour is fixed. A .checkov.yml at the root sets quiet: true, framework: terraform and the skip-path for .terraform directories, and the terraform_checkov hook is added to .pre-commit-config.yaml with --args=--quiet and --args=--config-file=.checkov.yml, so a developer running pre-commit run -a, as the contributing guide asks, and the CI job see the same result.

The CI side needs one more line. The pre-commit workflow installs tflint and terraform-docs at pinned versions; Checkov is a Python package, so the agent adds a pip install checkov==<version> step in the same style, pinned with a CHECKOV_VERSION variable at the top beside the other two. It runs pre-commit run -a locally with the new hook, confirms terraform_fmt, terraform_docs and terraform_validate still pass unchanged, and confirms the README's generated inputs and outputs tables, 236 variables and 119 outputs, are untouched because no variable changed.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add Checkov scanning to this Terraform module's pre-commit hooks and CI. Read .pre-commit-config.yaml, .github/workflows/pre-commit.yml, .github/contributing.md, versions.tf, variables.tf, outputs.tf, main.tf, vpc-flow-logs.tf, the examples/ and wrappers/ directories and .gitignore first. Install checkov and run it once over the whole repository with the terraform framework; list every finding by check id, resource and file. For each, either fix it without changing the module's behaviour or defaults, or add an inline checkov:skip comment on the resource with a one-line reason; never skip a check globally. Add a .checkov.yml with quiet, framework terraform and skip-path for .terraform directories. Add the terraform_checkov hook from antonbabenko/pre-commit-terraform to .pre-commit-config.yaml with --args=--quiet and --args=--config-file=.checkov.yml. In the pre-commit workflow, install checkov with pip at a pinned version set in a CHECKOV_VERSION variable beside TFLINT_VERSION and TERRAFORM_DOCS_VERSION. Run pre-commit run -a and confirm every hook passes and the README tables are unchanged. Open a pull request with the finding table, the treatment of each, and the pre-commit output.",
  "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 on its own branch that adds .checkov.yml, adds one hook entry to .pre-commit-config.yaml, adds a CHECKOV_VERSION variable and an install step to .github/workflows/pre-commit.yml, and adds inline skip comments with reasons to the handful of resources whose findings reflect deliberate defaults. variables.tf, outputs.tf and the generated README tables are unchanged, which the description states first, because a module's inputs are its contract.

The description carries a table of every finding Checkov reported: check id, its name as Checkov prints it, the resource and file, and the treatment, fixed with the diff hunk or skipped with the reason that is now in the comment. It quotes the pre-commit run -a output with every hook passing, including the new one, so the reviewer can see the branch is green under the same command CI runs.

Before merging, a reviewer reads each skip reason and decides whether they agree it is a deliberate default, and whether the examples should set enable_flow_log = true to show the compliant shape. A follow-up on the same session can make that change to examples/complete without starting over.

Run it on every module you maintain

This is a change you want done the same way across every module: a POST /o/{org}/sessions with this prompt and one repository in resources, sent from the terminal for each module, one run per repository. Each run reads that module's own hooks, defaults and findings and opens its own pull request, and the laptop is free the whole time. The sandbox parks with its disk when the turn ends, so a follow-up such as also add terraform_trivy with the same treatment wakes it with Checkov installed and the findings already triaged.

With a webhook URL on the API key, Rush posts run.completed or run.failed with the session_url for each run as it finishes, so the pull request links collect in one place instead of in ten browser tabs.

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

Why run it on Rush?

A scanner is easy to add and hard to add well: the first run reports findings, and someone has to read each one against the module's defaults and write down why it stays. The agent does that reading in its own sandbox, with Checkov's output, the variables file and the examples in front of it, and every decision is in the run's record beside the command that produced the finding.

The record is also what keeps the skips honest. The transcript shows the agent running Checkov before any change, checking each flagged default in variables.tf, and choosing an inline skip with a reason over a global one. A reviewer who disagrees with one skip can say so in a follow-up and the parked sandbox fixes that resource with the hook already in place.

Frequently asked questions

Why pre-commit instead of a separate workflow?

Because the module already runs fmt, docs, tflint and validate through pre-commit, both locally and in the pre-commit.yml workflow, and the contributing guide tells contributors to run pre-commit run -a. Adding terraform_checkov there means one command gives the same answer on a laptop and in CI.

Will it change the module's defaults to satisfy Checkov?

No. A reusable module's defaults are its contract, and flow logs being opt-in is a choice the maintainers made. Findings that reflect such choices are skipped inline with a reason on the resource; only findings a change can fix without altering behaviour are fixed.

Does a skip hide the check everywhere?

No. An inline checkov:skip comment applies to the one resource it sits on and names the check id and reason, so a new resource added later is still scanned. The agent is told never to skip a check globally in .checkov.yml.

How is the Checkov version pinned?

With a CHECKOV_VERSION variable at the top of the pre-commit workflow, beside TFLINT_VERSION and TERRAFORM_DOCS_VERSION, used by a pip install step. Checkov ships on PyPI rather than as a release binary, so the hook collection cannot pin it itself.

Will the examples and wrappers be scanned too?

Yes. The workflow visits every directory with Terraform files, so examples/ and wrappers/ get the hook as well, and their findings are triaged in the same table. An example that shows a compliant configuration can be adjusted in a follow-up if the maintainers want it.

More Terraform jobs

More jobs like this: Hand off a long task

Keep reading