alphacrack/iac-scanner

# IaC Scanner [](https://pypi.org/project/iac-scanner/) [](https://pypi.org/project/iac-scanner/) [](https://github.com/alphacrack/iac-scanner/actions/workflows/ci.yml) [](https://github.com/alphacrack/iac-scanner/actions/workflows/codeql.yml) [](https://securityscorecards.dev/viewer/?uri=github.com/alphacrack/iac-scanner) [](LICENSE) [](https://developercertificate.org/) Python CLI 工具，用于扫描 Terraform 和 AWS CDK 的基础设施即代码，报告安全与最佳实践发现的潜在问题，并**直接生成修复代码**。支持在本地运行、无密钥运行，或由 Checkov 提供基础保障。 iac-scanner **补充**了像 Checkov、tfsec 和 KICS 这样基于规则的扫描器——它并非要替代它们。它的核心差异在于能够在发现问题的同时提供 **AI 生成的修复方案**，并支持通过 GitHub Models、Ollama 或 MCP server 进行无密钥操作。 **许可证：**[Apache License 2.0](LICENSE)。 ## 快速开始（30 秒，零成本） 请根据您的环境选择最适合的方式： ### GitHub Models（对所有 GitHub 用户免费） ``` pip install iac-scanner export GITHUB_TOKEN=$(gh auth token) iac-scan scan ./my-tf --provider github -o ./out ``` ### Ollama（完全本地、离线、免费） ``` pip install iac-scanner[local] ollama pull qwen2.5-coder:7b-instruct # first run only iac-scan scan ./my-tf --provider ollama -o ./out ``` ### MCP server —— 通过 Claude Desktop / Cursor 驱动 ``` pip install iac-scanner[mcp] # 添加至 ~/Library/Application Support/Claude/claude_desktop_config.json: # "mcpServers": { "iac-scanner": { "command": "iac-scan-mcp" } } # 然后在 Claude 中："Scan the Terraform in ~/work/infra" ``` ### OpenAI / Anthropic（自带 API key） ``` pip install iac-scanner export OPENAI_API_KEY=sk-... iac-scan scan ./my-tf --provider openai -o ./out # 或者： iac-scan scan ./my-tf --provider auto (依次选择 ollama → github → openai → anthropic) ``` ### 无网络演示（无 AI，仅解析） ``` iac-scan scan ./samples/tf -o ./out --scan-only ``` 每种模式都会生成 `scan-report.json`（包含发现的问题），并在启用 AI 时生成 `fixed/`（包含修复后的代码）。 ## 输入 (CLI) - **Terraform**：包含 `main.tf` 的目录，或指向 `main.tf` 文件本身的路径。同级的 `.tf` 文件也会被包含在内。 - **CDK**：包含 `index.ts`/`index.js` 的目录，或指向该文件的路径。`lib/` 和 `bin/` 子目录也会被包含在内。 ### 自动跳过的内容 `terraform.tfstate*`, `*.tfvars`, `.env*`, `*.pem`, `*.key`, `id_rsa*`, `.terraform/`, `node_modules/`, `cdk.out/`。有关完整的跳过列表和威胁模型，请参阅 [SECURITY.md](SECURITY.md)。 ## 处理流程 1. **工厂模式** 根据给定的路径创建正确的扫描器（`TerraformScanner` 或 `CdkScanner`）。 2. **扫描**：加载入口文件，应用跳过列表，对明显的密钥进行脱敏处理，并强制执行 200 KB 的输入大小限制。 3. *（可选）* **规则引擎预处理**（`--rules-engine=checkov`）添加带有 CWE/CIS/NIST 标签的框架映射发现。 4. **分析**（LLM，结构化输出）：以 Pydantic 验证的 JSON 数组形式输出发现的问题，包含严重程度和位置信息。 5. **修复**（LLM，文本输出）：重新生成修复后的代码，并强制添加 `AI-generated — review before applying`（AI 生成——应用前请审查）的横幅。 6. **输出**：JSON 和/或 SARIF 2.1.0 报告；修复后的文件位于 `fixed/` 目录下。 ## 输出 - **JSON 报告**（`scan-report.json`）：包含 `iac_type`、`entry_path`、`findings`、`metadata`、`provider`、`analysis_model`、`fix_model`、`prompt_version`。 - **SARIF 2.1.0**（`--format sarif|both`）：可供 GitHub Code Scanning、GitLab Security Dashboards、SonarQube 使用。 - **修复后的代码**（`fixed/`）：多文件输出保留原始布局；每个文件开头都带有 AI 生成的横幅。 ## 使用说明 ``` # 基础扫描（分析 + 修复） iac-scan scan ./my-tf-dir # 仅无 AI 解析（无需密钥） iac-scan scan ./my-tf-dir --scan-only # 仅输出发现，跳过修复生成 iac-scan scan ./my-tf-dir --no-fix # 为 GitHub Code Scanning 输出 SARIF iac-scan scan ./my-tf-dir --format sarif -o ./out # 或者同时执行两者 iac-scan scan ./my-tf-dir --format both -o ./out # 显式选择 provider iac-scan scan ./my-tf-dir --provider github iac-scan scan ./my-tf-dir --provider ollama iac-scan scan ./my-tf-dir --provider openai # 使用 Checkov 规则发现来为 LLM 提供 Ground（hybrid mode） pip install iac-scanner[rules] iac-scan scan ./my-tf-dir --rules-engine checkov # CI gate：遇到任何 HIGH 或 CRITICAL 发现时以非零状态退出 iac-scan scan ./my-tf-dir --fail-on high # Cost cap：如果预计的 LLM 成本超过 $0.50 则中止 iac-scan scan ./my-tf-dir --max-spend 0.50 # Force-refresh：为本次运行跳过响应缓存 iac-scan scan ./my-tf-dir --no-cache ``` ## 环境变量 | 变量 | 用途 | |-----------------------|-------------------------------------------------------------------------------------------| | `IAC_PROVIDER` | `openai` \| `anthropic` \| `github` \| `ollama`（覆盖自动检测）。 | | `OPENAI_API_KEY` | 当使用 `--provider=openai` 时必填。 | | `ANTHROPIC_API_KEY` | 当使用 `--provider=anthropic` 时必填。 | | `GITHUB_TOKEN` | 当使用 `--provider=github` 时必填。支持任何 `gh auth` token（免费层级可用）。 | | `OLLAMA_HOST` | Ollama 端点。默认：`http://localhost:11434`。 | | `IAC_ANALYSIS_MODEL` | 覆盖默认的分析模型（例如 `gpt-4o`、`claude-3-5-sonnet-20241022`）。 | | `IAC_FIX_MODEL` | 覆盖默认的修复模型。 | | `IAC_MAX_SPEND_USD` | 每次运行的硬性消费上限。如果预计成本超过此值，则中止运行。 | | `IAC_MAX_INPUT_BYTES` | 输入大小上限（默认 200 KB，下限为 1 KB，上限为 10 MB）。 | | `IAC_NO_CACHE` | 设置后，将跳过基于内容寻址的响应缓存。 | | `IAC_NO_REDACT` | 禁用密钥脱敏（不推荐——参阅 SECURITY.md）。 | | `IAC_CACHE_DIR` | 覆盖缓存目录（默认为 `~/.cache/iac-scanner/`）。 | | `IAC_OUTPUT_FORMAT` | 默认输出格式（`json` \| `sarif` \| `both`）。 | ## 安装 ``` # 基础安装 — 包含 OpenAI 和 Anthropic providers + GitHub Models pip install iac-scanner # 包含可选 extras pip install iac-scanner[local] # Ollama local-LLM provider pip install iac-scanner[mcp] # MCP server mode for Claude Desktop / Cursor pip install iac-scanner[rules] # Checkov hybrid mode pip install iac-scanner[all] # all of the above # 从源码 git clone https://github.com/alphacrack/iac-scanner cd iac-scanner pip install -e ".[dev]" ``` ## 博客与教程 文章和分步教程已发布在 **GitHub Pages** 上：`https://alphacrack.github.io/iac-scanner/`。源码位于 [docs/](docs/)。 ## 治理与支持 - **[GOVERNANCE.md](GOVERNANCE.md)** —— 角色、决策机制、分支保护策略。 - **[MAINTAINERS.md](MAINTAINERS.md)** —— 官方维护者列表。 - **[SUPPORT.md](SUPPORT.md)** —— 提问、提交 bug 报告和功能请求的渠道。 - **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** —— Contributor Covenant 2.1。 ## 安全 有关威胁模型（prompt 注入、密钥泄露、幻觉修复、供应链、成本滥用）和私下披露渠道，请参阅 **[SECURITY.md](SECURITY.md)**。 ## 项目结构 ``` src/iac_scanner/ cli.py # CLI entry (click) factory.py # create_scanner(path) → TerraformScanner | CdkScanner models.py # Pydantic: Finding, FindingsList, ScanReport, VerificationResult cache.py # content-addressed SHA-256 response cache cost.py # tiktoken preflight + IAC_MAX_SPEND_USD enforcement mcp_server.py # iac-scan-mcp entry — MCP server for host LLMs scanners/ base.py # IacScanner (abstract), ScanResult _filters.py # skip-list, secret redaction, input size cap terraform.py # TerraformScanner (main.tf) cdk.py # CdkScanner (index.ts / index.js) llm/ providers.py # LLMClient + OpenAI / Anthropic / GitHub Models / Ollama orchestration/ tasks.py # analysis + fix LangChain tasks (structured output, XML fencing) runner.py # run_pipeline: scan → cache → cost check → LLM → result hybrid.py # rule-pre-pass + LLM augment + dedupe rules/ engine.py # rule-engine dispatcher checkov.py # Checkov subprocess adapter with CWE/CIS/NIST mapping output/ report.py # write_report_and_fixes — JSON + fixed/ banner sarif.py # SARIF 2.1.0 emitter ```

标签：AI智能体, AI风险缓解, ECS, IaC扫描, Python CLI, Terraform, 图数据库, 成本分析, 逆向工具