iac-scanner: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this project is

iac-scanner is a Python CLI (iac-scan) and MCP server (iac-scan-mcp) that scans Terraform (main.tf) and AWS CDK (index.ts/index.js) IaC, then uses an LLM to both generate findings (structured output) and produce fixed code. It is AI-augmented, not rule-only — it complements Checkov/tfsec/KICS rather than replacing them. Version is derived from git tags (signed vX.Y.Z) by setuptools-scm; pyproject.toml has dynamic = ["version"] and no hardcoded version. The package reads the version from _version.py (written at build time) or falls back to importlib.metadata.

Commands

# Setup
pip install -e ".[dev]"             # editable install + dev deps
pre-commit install                  # ruff + bandit + gitleaks + hygiene

# Test
pytest tests/ -m "not e2e"          # fast suite (mocked LLM, no keys)
pytest tests/ -m smoke              # CLI end-to-end smoke
pytest tests/ -m e2e                # opt-in: real provider APIs, needs keys
pytest tests/test_runner.py -v      # single file
pytest tests/test_runner.py::test_name  # single test
pytest tests/ --cov=iac_scanner     # coverage (CI threshold 80%, target 90%)

# Lint / type / security
ruff check src/ tests/              # lint
ruff format src/ tests/             # format
mypy src/iac_scanner                # CI hard-fails on any issue (strict mode)
bandit -r src/ -ll -c pyproject.toml
pip-audit

# Version + release (tag-driven, setuptools-scm)
make version                                # print version setuptools-scm would emit
make release-dry                            # preview a patch release
make release-patch | release-minor | release-major   # promote CHANGELOG + signed tag
# then: git push --follow-tags origin <branch>   # tag push → GitHub Release → PyPI publish

Make targets mirror most of the above (make test, make lint, make check, make build).