Terraform security scanning in GitHub Actions

The zero-config path: the GitHub App

Before you write a workflow, know that you may not need one. The audytx GitHub App reviews every pull request on install — no Actions file, no token to store. It reads your .tf/.tfvars files, runs the whole engine, posts one comment with the findings and their suppression rationales, adds inline annotations, and uploads a SARIF document to GitHub Code Scanning so findings show in the Security tab.

A hard gate in GitHub Actions

To block a merge on a High or Critical finding, add a workflow that calls the audytx MCP API and fails the job on the result. This needs a free Client ID — store it as the repository secret AUDYTX_CLIENT_ID. The workflow bundles your Terraform, POSTs one JSON-RPC call, and exits non-zero when the severity summary crosses your threshold:

name: audytx Terraform security gate
on: [pull_request]
permissions:
  contents: read
jobs:
  audytx:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Scan Terraform with audytx
        env:
          AUDYTX_CLIENT_ID: ${{ secrets.AUDYTX_CLIENT_ID }}
        run: |
          # Bundle every .tf/.tfvars file into one JSON-RPC request.
          # Pass the whole tree — cross-resource reasoning needs it.
          req=$(find . \( -name '*.tf' -o -name '*.tfvars' \) -print0 \
            | xargs -0 -I{} jq -n --arg p "{}" --rawfile c "{}" \
                '{path:$p, content:$c}' \
            | jq -s '{jsonrpc:"2.0", id:1, method:"tools/call",
                      params:{name:"scan_terraform", arguments:{files:.}}}')

          resp=$(curl -sf https://audytx.com/mcp \
            -H "Content-Type: application/json" \
            -H "X-Client-ID: $AUDYTX_CLIENT_ID" --data "$req")

          # List the High/Critical findings for the log …
          echo "$resp" | jq -r '.result.structuredContent.findings[]
            | select(.severity=="CRITICAL" or .severity=="HIGH")
            | "\(.severity)  \(.rule_id)  \(.file):\(.line_start)  \(.title)"'

          # … then fail the build if any exist.
          gate=$(echo "$resp" \
            | jq '.result.structuredContent.summary | .critical + .high')
          if [ "$gate" -gt 0 ]; then
            echo "::error::audytx found $gate High/Critical AWS security findings"
            exit 1
          fi

The response carries a summary block (critical/high/medium/low counts) and a findings array with rule_id, severity, file, line_start, and remediation — the same contract the docs describe. Move the gate to .critical alone for a looser policy, or add .medium for a stricter one.

Resolved-value precision with a plan upload

Static parsing can't resolve values behind variables, count/for_each expansion, or resources inside modules. If you want findings computed against the resolved plan, add the plan-upload workflow. It authenticates with the run's GitHub OIDC token — no secret to store — runs terraform show -json, and POSTs the plan so audytx re-scans with final values folded in. It's strictly additive: the normal scan keeps working with or without it.

The full workflow and its permissions: id-token: write block are documented on the plan-scanning page. Pair it with either level above.

The same gate for CloudFormation

Building CloudFormation instead of Terraform? The MCP gate works unchanged — audytx normalizes stack templates into the same resource model and returns the same response shape. Point find at your templates and call scan_cloudformation:

          req=$(find . \( -name '*.yaml' -o -name '*.yml' -o -name '*.json' \) -print0 \
            | xargs -0 -I{} jq -n --arg p "{}" --rawfile c "{}" \
                '{path:$p, content:$c}' \
            | jq -s '{jsonrpc:"2.0", id:1, method:"tools/call",
                      params:{name:"scan_cloudformation", arguments:{files:.}}}')

Common questions