Pitch: Criei um plugin de segurança para o Claude Code que roda pentest autônomo, SAST e audit de dependências com um único comando

Fala, pessoal.

Nos últimos dias mergulhei num projeto que quero compartilhar com vocês: o Shield, um plugin open-source para o Claude Code que orquestra ferramentas reais de segurança de dentro do terminal.

A ideia nasceu de uma frustração real: trabalho em projetos onde não tem equipe de AppSec dedicada. Ferramentas como Semgrep, gitleaks e npm audit existem e são boas, mas cada uma roda separada, gera relatório num formato diferente, e nenhuma propõe correção no código. Sem falar que interpretar os resultados exige tempo que dev solo geralmente não tem.

O Shield resolve isso trazendo tudo pra dentro do Claude Code, onde eu já estou trabalhando.

O que ele faz na prática

Um comando. Resultado completo:

/shield:shield

Ele detecta automaticamente a stack do projeto (linguagem, framework, package manager, Docker), roda as ferramentas que estiverem instaladas, consolida tudo num relatório unificado com score de risco, e propõe correções com diff.

Testei no MeusDireitos, meu projeto de análise de contratos de aluguel — um monorepo Next.js + React com pnpm. Rodei com Semgrep, gitleaks e pnpm audit instalados. O resultado foi pesado:

Dependências vulneráveis (pnpm audit):

| Severidade | Quantidade |
|------------|-----------|
| CRITICAL   | 1         |
| HIGH       | 26        |
| MEDIUM     | 6         |
| LOW        | 3         |
| Total      | 36        |

Secrets no histórico do git (gitleaks) — 103 segredos encontrados:

| Tipo                 | Quantidade | Severidade |
|----------------------|-----------|-----------|
| generic-api-key      | 57        | HIGH      |
| curl-auth-header     | 15        | HIGH      |
| gcp-api-key          | 12        | HIGH      |
| aws-access-token     | 5         | CRITICAL  |
| stripe-access-token  | 5         | CRITICAL  |
| openai-api-key       | 4         | HIGH      |
| jwt                  | 3         | HIGH      |
| anthropic-api-key    | 1         | CRITICAL  |
| private-key          | 1         | CRITICAL  |

SAST (Semgrep) — 77 findings:

35 HIGH (hardcoded credentials, XSS via innerHTML/document.write)
30 MEDIUM (dangerouslySetInnerHTML, path traversal em scripts, raw HTML no Express, falta de SRI em CDN)
12 LOW (falsos positivos em template literals)

O Shield consolidou tudo e gerou um relatório de 246 linhas com 4 níveis de prioridade. A parte que mais me surpreendeu: ele não só listou, mas contextualizou cada finding. Por exemplo, sobre os 4 dangerouslySetInnerHTML que o Semgrep flagou como MEDIUM:

"Usado para injetar JSON-LD structured data. O conteúdo é gerado server-side sem input do usuário, então o risco real é BAIXO. JSON-LD em <script type='application/ld+json'> é um padrão aceito."

E sobre as 36 dependências vulneráveis:

"A maioria das vulnerabilidades são em dependências transitivas. O score acumulado parece alarmante, mas as mais impactantes para o projeto são next, jspdf e axios que são dependências diretas."

No final, das 36 dependency vulns, atualizei 3 pacotes diretos (next, jspdf, axios) + 10 overrides no pnpm e o resultado ficou 0 vulnerabilidades em dependências. O .env.prod-verify que estava trackeado no git (com chaves AWS, Stripe, OpenAI) foi removido e as credenciais rotacionadas.

Como funciona por baixo

O Shield é um conjunto de shell scripts modulares que se comunicam via JSON. Cada ferramenta é um script isolado:

detect-stack.sh — Detecta linguagem, framework, package manager, Docker
run-sca.sh — Roda npm/yarn/pnpm/pip/composer audit
run-sast.sh — Roda Semgrep com 34 regras customizadas (12 JS/TS, 11 Python, 11 PHP)
run-secrets.sh — Roda gitleaks no histórico do git
run-outdated.sh — Checa dependências desatualizadas (SECURITY/MAJOR/MINOR/PATCH)
run-shannon.sh — Orquestra o Shannon (pentester autônomo da KeygraphHQ)
consolidate.sh — Junta tudo, deduplica, atribui IDs SHIELD-XXX
calculate-score.sh — Calcula score 0-100 com pesos por severidade

A arquitetura é proposital: scripts simples em bash, sem dependência de Node/Python pro tooling em si. Cada script manda JSON pro stdout e logs pro stderr. O Claude Code lê o JSON, enriquece com contexto (CWE, OWASP, compliance), e gera o relatório com propostas de fix.

O scoring

A fórmula é transparente:

Score = 100 - (CRITICAL×15 + HIGH×8 + MEDIUM×3 + LOW×1)
Mínimo: 0

Faixa	Nível de risco
90-100	LOW RISK
70-89	MEDIUM RISK
40-69	HIGH RISK
0-39	CRITICAL RISK

Exemplo concreto: um projeto com 1 CRITICAL e 5 HIGH = 100 - (15 + 40) = 45/100 → HIGH RISK.

O que mais ele faz

6 modos de operação:

Modo	Comando	O que faz
Full	`/shield:shield full`	Pentest Shannon + SAST + secrets + audit + outdated
Quick	`/shield:shield quick`	SAST + secrets + audit + outdated (sem pentest)
Fix	`/shield:shield fix`	Propõe correções com diff pra cada achado
Verify	`/shield:shield verify`	Re-escaneia pra confirmar que os fixes funcionaram
Score	`/shield:shield score`	Só calcula o score, sem rodar scan novo
Outdated	`/shield:shield outdated`	Checa dependências desatualizadas

Detecção de stack automática — Suporta 9 ecossistemas: Node.js, Python, PHP, Go, Ruby, Rust, Java, C#, TypeScript. Detecta framework (Express, Next.js, Django, Laravel, etc.), package manager (npm, yarn, pnpm, pip, composer, cargo, bundler...) e presença de Docker.

Compliance mapping — Cada finding é mapeado para OWASP Top 10, SOC 2, PCI-DSS e HIPAA. Útil pra quem precisa mostrar conformidade em auditorias.

Degradação graciosa — Se você só tem npm instalado, ele roda só o npm audit. Se tem Semgrep e gitleaks, roda os três. Nunca trava por falta de ferramenta — usa o que tiver e reporta o que ficou faltando.

GitHub Issues — Pode criar uma issue por vulnerabilidade, com template padronizado incluindo CWE, OWASP, severidade e proposta de fix.

SARIF — Output em SARIF 2.1.0 pra integrar com a aba Security do GitHub.

A integração com o Shannon

O diferencial principal é a integração com o Shannon, um pentester autônomo open-source da KeygraphHQ que usa IA pra executar exploits reais contra a aplicação rodando.

O Shannon faz algo que nenhum SAST faz: ele prova a vulnerabilidade com um exploit funcional. SQL injection? Ele manda o payload, recebe o resultado, e gera um PoC que você pode copiar e colar pra reproduzir.

O Shield entra como a camada que faltava:

Shannon encontra e prova → Shield propõe o fix no código
Shannon gera relatório → Shield consolida com as outras ferramentas
Shannon roda via Docker → Shield configura automaticamente baseado na stack

O Shannon é AGPL-3.0. O Shield é MIT. Não tem conflito porque o Shield chama o Shannon via CLI como processo externo, igual faz com Semgrep ou gitleaks.

Dependências desatualizadas com classificação

Uma feature que adicionei e curti bastante: o check de outdated com cross-reference de vulnerabilidades.

Testei de novo no MeusDireitos, dessa vez só o check de outdated:

{
  "total": 3,
  "security": 0,
  "major": 0,
  "minor": 3,
  "patch": 0
}

3 pacotes desatualizados (prettier, turbo, vercel), todos MINOR. Se algum desses pacotes também tiver CVE conhecida, o Shield marca como SECURITY em vez de MINOR. Ou seja, você sabe exatamente quais updates são urgentes e quais são só atualização de versão.

Stack técnica

Linguagem: Bash (shellcheck-clean, compatível com bash 3.2 do macOS)
Comunicação: JSON via stdout, logs via stderr
Testes: 189 assertions em 4 suites (detect-stack, check-prereqs, consolidate, calculate-score)
Regras Semgrep: 34 regras customizadas cobrindo SQL injection, XSS, command injection, SSRF, secrets hardcoded, desserialização insegura, path traversal, prototype pollution e mais
Licença: MIT
Zero dependências além das ferramentas de segurança em si (e jq pro processamento JSON)

Como instalar

# Clonar
git clone https://github.com/alissonlinneker/shield-claude-skill.git

# Instalar ferramentas de segurança
cd shield-claude-skill && ./install.sh

# Dentro do Claude Code, registrar o marketplace:
/plugin marketplace add /caminho/para/shield-claude-skill

# Instalar o plugin:
/plugin install shield@shield-security

# Ou pra teste rápido sem instalar:
claude --plugin-dir /caminho/para/shield-claude-skill

Depois é só abrir qualquer projeto e rodar /shield:shield.

O que vem pela frente

O roadmap tá organizado em issues no repositório:

v0.2.0:

Trivy pra container e IaC scanning
Parsing completo do relatório do Shannon
Modo CI com output SARIF pro pipeline
Pre-commit hook pra bloquear secrets antes do commit

v0.3.0:

Histórico de vulnerabilidades e análise de tendência
Relatório de compliance dedicado (SOC 2, PCI-DSS, HIPAA)
Suporte a Go, Ruby, Rust e Java no audit de dependências

Números do projeto

43 arquivos, ~7700 linhas de código
11 shell scripts + 34 regras Semgrep
189 testes unitários, 0 warnings no shellcheck
3 templates Shannon (web-app, API-only, SPA+API)

No teste real (MeusDireitos):

36 dependency vulns encontradas → todas corrigidas
103 secrets no git history → .env.prod-verify removido, credenciais rotacionadas
77 SAST findings → priorizados em 4 níveis de ação
Relatório final: 246 linhas com contexto, fix proposals e compliance mapping