tf-analyze

Static + plan-time Terraform analysis with attack-graph prioritisation, MITRE ATT&CK mapping, and one-click PR fix suggestions. Drop into CI in under 5 minutes.

Quickstart · Why tf-analyze? · Features · Integrations · Screenshots · Documentation · Adding a rule · Demo corpora · Repo layout · Contributing · Provenance · License

Same engine, ten surfaces — Claude Code skill, Python CLI, GitHub Action, Docker, pre-commit hook, LSP server, VS Code extension, HCP Run Task, MCP server for AI agents, native Terraform provider. Pick the one that fits your workflow; the rule catalogue, score, and fix_hcl are identical across all of them.

Hardening = ROB-* + STK-*; Ops & Reuse = OPS-* + COST-* + MOD-* + MOD-REUSE-* + INT-* + CI-* + STYLE-*. Full per-family breakdown and shape-by-cloud commentary in Detection ↓.

docker run --rm -v "$(pwd):/workspace" \
  ghcr.io/chrisadkin8/tf-analyze \
  --target /workspace --format html > report.html
open report.html

git clone https://github.com/ChrisAdkin8/tf-analyze.git
cd tf-analyze
./install.sh                                          # installs as a Claude Code skill
pip install python-hcl2                               # optional fast-path (default-on if present)

python3 scripts/detect.py --target /path/to/terraform
python3 scripts/detect.py --target . --mode diff --fail-on HIGH --format sarif > out.sarif
python3 scripts/detect.py --list-rules
python3 scripts/detect.py --explain SEC-AWS-IAM-POLICY-005

/tf-analyze                                # full audit, all areas
/tf-analyze focus:security mode:diff       # PR review
/tf-analyze mode:verify-fixed              # confirm prior fixes

Live diagnostics, Quick Fix, attack graph, Module Reuse Advisor, and a vscode:// URI handler — all from a self-contained .vsix (the engine and rule catalogue are bundled; no companion repo to clone).

# Marketplace (preferred, once the listing is live)
code --install-extension tfanalyze.tf-analyze

# Or from a downloaded .vsix (current path until the Marketplace listing publishes)
code --install-extension tf-analyze-0.1.57.vsix

Open any Terraform workspace and the six status-bar shortcuts appear bottom-left:

🛡 tf-analyze: 82 (B) · 7 findings   🛤 Attack Graph   🔀 Delta   ✅ Compliance   🪄 Remediate   📦 Module Reuse

To see the deeper panels render against rich input, open one of the showcase corpora in examples/ — examples/module-reuse-demo/ (📦) or examples/attack-graph-demo/ (🛤). Full reference: docs/vscode-extension.md.

- uses: ChrisAdkin8/tf-analyze@v1
  with:
    fail-on: HIGH
    post-pr-comment: true                # inline `suggestion` blocks on every PR
    compliance-framework: owasp_iac      # optional — adds a collapsible compliance gap report
    attack-graph: true                   # optional — embeds Mermaid attack graph in PR summary
    ref: v0.2.6                          # optional — shorthand for image tag (default: :latest)

ref: is a convenience alias — ref: v0.2.6 is equivalent to image: ghcr.io/chrisadkin8/tf-analyze:0.2.6 (the leading v is stripped before building the docker tag, since docker/metadata-action publishes semver tags without it). Both v0.2.6 and 0.2.6 work; non-semver values like main or latest pass through untouched. Set ref: or image:, not both. See action.yml for the full input reference, and integrations/github-action.yml for an alternative install-from-source workflow that adds SARIF upload + HTML artefact.

A scanner is only as good as the actions it provokes. Where comparable tools stop at "here is a finding", tf-analyze ranks findings by attack-path centrality, ships an HCL fix, and surfaces the adversarial scenario on hover.

1. Attack-path graph + fix centrality — BFS from internet-reachable resources to crown jewels. Findings on the critical path are promoted one urgency tier; fixes are ranked by how many crown jewels each one unblocks.
2. fix_hcl on every rule, with disruption classification — every finding ships an HCL snippet plus a Non-disruptive / Plan required / Forces replacement badge, so reviewers see operational impact before applying.
3. Adversarial scenario narratives — HIGH/CRITICAL findings come with a 3–4 sentence breach story (Capital One, Accenture, SolarWinds) to anchor severity in real outcomes.
4. IAM policy analysis (HCL + inline JSON) — ten dedicated rules walking both data "aws_iam_policy_document" blocks AND policy = jsonencode({...}) strings on aws_iam_policy / aws_iam_role_policy. Covers wildcard action, wildcard resource, public principal, iam:* privesc, full-admin, NotAction.
5. Baseline ratcheting — adopt on a noisy legacy repo by snapshotting today's findings; only regressions block CI thereafter.
6. Kubernetes + Helm coverage — kubernetes_namespace Pod Security Admission, missing kubernetes_network_policy, cluster-admin RoleBindings, plus helm_release overrides like service.type=LoadBalancer and securityContext.privileged=true.
7. Provider-version-aware — rules can declare applies_when: { min_provider: { aws: "5.0" } } so they self-skip on older provider versions instead of false-positiving.
8. Policy-as-code DSL (kind: policy) — author cross-resource, conditional, and aggregate rules as catalogue data (e.g. "every S3 bucket must have an aws_s3_bucket_logging"), without writing Python or vendoring Rego. A small, safe predicate language over the parsed resource model; findings flow through the same ID/urgency/SARIF/score/suppression pipeline. See docs/policy-dsl.md.

353 rules across six families. --list-rules enumerates them; --explain RULE-ID prints one in full.

Per-cloud breakdown (numerical parity across AWS, GCP, Azure as of 2026-05-13):

Why the per-section shapes differ at the same headline count. Each cloud puts services in different boxes, and the catalogue follows the provider taxonomy rather than forcing a synthetic split:

• AWS skews SEC (62) because more discrete services have their own dedicated security rule — KMS, ECR, CloudTrail, GuardDuty, Security Hub, MSK, Neptune, DocDB, Athena, Cognito, Kinesis, SNS, SQS, Secrets Manager, SSM. Each surfaces a distinct misconfiguration class that maps 1:1 to a rule.
• GCP skews STK (42) because GCP rolls multi-feature platforms (GKE, Cloud Run, Cloud SQL, BigQuery, Composer, Dataproc) where hardening is expressed as stack-level configuration (release channels, workload identity, binary authorization, IAM auth flags, CMEK on the platform) rather than per-service SEC-* rules.
• Azure skews SEC (56) because Azure's policy / Defender / Synapse / Databricks story exposes many fine-grained controls (auth_settings_v2, microsoft_defender, data_exfiltration_protection_enabled, oms_agent, vault per-resource diagnostic settings, federated-identity-credential subjects) that each get their own rule. App-Service / Functions / Event Grid / Search platform hardening goes under STK (25).
• ROB is small everywhere (13 / 5 / 7) because lifecycle and backup gaps map onto a small set of stateful resource shapes per cloud (RDS / Cloud SQL / Azure SQL + Cosmos + VMSS).
• OPS / COST / MOD-REUSE are deliberately 1-2 each per cloud — these tier-INFO/MEDIUM rules are about workflow ergonomics, not service depth, so one well-curated rule per cloud beats many redundant ones.

The headline number is parity. The shape is a property of each provider's product surface.

Every text, JSON, and HTML scan emits a deterministic 0–100 health score and letter grade A/B/B-/C/D/F. The score is the same number SKILL.md describes — _RISK_WEIGHTS and _GRADE_TIERS in scripts/detect.py are the single source of truth.

# tf-analyze: 82 (B) · 0 CRITICAL · 0 HIGH · 4 MEDIUM · 6 LOW · 0 INFO

"summary": {
  "scoring_version": 1,
  "score": 82,
  "grade": "B",
  "counts": {"CRITICAL": 0, "HIGH": 0, "MEDIUM": 4, "LOW": 6, "INFO": 0},
  "suppressed_count": 0,
  "formula": "max(0, floor(100 - sum(weight * count))); weights: CRITICAL=15, HIGH=7, MEDIUM=3, LOW=1, INFO=0; suppressed at half weight"
}

Suppressed and baseline-suppressed findings count at half weight (acknowledged, but the underlying risk still exists). INFO findings carry weight 0. The scoring_version field pins the formula — weight changes bump it so downstream gates can detect breakage. CI gates use --fail-on LEVEL (the urgency tier) rather than gating on the grade, intentionally — the grade is for trend visibility, not pass/fail.

Full CLI reference: docs/cli.md.

Findings tab — urgency-badged, collapsible, with adversarial narrative + suggested fix	Attack Graph — interactive force-directed SVG; critical path in red, crown jewels gold-bordered
Executive View — findings reorganised into Entry Points / Lateral Movement / Crown Jewels / Blind Spots	Fix Priority — findings ranked by attack-path centrality; CRITICAL-PATH and INET-REACHABLE badges

Additional screenshots: compliance report · fix-disruption badges · findings narrative panel.

When this repo is served via GitHub Pages (Settings → Pages → Deploy from branch: main / docs), the same content is reachable at https://chrisadkin8.github.io/tf-analyze/ with the blog at /blog/.

python3 scripts/detect.py --new-rule SEC-MYDOMAIN-001
# wrote catalog/SEC-MYDOMAIN-001.yaml
# wrote fixtures/sec_mydomain_001/main.tf

Edit the two scaffolded files (TODO markers throughout), then run:

python3 -m pytest tests/test_fixtures.py -k sec_mydomain_001
python3 scripts/detect.py --explain SEC-MYDOMAIN-001
python3 scripts/detect.py --strict-catalog --target /tmp        # validates schema

Catalogue schema: catalog/README.md. Custom-rule walkthrough: docs/custom-rules.md.

Three corpora that double as engine smoke tests and end-to-end demos for the surfaces that do graph reasoning across multiple resources. See examples/README.md for the chooser.

python3 scripts/detect.py --target examples/terragoat --format html > demo.html

The single-rule fixtures under fixtures/ (239 positive + 146 clean) complement these corpora — they isolate one rule each so a self-test failure points at exactly which detector broke. Drift on the demo corpora is gated by tests/test_examples_demos.py so a catalogue change that shifts the documented finding counts fails the local pytest run instead of silently breaking the README screenshots.

.
├── SKILL.md                    # Skill prose loaded as /tf-analyze in Claude Code
├── README.md                   # This file
├── CHANGELOG.md                # Per-round release notes
├── TODO.md                     # Roadmap and backlog
├── CONTRIBUTING.md
├── LICENSE                     # MPL-2.0
├── Dockerfile                  # ghcr.io/chrisadkin8/tf-analyze
├── pyproject.toml
├── install.sh                  # Symlinks repo into ~/.claude/skills/tf-analyze
├── .pre-commit-hooks.yaml      # pre-commit.com hook declaration
├── .github/workflows/          # CI (ci.yml, docker.yml)
├── catalog/                    # 343 rule definitions (one YAML per rule)
│   └── README.md               # Schema reference
├── fixtures/                   # 239 positive + 146 clean (negative) fixtures
├── examples/                   # Showcase corpora
│   ├── terragoat/              #   • Multi-cloud deliberately-vulnerable corpus
│   ├── module-reuse-demo/      #   • Module Reuse Advisor showcase (3 clouds)
│   └── attack-graph-demo/      #   • Multi-tier AWS app for the Attack Graph
├── scripts/
│   ├── detect.py               # Detection engine orchestrator (~3,000 LoC after R30.15 split)
│   ├── _handlers_*.py          # 51 detector handlers in 5 topic modules (generic / security /
│   │                           #   robustness / modules / infra) — registered into the engine
│   │                           #   by side-effect import
│   ├── _hcl.py                 # HCL-parsing primitives (find_blocks, brace_walk, …)
│   ├── _lsp.py                 # `--lsp` server entry point
│   ├── _attack_graph.py        # Attack-graph BFS + Mermaid render
│   ├── _blast_radius.py        # Blast-radius graph walker
│   ├── self_test.py            # Walks fixtures/ vs catalog/, asserts expected IDs
│   ├── test_schema.py          # Catalogue schema regression tests
│   ├── stub-status.py          # Reports stale `status: stub` entries
│   ├── gen-cli-docs.py         # Regenerates docs/cli.md from argparse
│   ├── gen_clean_fixtures.py   # Auto-scaffolds clean fixtures from fix_hcl
│   └── apply_mitre.py          # Idempotent MITRE ATT&CK mapper
├── tests/                      # pytest suite (872 passing, 2 skipped)
├── docs/                       # User-facing documentation
├── integrations/
│   ├── github-action.yml
│   ├── pre-commit-hook.yaml
│   └── run-task/               # HCP Terraform Run Task FastAPI server + Dockerfile
├── vscode-extension/           # TypeScript extension (Quick Fix, attack-graph webview)
├── demo/                       # FastAPI + d3 web demo (deployable to Fly.io)
├── reports/                    # Example report outputs (delta-tracking demos)
└── assets/                     # Banner, icon

The skill files (SKILL.md, catalog/, scripts/, fixtures/, integrations/) live at the repo root so ./install.sh can ln -s the whole directory into ~/.claude/skills/tf-analyze — no nested skill/ subdir.

Contributions welcome — see CONTRIBUTING.md for the workflow.

Versioning note for the VS Code extension: every reference to a specific tf-analyze-X.Y.Z.vsix filename in user-facing documentation (this README's integrations table, docs/vscode-extension.md, vscode-extension/README.md) must always match the latest vscode-extension/package.json#version. Historical references inside changelogs and archived planning docs are exempt — they intentionally pin to the artefact that shipped at that version. Full rules and the version-bump checklist live in CONTRIBUTING.md § VS Code extension version sync.

Routine maintenance commands:

python3 -m pytest tests/                        # Full suite (~45s)
python3 scripts/test_schema.py                  # Catalogue schema regression
python3 scripts/stub-status.py --age 90d        # Find stale stubs
python3 scripts/gen-cli-docs.py                 # Regenerate docs/cli.md after argparse changes
python3 scripts/gen_clean_fixtures.py --write   # Auto-scaffold clean fixtures from fix_hcl
python3 scripts/gen_sample_reports.py           # Regenerate reports/*.{md,json} from terragoat

CI gate (.github/workflows/ci.yml) runs the pytest suite, the schema validator, the CLI-docs freshness check, and stub-status.py --age 180d. The Docker image is built and published on tag pushes via .github/workflows/docker.yml.

Built and exercised inside an HCP Vault + Consul + GKE platform engineering project; many catalogue rules trace to real audit findings on that infra. The skill is provider-agnostic in design — see the per-cloud breakdown under Detection for the current split. Full CIS Foundations Benchmark coverage on GCP; growing parity on AWS and Azure. Compliance output covers CIS, PCI-DSS v4.0, SOC 2 Trust Services Criteria, and the OWASP IaC Cheat Sheet.

Mozilla Public License 2.0. Catalogue rules and fixtures are released under the same licence to permit upstream contributions and downstream forks.