leonamvasquez/terraview
GitHub: leonamvasquez/terraview
一个针对 Terraform plan 的安全分析工具，将静态扫描器与 AI 上下文分析并行运行，帮助团队在云基础设施交付前发现并修复安全风险。
Stars: 2 | Forks: 1
**选择您的语言：** [Português](README.md) | [English](README.en.md)
[](LICENSE)
[](https://golang.org)
[](https://github.com/leonamvasquez/terraview/releases/latest)
[](https://github.com/leonamvasquez/terraview/actions/workflows/ci.yml)
[](https://goreportcard.com/report/github.com/leonamvasquez/terraview)
[](https://codecov.io/gh/leonamvasquez/terraview)
[](https://slsa.dev)
[](https://scorecard.dev/viewer/?uri=github.com/leonamvasquez/terraview)
Terraview 是一个针对 Terraform plan 的安全分析工具，它将静态扫描器（Checkov、tfsec、Terrascan）与由 AI 执行的上下文分析结合在一起**并行**运行。
它会检查使用 Terraform 配置的基础设施，通过知名的开源扫描器检测安全和合规性配置错误，并在配置了 provider 时，自动通过 AI 多 provider 上下文分析来丰富结果。支持 Ollama、Gemini、Claude、OpenAI、DeepSeek、OpenRouter、Gemini CLI、Claude Code 以及任何通过 Custom provider 兼容 OpenAI 的 API。
Terraview 以单一二进制文件运行，无外部依赖。当配置了 AI provider 时，扫描器和 AI 会自动并行运行。使用 `--static` 可仅运行扫描器，不启用 AI。
## 目录
- [功能](#funcionalidades)
- [示例](#exemplos)
- [快速开始](#início-rápido)
- [安装](#instalação)
- [更新](#atualização)
- [Shell 补全](#shell-completions)
- [用法](#uso)
- [Scan](#scan)
- [Status](#status)
- [Fix](#fix)
- [Diagram](#diagram)
- [Explain](#explain)
- [History](#history)
- [MCP Server](#mcp-server)
- [Provider 管理](#gerenciamento-de-providers)
- [Scanner 管理](#gerenciamento-de-scanners)
- [AI 缓存](#cache-de-ia)
- [输出格式](#formatos-de-saída)
- [配置](#configuração)
- [安全扫描器](#scanners-de-segurança)
- [AI Provider](#providers-de-ia)
- [基于订阅的 AI 集成](#integração-com-ia-por-assinatura)
- [CI/CD 集成](#integração-cicd)
- [Docker](#docker)
- [架构](#arquitetura)
- [开发](#desenvolvimento)
- [贡献](#contribuindo)
- [免责声明](#aviso)
- [支持](#suporte)
- [许可证](#licença)
## 功能
- **安全扫描器** — 自动集成 Checkov、tfsec 和 Terrascan；自动检测已安装的程序并运行，无需配置
- **AI 上下文分析（默认）** — 当配置了 AI provider 时，AI 会与扫描器**并行**运行，分析跨资源关系、依赖链和静态扫描器无法检测到的架构反模式
- **多 Provider AI** — 三个类别：
- **API**：Ollama（本地）、Google Gemini、Anthropic Claude、OpenAI、DeepSeek 和 OpenRouter
- **CLI（订阅）**：Gemini CLI 和 Claude Code — 使用您的个人订阅，无需 API key
- **Custom**：任何兼容 OpenAI 的 API（Grok/xAI、Groq、Mistral、Together AI、Fireworks 等）
- **发现结果抑制** — 通过 `.terraview-ignore` 文件永久抑制已接受的风险和误报，支持按规则、资源或来源（`--ignore-file`）进行 AND 逻辑范围限定
- **AI 修复建议** — `terraview fix plan`（dry-run）/ `terraview fix apply`（交互式或 `--auto-approve`）生成并应用修正后的 HCL，用于处理 CRITICAL/HIGH 级别的发现，具备验证、备份和 diff 预览功能
- **自动集成测试** — 通过 `provider list` 选择 provider 时，terraview 会测试连接性并按类型返回特定反馈（已安装 CLI、API key 有效、服务可访问）
- **冲突解决** — 扫描器 × AI：出现分歧时以扫描器为准（置信度 0.80）；一致时将置信度提升至 1.00
- **统一记分卡**，包含安全性、合规性和可维护性评分（0–10）
- **风险向量** — 从 5 个维度提取资源风险：网络暴露、加密、身份、治理和可观察性
- **ASCII 图表（AWS）** — 在终端中以拓扑视图展示基础设施，包括 VPC 嵌套、子网层级、连接箭头、安全组交叉引用、双向边、NAT/TGW/VPN 可视化节点以及资源聚合
- **通过 MCP 分析爆炸半径** — 通过 MCP tool `terraview_impact` 向 AI agent 暴露依赖影响分析
- **AI 解释** — 通过 `explain` 以自然语言解释您的基础设施
- **零配置** — 自动检测 Terraform 项目并执行 `init + plan + show`
- **扫描历史** — 通过 SQLite 进行跟踪，包含趋势迷你图、并排比较以及 CSV/JSON 导出
- **MCP Server** — 通过 `terraview mcp server` 使用 Model Context Protocol 与 AI agent（Claude Code、Cursor、Windsurf）集成
- **原生 CI/CD** — 语义化 exit codes（0/1/2）+ SARIF、JSON 和 Markdown 输出，适用于 GitHub Actions、GitLab CI 和 Azure DevOps
- **供应链加固** — 每个版本提供 SBOM（CycloneDX）、cosign 签名、SLSA Build Provenance Level 3
- **双语（en/pt-BR）** — 所有命令均可用 `--br` 标志
- **通过包管理器更新**（`brew upgrade terraview`、`scoop update terraview`、`apt upgrade terraview` 等）
- **别名 `tv`** — 安装时创建的符号链接；`tv scan` = `terraview scan`
- **持久化 AI 缓存到磁盘** — 对同一 plan 的重复执行可避免冗余的 API 调用（`cache status | clear`）
- **跨平台安装扫描器** — 通过 `terraview scanners install --all`（Linux、macOS、Windows）
## 示例
CLI 中的扫描输出
```
$ terraview scan checkov
══════════════════════
┌──────────────────────────────────────────────────────┐
│ Scorecard │
│ Segurança: 7.2 / 10 ████████░░ │
│ Compliance: 8.5 / 10 █████████░ │
│ Manutenibilidade: 9.0 / 10 █████████░ │
└──────────────────────────────────────────────────────┘
3 CRITICAL · 5 HIGH · 12 MEDIUM · 4 LOW
● [CRITICAL] aws_s3_bucket.data
✗ CKV_AWS_145 Criptografia não habilitada
✗ CKV2_AWS_61 Configuração de lifecycle ausente
● [HIGH] aws_security_group.web
✗ CKV_AWS_25 Ingress irrestrito na porta 22 (0.0.0.0/0)
✦ Análise IA (gemini-cli · paralelo)
Risco cross-resource: bucket S3 exposto via CloudFront sem
Origin Access Control — escalação de leitura pública possível.
$ terraview fix apply --severity CRITICAL
1 aws_s3_bucket.data → s3.tf
--- s3.tf (original)
+++ s3.tf (corrigido)
@@ -14,6 +14,12 @@
resource "aws_s3_bucket" "data" {
bucket = var.bucket_name
+
+ server_side_encryption_configuration {
+ rule {
+ apply_server_side_encryption_by_default {
+ sse_algorithm = "AES256"
+ }
+ }
+ }
}
Aplicar? [y/N]: y
✓ 1 arquivo corrigido · backup em s3.tf.tvfix.bak · terraform validate passou
```
设置输出
```
terraview setup
═══════════════
Scanners de Segurança
[✓] checkov 3.2.504
[✗] tfsec Instale com: terraview scanners install tfsec
[✗] terrascan Instale com: terraview scanners install terrascan
Providers de IA
[✓] ollama rodando (llama3.1:8b)
[✓] gemini-cli CLI gemini instalado
[✓] claude-code CLI claude instalado
[✗] gemini GEMINI_API_KEY não definida
[✗] claude ANTHROPIC_API_KEY não definida
IA pronta (2 providers disponíveis)
Início Rápido
terraview scan checkov # scanner + IA (default)
terraview scan checkov --static # somente scanner
Instalar o que falta: terraview scanners install --all
```
## 快速开始
### 前置条件
- Terraform >= 0.12
- 安装一个或多个扫描器（Checkov、tfsec、Terrascan）— terraview 可以为您安装它们
### 快速安装
```
curl -sSL https://raw.githubusercontent.com/leonamvasquez/terraview/main/install.sh | bash
```
### 配置 AI
```
terraview provider list # seletor interativo + teste de conectividade
```
### 首次扫描
```
cd meu-projeto-terraform
terraview scan checkov # scanner + IA (default quando provider configurado)
terraview scan checkov --static # somente scanner, sem IA
terraview status # findings do último scan com delta
```
## 安装说明
### 安装脚本（Linux、macOS、Windows WSL）
```
curl -sSL https://raw.githubusercontent.com/leonamvasquez/terraview/main/install.sh | bash
```
该脚本会自动检测您的操作系统和架构，从 GitHub Releases 下载正确的二进制文件并创建 `tv` 别名。
### Homebrew (macOS / Linux)
```
brew install leonamvasquez/terraview/terraview
```
### Scoop (Windows)
```
scoop bucket add terraview https://github.com/leonamvasquez/scoop-terraview.git
scoop install terraview
```
### APT — Debian / Ubuntu
```
# 添加 repository
curl -1sLf 'https://dl.cloudsmith.io/public/workspace-for-leonam/terraview/setup.deb.sh' | sudo bash
# 安装
sudo apt update
sudo apt install terraview
```
### Dnf / YUM — Fedora / RHEL / Amazon Linux
```
# 添加 repository
curl -1sLf 'https://dl.cloudsmith.io/public/workspace-for-leonam/terraview/setup.rpm.sh' | sudo bash
# 安装
sudo dnf install terraview
```
### Docker
```
docker pull leonamvasquez/terraview:latest
# 使用
docker run --rm -v $(pwd):/workspace leonamvasquez/terraview scan checkov
```
### Windows — PowerShell（直接运行脚本）
```
irm https://raw.githubusercontent.com/leonamvasquez/terraview/main/install.ps1 | iex
```
### 手动下载
```
# 将
, 和 替换为您的系统
# OS: linux, darwin, windows | ARCH: amd64, arm64
curl -Lo terraview.tar.gz https://github.com/leonamvasquez/terraview/releases/download//terraview--.tar.gz
tar -xzf terraview.tar.gz
sudo mv terraview /usr/local/bin/terraview
```
### 从源代码构建
```
git clone https://github.com/leonamvasquez/terraview.git
cd terraview
make install
```
编译二进制文件，安装到 `~/.local/bin/terraview`，创建符号链接 `tv` 并将提示词复制到 `~/.terraview/prompts/`。
## 更新
通过您的包管理器更新 Terraview：
```
# Homebrew
brew upgrade leonamvasquez/terraview/terraview
# Scoop
scoop update terraview
# APT
sudo apt update && sudo apt upgrade terraview
# DNF
sudo dnf upgrade terraview
```
## Shell 补全
```
# Bash
terraview completion bash | sudo tee /etc/bash_completion.d/terraview > /dev/null
source /etc/bash_completion.d/terraview
# Zsh (添加到 ~/.zshrc)
terraview completion zsh | sudo tee "${fpath[1]}/_terraview" > /dev/null
# Fish
terraview completion fish | source
# PowerShell (添加到您的 $PROFILE)
terraview completion powershell | Out-File $PROFILE -Append
```
配置完成后，重新打开终端并使用 `terraview ` 自动补全命令、标志和参数。
## 用法
```
$ terraview
Core Commands:
scan Scan de segurança + análise contextual por IA (paralelo)
status Mostra findings abertos do último scan
fix Correções geradas por IA (fix plan | fix apply)
diagram Gera diagrama ASCII da infraestrutura
explain Explicação da infraestrutura por IA
Provider Management:
provider Gerencia providers de IA e runtimes LLM
provider list | use | current | test
Scanner Management:
scanners Gerencia scanners de segurança
scanners list | install | default
Utilities:
cache Gerencia o cache de respostas de IA
cache status | clear
version Mostra informações de versão
setup Diagnóstico interativo do ambiente
Flags:
-d, --dir string Diretório do workspace Terraform (default ".")
-p, --plan string Caminho do plan JSON (gera automaticamente se omitido)
-f, --format string Formato de saída: pretty, compact, json, sarif
-o, --output string Diretório de saída para arquivos gerados
--provider string Provider de IA (ollama, gemini, claude, openai, deepseek, openrouter, gemini-cli, claude-code)
--model string Modelo de IA a ser usado
--br Saída em português do Brasil (pt-BR)
--no-color Desabilita saída colorida
-v, --verbose Habilita saída verbosa
```
### Scan
默认情况下，terraview 会**同时**并行运行安全扫描器和 AI 上下文分析。当配置了 provider 时（通过 `.terraview.yaml`、`--provider` 标志或 `terraview provider use`），AI 会自动激活。如果未配置任何 provider，则仅运行扫描器。
```
terraview scan # seleciona o scanner default
terraview scan checkov # scan com Checkov (+ IA se configurada)
terraview scan tfsec # scan com tfsec
terraview scan terrascan # scan com Terrascan
terraview scan checkov --static # somente scanner, desabilita IA
terraview scan checkov --plan plan.json # usa um plan JSON existente
terraview scan checkov -f sarif # saída SARIF para CI
terraview scan checkov --strict # findings HIGH também retornam exit code 2
terraview scan checkov --findings ext.json # importa findings externos Checkov/tfsec/Trivy
```
#### 指定目录或输入文件
扫描当前目录（自动检测 Terraform）：
```
terraview scan checkov
```
或扫描特定目录：
```
terraview scan checkov -d /caminho/para/meu-projeto
```
或手动生成 plan：
```
terraform init
terraform plan -out tf.plan
terraform show -json tf.plan > tf.json
terraview scan checkov --plan tf.json
```
使用 CLI provider（订阅 — 无需 API key）：
```
terraview scan checkov --provider gemini-cli --model gemini-3
terraview scan checkov --provider claude-code --model claude-sonnet-4-5
```
### Status
显示上次扫描的未解决发现及与前次扫描的差异。从持久化的 `LastScan` 中读取，因此不会重新运行扫描器。
```
terraview status # CRITICAL/HIGH + delta vs scan anterior
terraview status --all # inclui MEDIUM/LOW/INFO
terraview status --explain-scores # decomposição detalhada dos scores
```
### Fix
用于 AI 生成修复的父命令。读取上次扫描的发现并生成修正后的 HCL。`fix plan` 为 dry-run（仅显示 diff）；`fix apply` 默认为交互式（逐个确认 y/n）。
```
terraview fix plan # dry-run: preview dos diffs, não escreve nada
terraview fix apply # interativo: y/n por fix
terraview fix apply --auto-approve # aplica tudo sem prompts (CI/scripts)
terraview fix apply CKV_AWS_18 # apenas findings com este rule ID
terraview fix apply --severity CRITICAL # filtra por severidade
terraview fix apply --file vpc.tf # filtra por arquivo .tf
terraview fix apply --max 5 # limita a quantidade de fixes gerados
```
安全保障：大括号平衡的预检、按文件备份 `.tvfix.bak`、apply 后执行 `terraform validate`、验证失败时自动回滚。
### Diagram
从 Terraform plan 生成确定性的 ASCII 基础设施图表。不需要 AI。目前**仅支持 AWS**。
提供两种渲染模式：
- **topo**（默认） — 拓扑视图，包含 VPC 嵌套、子网层级、连接箭头、安全组交叉引用、双向边、NAT/TGW/VPN 可视化节点以及资源聚合
- **flat** — 基于层的简单视图
```
terraview diagram # diagrama do diretório atual (modo topo)
terraview diagram --plan plan.json # diagrama a partir de plan existente
terraview diagram --diagram-mode flat # visão flat baseada em camadas
terraview diagram --output ./reports # grava diagram.txt no diretório
```
### Explain
使用 AI 生成关于您 Terraform 基础设施的自然语言解释。需要配置 provider。
```
terraview explain # explica o projeto atual
terraview explain --plan plan.json # explica a partir de plan existente
terraview explain --provider gemini # usa um provider específico
terraview explain --format json # saída estruturada em JSON
```
### History
查看本地存储在 SQLite 中的扫描历史。启用历史记录后，每次扫描会自动记录结果。
```
terraview history # últimos 20 scans do projeto atual
terraview history --all # todos os projetos
terraview history --limit 50 # limita resultados
terraview history --since 7d # scans dos últimos 7 dias
terraview history --format json # saída JSON
terraview history trend # sparkline de trends de score
terraview history compare # último vs scan anterior
terraview history compare --with 5 # último vs scan #5
terraview history clear # limpa o projeto atual
terraview history clear --before 30d # limpa mais antigos que 30 dias
terraview history export --format csv -o scans.csv
```
在 `.terraview.yaml` 中启用：
```
history:
enabled: true
retention_days: 90
max_size_mb: 50
```
### MCP Server
用于与 AI agent 集成的 Model Context Protocol 服务器。通过 stdio 上的 JSON-RPC 2.0 暴露 terraview 的 tools。
```
terraview mcp server
```
在 Claude Code 中注册：
```
claude mcp add terraview -- terraview mcp server
```
在 Cursor 中注册（`.cursor/mcp.json`）：
```
{
"mcpServers": {
"terraview": {
"command": "terraview",
"args": ["mcp", "server"]
}
}
}
```
暴露 11 个 tools：`terraview_scan`、`terraview_explain`、`terraview_diagram`、`terraview_history`、`terraview_history_trend`、`terraview_history_compare`、`terraview_impact`、`terraview_cache`、`terraview_scanners`、`terraview_fix_suggest`、`terraview_version`。
### Provider 管理
```
terraview provider list # seletor interativo (provider + modelo + teste de conectividade)
terraview provider use gemini gemini-2.5-pro # define provider via CLI (não interativo)
terraview provider use ollama llama3.1:8b # define provider local
terraview provider current # mostra a configuração atual
terraview provider test # testa conectividade do provider configurado
```
`provider list` 命令会执行一次**自动集成测试**。如果测试失败，将显示诊断信息：
- **未安装 CLI** → 显示安装命令（`npm install -g ...`）
- **缺少 API key** → 显示需要设置的环境变量
- **API key 无效 / 网络错误** → 建议检查凭证和连接
- **本地服务无法访问** → 建议检查服务是否正在运行
```
[terraview] Testando conectividade com gemini-cli (gemini-3)... ✓
✓ Teste de integração passou — CLI "gemini" instalado e pronto.
✓ Provider default: gemini-cli modelo: gemini-3
Salvo em: ~/.terraview/.terraview.yaml
```
### Scanner 管理
```
terraview scanners list # lista scanners com status de instalação
terraview scanners install checkov # instala um scanner específico
terraview scanners install tfsec terrascan # instala múltiplos scanners
terraview scanners install --all # instala todos os scanners faltantes
terraview scanners install --all --force # reinstala todos forçadamente
terraview scanners default checkov # define o scanner default
terraview scanners default # mostra o default atual
```
### AI 缓存
Terraview 拥有持久化到磁盘的 AI 响应缓存（`~/.terraview/cache/`）。启用后，对同一 plan 的重复执行将重用之前的响应，无需额外的 API 调用。
```
terraview cache status # mostra estatísticas do cache (entries, tamanho, datas)
terraview cache clear # limpa todas as respostas de IA em cache
```
在 `.terraview.yaml` 中启用：
```
llm:
cache: true # habilita cache persistente
cache_ttl_hours: 24 # TTL em horas (default: 24)
```
### 其他命令
```
terraview setup # diagnóstico do ambiente
terraview version # versão, runtime Go, OS/arch
```
### Exit Codes
| 代码 | 含义 |
|--------|-------------|
| `0` | 无问题或仅有 MEDIUM/LOW/INFO |
| `1` | 严重性为 HIGH 的发现 |
| `2` | CRITICAL 发现（阻止 apply） |
## 输出格式
```
terraview scan checkov # saída pretty (default)
terraview scan checkov -f compact # resumo em uma linha
terraview scan checkov -f json # JSON (review.json)
terraview scan checkov -f sarif # SARIF (review.sarif.json) para a aba Security do GitHub
terraview scan checkov -o ./reports # grava review.json + review.md em ./reports
```
每次扫描都会生成 `review.json` 和 `review.md`。使用 `-f sarif` 时会生成 SARIF 输出。
## 配置
Terraview 可以使用 YAML 文件进行配置。默认情况下，它会在以下位置查找 `.terraview.yaml`（按优先级顺序）：
1. 项目目录通过 `--dir` 指定）
2. 当前工作目录
3. 用户主目录（`~/.terraview/.terraview.yaml`）
配置示例（请参阅 [`examples/.terraview.yaml`](examples/.terraview.yaml) 以获取包含所有字段文档的完整参考）：
```
llm:
enabled: true
provider: ollama # ollama, gemini, claude, openai, deepseek, openrouter, gemini-cli, claude-code
model: llama3.1:8b # modelo específico do provider
url: http://localhost:11434 # URL customizada (relevante apenas para ollama)
# api_key: "" # prefira variáveis de ambiente (veja aviso acima)
timeout_seconds: 120 # timeout de chamadas LLM
temperature: 0.2 # 0.0 a 1.0 (menor = mais determinístico)
max_resources: 30 # máximo de recursos no prompt de IA (default: 30)
cache: false # habilita cache persistente de respostas de IA
cache_ttl_hours: 24 # TTL do cache em horas (default: 24)
ollama:
num_ctx: 4096 # janela de contexto do modelo (default: 4096)
max_threads: 0 # 0 = usa todas as CPUs
max_memory_mb: 0 # 0 = sem limite
min_free_memory_mb: 1024 # memória livre mínima para iniciar o Ollama
scanner:
default: checkov # scanner default para "terraview scan"
scoring:
severity_weights:
critical: 5.0
high: 3.0
medium: 1.0
low: 0.5
rules:
required_tags: # tags obrigatórias em todos os recursos
- Environment
- Owner
- CostCenter
disabled_rules: # silencia rule IDs específicos
- CKV_AWS_79
# enabled_rules: [] # se definido, apenas estas regras são avaliadas
output:
format: pretty # pretty, compact, json
```
### 环境变量
| 变量 | Provider | 描述 |
|----------------------|-------------|-----------------------------|
| `GEMINI_API_KEY` | Gemini | Google Gemini API key |
| `ANTHROPIC_API_KEY` | Claude | Anthropic API key |
| `OPENAI_API_KEY` | OpenAI | OpenAI API key |
| `DEEPSEEK_API_KEY` | DeepSeek | DeepSeek API key |
| `OPENROUTER_API_KEY` | OpenRouter | OpenRouter API key |
| `NO_COLOR` | (global) | 禁用彩色输出 |
Ollama 不需要 API key。`gemini-cli` 和 `claude-code` provider 通过各自的 CLI 订阅进行认证。
## 安全扫描器
| Scanner | 描述 | 安装 |
|---------|-----------|------------|
| [Checkov](https://www.checkov.io/) | 针对 IaC 的安全和合规扫描器 | `terraview scanners install checkov` |
| [tfsec](https://aquasecurity.github.io/tfsec/) | Terraform 安全静态分析 | `terraview scanners install tfsec` |
| [Terrascan](https://runterrascan.io/) | 合规性违规检测器 | `terraview scanners install terrascan` |
所有扫描器的发现结果都会被标准化、去重，并呈现在统一的记分卡中。
```
terraview scanners install --all # instala todos
terraview scanners install checkov # instala específico
terraview scanners default checkov # define como default
terraview scanners list # verifica status
```
## AI Provider
Terraview 支持分为四个类别的**多种 AI provider**。通过 OpenRouter 和 Custom，您几乎可以访问市面上的任何 AI 模型：
### API Provider（需要 API key）
| Provider | 环境变量 | 默认模型 | 示例模型 |
|----------|---------------------|----------------|--------------------|
| **gemini** | `GEMINI_API_KEY` | gemini-2.5-flash | gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash |
| **claude** | `ANTHROPIC_API_KEY` | claude-haiku-4-5 | claude-haiku-4-5, claude-sonnet-4-6, claude-opus-4-6 |
| **openai** | `OPENAI_API_KEY` | gpt-4o-mini | gpt-4o-mini, gpt-4o, o3-mini |
| **deepseek** | `DEEPSEEK_API_KEY` | deepseek-v3.2 | deepseek-chat, deepseek-reasoner |
| **openrouter** | `OPENROUTER_API_KEY` | google/gemini-2.5-flash | OpenRouter 上的任何可用模型 |
### CLI Provider（订阅 — 无需 API key）
| Provider | 需要 CLI | 安装 | 默认模型 |
|----------|---------------|------------|----------------|
| **gemini-cli** | `gemini` | `npm install -g @google/gemini-cli` | gemini-2.5-flash |
| **claude-code** | `claude` | `npm install -g @anthropic-ai/claude-code` | claude-haiku-4-5 |
这些 provider 使用您的**个人订阅**（Google/Anthropic）进行计费。无需 API key — 只需安装 CLI 并进行一次身份验证。
### 本地 Provider（离线）
| Provider | 要求 | 默认模型 |
|----------|-----------|----------------|
| **ollama** | Ollama 在本地运行 | llama3.1:8b |
在 [ollama.com](https://ollama.com) 安装 Ollama 并下载模型（例如：`ollama pull llama3.1:8b`），然后：
```
terraview provider use ollama llama3.1:8b
```
### 自定义 Provider（兼容 OpenAI）
| Provider | 环境变量 | 需要填写 URL | 默认模型 |
|----------|---------------------|----------------|----------------|
| **custom** | `CUSTOM_LLM_API_KEY` | 是（配置中的 `url`） | gpt-4o-mini |
适用于任何遵循 `/v1/chat/completions` 标准的 API：**Grok (xAI)**、**Groq**、**Mistral**、**Together AI**、**Fireworks**、**Perplexity**、**LM Studio**、**vLLM** 等。
```
# .terraview.yaml
llm:
provider: custom
model: grok-3-mini
url: https://api.x.ai
```
## 基于订阅的 AI 集成
Terraview 不同于类似工具的地方在于它原生集成了**基于订阅的 AI** —— 这些 provider 使用 Google（Gemini CLI）或 Anthropic（Claude Code）的官方 CLI 进行分析，通过开发者的个人订阅计费，而不是要求提供 API key 或预充值额度。
### 工作原理
与直接向 API 发送 HTTP 请求不同，terraview 将本地安装的 CLI 二进制文件（`gemini` 或 `claude`）作为子进程调用。这意味着：
1. **无需 API key** — 身份验证由已登录您 Google 或 Anthropic 账户的 CLI 会话处理
2. **订阅计费** — 费用由您已支付的月度计划（Google One AI Premium、Anthropic Max 等）吸收
3. **无需额外配置** — 如果 CLI 在您的终端中能用，它在 terraview 中也能用
4. **与 API 同款模型** — 可访问诸如 `gemini-3`、`gemini-2.5-pro`、`claude-sonnet-4-5`、`claude-opus-4-6` 等模型
### 设置
```
# Gemini CLI (需要 Google One AI Premium 或登录 Google AI Studio)
npm install -g @google/gemini-cli
gemini # autentica na primeira execução
terraview provider use gemini-cli # define como provider default
# Claude Code (需要 Anthropic Max, Pro 或 Team)
npm install -g @anthropic-ai/claude-code
claude # autentica na primeira execução
terraview provider use claude-code # define como provider default
```
### 使用
```
# 使用 Gemini CLI 进行 Scan
terraview scan checkov --provider gemini-cli
terraview scan checkov --provider gemini-cli --model gemini-3
# 使用 Claude Code 进行 Scan
terraview scan checkov --provider claude-code
terraview scan checkov --provider claude-code --model claude-opus-4-6
# 使用 provider CLI 进行 Infrastructure Explain
terraview explain --provider claude-code
```
### API 与 CLI（订阅） — 何时使用
| 方面 | API (key) | CLI (订阅) |
|---------|-----------|------------------|
| **设置** | 创建账户 + 生成 API key | 安装 CLI + 登录 |
| **计费** | 按量付费 (token) | 固定月度计划 |
| **最适合** | CI/CD，自动化流水线 | 本地开发，个人使用 |
| **速率限制** | API 限制（因套餐而异） | 订阅限制 |
| **离线** | 否 | 否（但 Ollama 可以） |
| **Provider** | gemini, claude, openai, deepseek, openrouter | gemini-cli, claude-code |
## CI/CD 集成
### GitHub Actions
```
name: Terraform Security Scan
on:
pull_request:
paths: ['**.tf']
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Terraform
uses: hashicorp/setup-terraform@v3
- name: Install terraview
run: curl -sSL https://raw.githubusercontent.com/leonamvasquez/terraview/main/install.sh | bash
- name: Security scan
run: terraview scan checkov -f sarif -o ./reports
- name: Upload SARIF
if: always()
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: reports/review.sarif.json
- name: Comment on PR
if: always()
uses: marocchino/sticky-pull-request-comment@v2
with:
path: reports/review.md
```
### GitLab CI
```
terraform-scan:
stage: validate
script:
- curl -sSL https://raw.githubusercontent.com/leonamvasquez/terraview/main/install.sh | bash
- terraview scan checkov -f json -o ./reports
artifacts:
paths: [reports/review.json, reports/review.md]
when: always
```
## Docker
```
docker pull ghcr.io/leonamvasquez/terraview:latest
docker run --rm -v $(pwd):/workspace -w /workspace ghcr.io/leonamvasquez/terraview scan checkov
```
要生成 SARIF 输出并将文件保存在挂载目录中：
```
docker run --rm -v $(pwd):/workspace -w /workspace \
ghcr.io/leonamvasquez/terraview scan checkov -f sarif -o /workspace/reports
```
## 架构
```
┌─────────────────────────────┐
│ MCP Server (stdio) │
│ JSON-RPC 2.0 │
│ Claude Code / Cursor / │
│ Windsurf │
└─────────────┬───────────────┘
│
┌───────────────────────────────────────┼───────────────────────────────────────────┐
│ terraview CLI │
│ scan | status | fix | diagram | explain | history | provider | scanners | mcp │
└───────────────────────────────────────┬───────────────────────────────────────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
▼ ▼ ▼
┌────────────────────┐ ┌──────────────────────┐ ┌────────────────────┐
│ Terraform Executor │ │ Plan JSON (--plan) │ │ History Store │
│ init + plan │ │ │ │ SQLite (local) │
│ show -json │ │ │ │ trends/compare │
└─────────┬──────────┘ └──────────┬───────────┘ └────────────────────┘
│ │
└───────────┬────────────┘
▼
┌─────────────────────────┐
│ Parser + Normalizer │
│ NormalizedResource[] │
└────────────┬────────────┘
│
▼
┌─────────────────────────┐
│ Topology Graph │
└────────────┬────────────┘
│
┌──────────┴──────────┐
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Plan (original) │ │ Sanitizer │
│ │ │ Plan (redacted)│
└────────┬────────┘ └────────┬────────┘
│ │
│ ┌────────┴────────┐
│ │ AI Cache │
│ │ SHA256 + TTL │
│ └───┬─────────┬───┘
│ │ │
│ hit│ miss│
│ │ ▼
┌────────┴───────┐ │ ┌─────────────────┐
│ Scanner │ │ │ AI Context │
│ ┌───────────┐ │ │ │ Analysis │
│ │ Checkov │ │ │ └────────┬────────┘
│ │ tfsec │ │ │ │
│ │ Terrascan │ │ │ ▼
│ └───────────┘ │ │ ┌─────────────────┐
└────────┬───────┘ │ │ Validator │
│ │ └────────┬────────┘
│ │ │
└────────┬────────┴───────────┘
▼
┌──────────────────────────┐
│ Normalizer + Resolver │
│ Confidence Scorer │
└────────────┬─────────────┘
▼
┌──────────────────────────┐
│ Aggregator + Scorer │
│ ┌────────────────────┐ │
│ │ Security 0-10 │ │
│ │ Compliance 0-10 │ │
│ │ Maintainab. 0-10 │ │
│ └────────────────────┘ │
│ ┌────────────────────┐ │
│ │ Risk Vectors │ │
│ │ network │ │
│ │ encryption │ │
│ │ identity │ │
│ │ governance │ │
│ │ observability │ │
│ └────────────────────┘ │
│ Meta-analysis │
└────────────┬─────────────┘
│
┌────────────┼─────────────┐
▼ ▼ ▼
┌──────────┐ ┌─────────┐ ┌───────────┐
│ Output │ │ History │ │ MCP │
│ pretty │ │ Record │ │ Response │
│ json │ │ (SQLite)│ │(JSON-RPC) │
│ sarif │ │ │ │ │
└──────────┘ └─────────┘ └───────────┘
```
## 开发
```
git clone https://github.com/leonamvasquez/terraview.git
cd terraview
make build # build para a plataforma atual
make test # testes com race detection + coverage
make test-short # testes rápidos (sem race detector)
make coverage # relatório HTML de coverage
make lint # golangci-lint (ou fallback go vet)
make clean # remove artefatos de build
make dist # build para todas as plataformas (linux/darwin/windows, amd64/arm64)
make docker-build # build da imagem Docker
make docker-run # roda no Docker com plan de exemplo
make install # instala localmente em ~/.local/bin + assets em ~/.terraview
make uninstall # remove a instalação local
make release # cria draft de GitHub release (requer gh CLI)
```
## 贡献
欢迎贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 获取完整说明。
摘要：
- 从 `main` 分支创建新分支，带有 `feat/`、`fix/`、`docs/`、`refactor/` 等前缀。
- 提交格式遵循 [Conventional Commits](https://www.conventionalcommits.org/)：`feat(scanner): add trivy support`
- 必须包含测试：`make test` 必须通过。新模块必须包含 `_test.go`
- 代码检查：`make lint` 无错误
- PR 必须描述问题及解决方案
如需报告安全漏洞，请查看 [SECURITY.md](SECURITY.md)。
## 免责声明
- Terraview **不保存、发布或共享**任何可识别用户身份的信息。
- 当 AI 处于激活状态（配置 provider 后的默认行为）时，Terraform plan 的内容将发送至选定的 provider（Ollama 在本地运行；诸如 Gemini/Claude 等云 API 会将数据发送至外部）。在处理敏感数据前，请查阅 provider 的数据政策。
- 如需 100% 本地和离线分析，请使用 Ollama 作为 AI provider。
## 支持
Terraview 作为开源项目在 MIT 许可证下维护。
- 文档：本 README 及 [CONTRIBUTING.md](CONTRIBUTING.md)
- 问题：[GitHub Issues](https://github.com/leonamvasquez/terraview/issues)
- 讨论：[GitHub Discussions](https://github.com/leonamvasquez/terraview/discussions)
- 安全：[SECURITY.md](SECURITY.md)
### 支持的 Go 版本
我们遵循 Go 的官方支持周期并进行自动化测试。目前支持 **Go 1.26+**。如果您在任何未 EOL 的版本上遇到问题，请提交 [Issue](https://github.com/leonamvasquez/terraview/issues)。
## 许可证
基于 [MIT](LICENSE) 许可证分发。 标签：AI, AI风险缓解, CI/CD安全, Claude, CVE检测, DeepSeek, DevSecOps, DLL 劫持, EC2, ECS, EVTX分析, Gemini, Go语言, IaC, Llama, LLM, LLM评估, LNA, Ollama, OpenAI, SLSA, Terraform, tfsec, Unmanaged PE, 上下文分析, 上游代理, 云安全监控, 人工智能, 内存规避, 大语言模型, 安全合规, 安全扫描, 开源安全工具, 日志审计, 时序注入, 熵值分析, 用户模式Hook绕过, 程序破解, 网络代理, 自动化代码审查, 请求拦截, 逆向工程平台, 静态分析, 预配置检查