terraview - Realiza análise estática e contextual de segurança

项目说明

<picture>
<source media="(prefers-color-scheme: dark)" srcset=".github/assets/terra.png">
<source media="(prefers-color-scheme: light)" srcset=".github/assets/terra.png">
<img alt="terraview" src=".github/assets/terra.png">
</picture>

Escolha seu idioma: Português | English

![Go]()
![GitHub release]()
![CI]()
![Go Report Card]()
![codecov]()
![SLSA 3]()
![OpenSSF Scorecard]()

O Terraview é uma ferramenta Open Source de análise de segurança para planos Terraform que combina scanners estáticos (Checko, Terrascan) com análise contextual por IA executada em paralelo.

Ele inspeciona infraestrutura pro com Terraform, detecta misconfigurations de segurança e compliance usando scanners open-source consagrados, e automaticamente enriquece o resultado com análise contextual multi-provider de IA quando um provider está configurado.

O Terraview roda como binário único, sem dependências externas. Quando um provider de IA está configurado, scanner e IA rodam em paralelo automaticamente.

Sumário

Funcionalidades

Exemplos

Início Rápido

Instalação

Atualização

Shell Completions

Uso

Scan

Terragrunt

Status

Fix

Diagram

Explain

History

MCP Server

Gerenciamento de Pro

Gerenciamento de Scanners

Cache de IA

Formatos de Saída

Configuração

Scanners de Segurança

Pro de IA

Integração com IA por Assinatura

Integração CI/CD

Docker

Arquitetura

Desen

Contribuindo

Aviso

Suporte

Licença

Funcionalidades

Scanners de Segurança — integração automática com Checko e Terrascan; detecta o que está instalado e executa sem configuração

Scanner builtin — 43 regras CKV_AWS em Go puro embutidas no binário; roda sem Python, npm ou downloads externos. Fallback automático quando nenhum scanner externo está no PATH (ideal para CI air-gapped e imagens Docker mínimas)

Policy-as-code nativo — regras customizadas declaradas em .terraview.yaml (8 operadores: is_null, equals, contains, matches, etc.) sem Rego ou Sentinel

Análise contextual por IA (default) — quando um provider de IA está configurado, a IA roda em paralelo com o scanner, analisando relações cross-resource, cadeias de dependências e anti-patterns arquiteturais que scanners estáticos não detectam

IA Multi-Provider — três categorias:

- API: Ollama (local), Google Gemini, Anthropic Claude, OpenAI, DeepSeek e OpenRouter
- CLI (assinatura): Gemini CLI e Claude Code — usam sua assinatura pessoal, sem API key
- Custom: qualquer API OpenAI-compatible (Grok/xAI, Groq, Mistral, Together AI, Fireworks, etc.)

Supressão de findings — arquivo .terra para suprimir riscos aceitos e falsos positivos de forma permanente, com escopo AND-logic por regra, recurso ou fonte (--ignore-file)

Sugestões de AI Fix com classificador de ad — terraview fix plan (dry-run) / terraview fix apply (interativo ou --auto-approve) geram e aplicam HCL corrigido para findings CRITICAL/HIGH com ção, backup e preview de diff. Classificador multi-sinal (5 sinais: catálogo estático, categoria arquitetural, deleção com referências no grafo, histórico de falhas persistente, auto-avaliação da IA via manual_re/blast_radius) promo de risco para revisão manual antes de aplicar

Teste de integração automático — ao selecionar um provider via provider list, o terraview testa conecti e retorna feedback específico por tipo (CLI instalado, API key válida, serviço acessível)

Resolução de conflitos — scanner × IA: scanner vence em caso de divergência (confidence 0.80); acordo ele para 1.00

Scorecard unificado com notas de Segurança, Compliance e Manutenibilidade (0–10)

de risco — extração de risco por recurso em 5 eixos: exposição de rede, criptografia, identidade, goça e obser

Diagrama ASCII (AWS) — ção topológica da infraestrutura no terminal com aninhamento de VPC, tiers de subnet, setas de conexão, referências cruzadas de security groups, arestas bidirecionais, nós NAT/TGW/VPN e agregação de recursos

Blast radius via MCP — análise de impacto de dependências exposta para agentes de IA pela tool MCP terra

Explicação por IA — explicação em linguagem natural da sua infraestrutura via explain

Zero configuração — detecta projetos Terraform e executa init + plan + show automaticamente

Histórico de scans — tracking em SQLite com sparkline de trends, comparação lado-a-lado e export CSV/JSON

MCP Server — integração Context Protocol para agentes de IA (Claude Code, Cursor, Windsurf) através de terraview mcp server

CI/CD nativo — exit codes semânticos (0/1/2) + saída SARIF, JSON e Markdown para GitHub Actions, GitLab CI e Azure DevOps

Supply chain hardening — SBOM (CycloneDX), assinaturas cosign, SLSA Build Pro Level 3 em cada release

Bilíngue (en/pt-BR) — flag --br disponível em todos os comandos

Atualização pelo seu gerenciador de pacotes (brew upgrade terraview, scoop update terraview, apt upgrade terraview, etc.)

Alias tv — symlink criado na instalação; tv scan = terraview scan

Cache de IA persistente em disco — re-execuções do mesmo plan evitam chamadas redundantes à API (cache status | clear)

Instalação cross-platform de scanners via terraview scanners install --all (Linux, macOS, Windows)

Exemplos

Saída de scan no CLI

<img src=".github/assets/scan.png" alt="terraview scan" width="100%">

<details>
<summary>Versão em texto</summary>

</details>

Saída de setup

Início Rápido

Requisitos

Terraform >= 0.12

Um ou mais scanners instalados (Checko, Terrascan) — o terraview pode instalá-los para você

Instalação rápida

Configurar IA

Primeiro scan

Instalação

Script de instalação (Linux, macOS, Windows WSL)

O script detecta automaticamente seu OS e arquitetura, baixa o binário correto do GitHub Releases e cria o alias tv.

Homebrew (macOS / Linux)

Scoop (Windows)

APT — Debian / Ubuntu

DNF / YUM — Fedora / RHEL / Amazon Linux

Docker

Windows — PowerShell (script direto)

Download manual

Build a partir do código-fonte

Compila o binário, instala em ~/.local/bin/terraview, cria o symlink tv e copia os prompts para ~/.terraview/prompts/.

Atualização

Atualize o Terraview pelo seu gerenciador de pacotes:

Shell Completions

Depois de configurar, reabra o terminal e use terraview <Tab> para autocompletar comandos, flags e argumentos.

Uso

Scan

Por default, o terraview roda tanto o scanner de segurança quanto a análise contextual por IA em paralelo. A IA é ativada automaticamente quando um provider está configurado (via .terraview.yaml, flag --provider ou terraview provider use). Se nenhum provider esti, apenas o scanner é executado.

#### Definindo diretório ou arquivo de entrada

Scan do diretório atual (auto-detecta Terraform):

Ou de um diretório específico:

Ou gerando o plan manualmente:

Usar pro CLI (assinatura — sem API key):

Terragrunt

O Terraview suporta Terragrunt como executor alternativo ao Terraform. Terragrunt é um wrapper do Terraform que adiciona funcionalidades como:

Gerenciamento de estado remoto automático — configuração centralizada de backends

Múltiplos módulos — planejar e aplicar dependências entre módulos em sequência

Variáveis e composição — reutilização de configurações via terragrunt.hcl

ção de dependências — executa módulos na ordem correta

#### Auto-detecção

O Terraview detecta automaticamente projetos Terragrunt quando encontra um arquivo terragrunt.hcl no diretório raiz:

Se encontrar um arquivo terragrunt.hcl, o Terraview avisa:

#### Uso explícito

Use --terragrunt para ativar o modo Terragrunt explicitamente:

#### Sintaxe

O flag --terragrunt suporta três formas:

| Sintaxe | Comportamento |
|---------|---------------|
| terraview scan checkov | Usa Terraform (auto-detecta se não houver terragrunt.hcl) |
| terraview scan checko | Auto-detecta arquivo de config Terragrunt |
| terraview scan checko dev.hcl | Usa arquivo dev.hcl como config do Terragrunt |

#### Projetos multi-módulo

O Terraview detecta automaticamente estruturas de multi-módulo Terragrunt e:

1. Executa terragrunt run-all plan para gerar planos para todos os módulos
2. Mescla os planos em um único resultado
3. Executa scanners e IA sobre o merged plan

Exemplo de estrutura:

Para escanear apenas o módulo dev/vpc:

Para escanear toda a estrutura dev:

#### Arquivo de config personalizado

Ao especificar um arquivo de config, o Terraview o passa ao Terragrunt via --terragrunt-config:

#### Flags compatíveis com Terragrunt

O Terragrunt funciona com todas as flags do Terraview:

#### Diferenças entre Terraform e Terragrunt

| Aspecto | Terraform | Terragrunt |
|---------|-----------|-----------|
| Executor | terraform init/plan/show | terragrunt init/plan/show |
| Multi-módulo | Manual (múltiplos terraform calls) | Automático (run-all) |
| Estado remoto | Configurado em terraform {} | Centralizado em terragrunt.hcl |
| Dependências | Gerenciadas .tf | Resolvidas automaticamente |
| Composição | Copy-paste ou módulos | Variáveis + inputs |

#### ção de workspace

O Terraview o workspace Terragrunt antes de executar:

se terragrunt está instalado

sintaxe de terragrunt.hcl

Garante que o diretório contém código Terragrunt válido

Se a ção falhar, o Terraview reporta o erro:

#### Exemplos práticos

Scan de dev com auto-detecção:

Scan de prd com arquiífico:

Gerar diagrama de toda a arquitetura:

Explicação de infraestrutura multi-ambiente:

Dry-run de fixes:

CI/CD — escanear antes de apply:

Status

Mostra os findings abertos do último scan com delta contra o scan anterior. Lê do LastScan persistido, portanto não re-executa o scanner.

Fix

Comando pai para correções geradas por IA. Lê findings do último scan e gera HCL corrigido. fix plan é dry-run (apenas diff); fix apply é interativo por default (y/n por fix).

Safeguards: pre-flight de brace-balance, backup .tvfix.bak por arquivo, terraform após apply, rollback automático em caso de falha de ção.

Diagram

Gera um diagrama ASCII determinístico da infraestrutura a partir de um plan Terraform. Não requer IA. Atualmente suporta apenas AWS.

<img src=".github/assets/diagram.png" alt="terraview diagram" width="100%">

Dois modos de renderização disponíveis:

topo (default) — visão topológica com aninhamento de VPC, tiers de subnet, setas de conexão, referências cruzadas de security groups, arestas bidirecionais, nós NAT/TGW/VPN e agregação de recursos

flat — visão simples baseada em camadas

Explain

Gera uma explicação em linguagem natural da sua infraestrutura Terraform usando IA. Requer um provider configurado.

History

o histórico de scans armazenado localmente em SQLite. Cada scan registra resultados automaticamente quando o histórico está habilitado.

Habilite no .terraview.yaml:

MCP Server

Servidor Model Context Protocol para integração com agentes de IA. Expõe as tools do terraview 2.0 sobre stdio.

> O alias terraview mcp serve continua funcionando por retrocompatibilidade.

Registrar no Claude Code:

Registrar no Cursor (.cursor/mcp.json):

Expõe 11 tools: terra, terra, terra, terra, terra, terra, terra, terra, terra, terra, terra.

Gerenciamento de Pro

O comando provider list executa um teste de integração automático. Se o teste falhar, uma mensagem de diagnóstico é exibida:

CLI não instalado → mostra comando de instalação (npm install -g ...)

API key ausente → mostra variável de ambiente a definir

API key inválida / erro de rede → sugere credenciais e conecti

Serviço local inacessível → sugere se o serviço está rodando

Gerenciamento de Scanners

Cache de IA

O Terraview possui um cache persistente de respostas de IA em disco (~/.terraview/cache/). Quando habilitado, re-execuções do mesmo plan reutilizam a resposta anterior sem chamadas adicionais à API.

Habilite no .terraview.yaml:

Outros comandos

Exit Codes

| Código | Significado |
|--------|-------------|
| 0 | Sem issues ou apenas MEDIUM/LOW/INFO |
| 1 | Findings de se HIGH |
| 2 | Findings CRITICAL (bloqueia apply) |

Formatos de Saída

Todo scan gera review.json e review.md. A saída SARIF é gerada quando -f sarif é usado.

Configuração

O Terraview pode ser configurado com um arquivo YAML. Por default, ele procura .terraview.yaml nos seguintes locais (em ordem de precedência):

1. Diretório do projeto (passado via --dir)
2. Diretório de trabalho atual
3. Home do usuário (~/.terraview/.terraview.yaml)

Exemplo de configuração (veja examples/.terraview.yaml para referência completa com todos os campos documentados):

> AVISO: Nunca faça commit de api_key diretamente no .terraview.yaml. Prefira variáveis de ambiente (ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.) ou adicione .terraview.yaml ao seu .gitignore. O Terraview emite um aviso no stderr quando detecta api_key no arquivo de configuração.

Variáveis de ambiente

| Variável | Provider | Descrição |
|----------------------|-------------|-----------------------------|
| GEMINI_API_KEY | Gemini | API key do Google Gemini |
| ANTHROPIC_API_KEY | Claude | API key da Anthropic |
| OPENAI_API_KEY | OpenAI | API key da OpenAI |
| DEEPSEEK_API_KEY | DeepSeek | API key do DeepSeek |
| OPENROUTER_API_KEY | OpenRouter | API key do OpenRouter |
| NO_COLOR | (global) | Desabilita saída colorida |

O Ollama não requer API key. Os pro gemini-cli e claude-code autenticam pelas respecti de CLI.

Scanners de Segurança

| Scanner | Descrição | Instalação |
|---------|-----------|------------|
| builtin | Scanner em Go puro embutido no terraview — 43 regras CKV_AWS, sem dependências externas | já incluído no binário |
| Checkov | Scanner de segurança e compliance para IaC | terraview scanners install checkov |
| Trivy | Análise estática de segurança para Terraform | terraview scanners install trivy |
| Terrascan | Detector de violações de compliance | terraview scanners install terrascan |

Os findings de todos os scanners são normalizados, deduplicados e apresentados em um scorecard unificado. O builtin cobre S3, RDS, EC2, Security Groups, Lambda, CloudFront, DynamoDB, ElastiCache, CloudWatch, EKS, ECS, ECR, SQS, SNS, IAM, CloudTrail, OpenSearch, MSK e RDS Cluster — útil para ambientes air-gapped onde scanners externos não podem ser instalados.

Pro de IA

O Terraview suporta múltiplos pro de IA organizados em quatro categorias. Com OpenRouter e Custom, você tem acesso a praticamente qualquer modelo de IA do mercado:

Pro API (requerem API key)

| Provider | Variável de ambiente | Modelo default | Modelos de exemplo |
|----------|---------------------|----------------|--------------------|
| 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 | Qualquer modelo disponível no OpenRouter |

Pro CLI (assinatura — sem API key)

| Provider | CLI requerido | Instalação | Modelo default |
|----------|---------------|------------|----------------|
| gemini-cli | gemini | npm install -g /gemini-cli | gemini-2.5-flash |
| claude-code | claude | npm install -g -ai/claude-code | claude-haiku-4-5 |

Estes pro usam sua assinatura pessoal (Google/Anthropic) para billing. Sem API key — basta instalar o CLI e autenticar uma vez.

Provider local (offline)

| Provider | Requisito | Modelo default |
|----------|-----------|----------------|
| ollama | Ollama rodando localmente | llama3.1:8b |

Instale o Ollama em ollama.com e baixe um modelo (ex: ollama pull llama3.1:8b), depois:

Provider Custom (OpenAI-compatible)

| Provider | Variável de ambiente | URL requerida | Modelo default |
|----------|---------------------|----------------|----------------|
| custom | CUSTOM_LLM_API_KEY | Sim (url na config) | gpt-4o-mini |

Funciona com qualquer API que siga o padrão /v1/chat/completions: Grok (xAI), Groq, Mistral, Together AI, Fireworks, Perplexity, LM Studio, vLLM, etc.

Integração com IA por Assinatura

O Terraview se diferencia de ferramentas similares ao oferecer integração nativa com IAs baseadas em assinatura — pro que usam os CLIs oficiais do Google (Gemini CLI) ou da Anthropic (Claude Code) para análise, cobrando pela assinatura pessoal do desen em vez de exigir API keys ou créditos pré-pagos.

Como funciona

Em vez de fazer requisições HTTP diretas às APIs, o terraview invoca os binários de CLI instalados localmente (gemini ou claude) como subprocessos. Isso significa:

1. Sem API key — a autenticação é tratada pela sessão de CLI já logada na sua conta Google ou Anthropic
2. Billing por assinatura — o custo é absorvido pelo plano que você já paga (Google One AI Premium, Anthropic Max, etc.)
3. Sem configuração extra — se o CLI funciona no seu terminal, ele funciona no terraview
4. Mesmos modelos da API — acesso a modelos como gemini-3, gemini-2.5-pro, claude-sonnet-4-5, claude-opus-4-6

Setup

Uso

API vs CLI (assinatura) — quando usar cada um

| Aspecto | API (key) | CLI (assinatura) |
|---------|-----------|------------------|
| Setup | Criar conta + gerar API key | Instalar CLI + fazer login |
| Billing | Pay-per-token (créditos) | Plano mensal fixo |
| Melhor para | CI/CD, pipelines automatizados | Desen local, uso pessoal |
| Rate limits | Limites da API ( por tier) | Limites da assinatura |
| Offline | Não | Não (mas Ollama sim) |
| Pro | gemini, claude, openai, deepseek, openrouter | gemini-cli, claude-code |

> Dica: Para uso local diário, os pro de assinatura são a escolha mais prática — zero configuração de key, billing simples. Para CI/CD, prefira pro de API (ou Ollama para ambientes air-gapped).

Integração CI/CD

GitHub Actions

GitLab CI

Docker

Para saída SARIF com arqui no diretório montado:

Arquitetura

Desen

Contribuindo

Contribuições são bem-! Veja CONTRIBUTING.md para instruções completas.

Resumo:

Branch a partir de main com prefixo feat/, fix/, docs/, refactor/, etc.

Commits no formato Con Commits: feat(scanner): add tri

Testes obrigatórios: make test de. Novos módulos de _test.go

Lint: make lint sem erros

PRs de o problema e a solução

Para reportar de segurança, veja SECURITY.md.

Aviso

O Terraview não sal nem compartilha nenhuma informação identificável do usuário.

Quando a IA está ati default quando um provider está configurado), o conteúdo do plan Terraform é enviado ao provider selecionado (Ollama roda localmente; APIs cloud como Gemini/Claude enviam dados externamente). Revise a política de dados do provider antes de usar com dados sensíveis.

Para análise 100% local e offline, use Ollama como provider de IA.

Suporte

O Terraview é mantido como projeto open source sob a licença MIT.

Documentação: este README e CONTRIBUTING.md

Issues: GitHub Issues

Discussions: GitHub Discussions

Segurança: SECURITY.md

Versão do Go suportada

Seguimos o ciclo oficial de suporte do Go com testes automatizados. Atualmente suportando Go 1.26+. Se encontrar problemas com qualquer versão não-EOL, abra uma Issue.

Licença

Distribuído sob a licença MIT.

项目信息

开发语言：Go

Star 数：13

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Realiza análise estática e contextual de segurança em infraestrutura Terraform, detecta misconfigurations e riscos de compliance antes do apply, calcula scores de segurança e gera sugestões de correção automática.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。