security-scan

Skill de Varredura de Segurança

Audite sua configuração do Claude Code em busca de problemas de segurança usando o AgentShield.

Quando Ativar

• Ao configurar um novo projeto Claude Code
• Após modificar .claude/settings.json, CLAUDE.md ou configurações MCP
• Antes de confirmar alterações de configuração
• Ao integrar-se a um novo repositório com configurações existentes do Claude Code
• Verificações periódicas de higiene de segurança

O Que Ela Varre

Arquivo	Verificações
CLAUDE.md	Segredos codificados, instruções de execução automática, padrões de injeção de prompt
settings.json	Listas de permissão excessivamente permissivas, listas de negação ausentes, flags de bypass perigosas
mcp.json	Servidores MCP arriscados, segredos de ambiente codificados, riscos de cadeia de suprimentos com npx
hooks/	Injeção de comando via interpolação, exfiltração de dados, supressão silenciosa de erros
agents/*.md	Acesso irrestrito a ferramentas, superfície de injeção de prompt, especificações de modelo ausentes

Pré-requisitos

O AgentShield deve estar instalado. Verifique e instale se necessário:

# Verificar se está instalado
npx ecc-agentshield --version

# Instalar globalmente (recomendado)
npm install -g ecc-agentshield

# Ou executar diretamente via npx (sem instalação)
npx ecc-agentshield scan .

Uso

Varredura Básica

Execute no diretório .claude/ do projeto atual:

# Escanear projeto atual
npx ecc-agentshield scan

# Escanear um caminho específico
npx ecc-agentshield scan --path /path/to/.claude

# Escanear com filtro de severidade mínima
npx ecc-agentshield scan --min-severity medium

Formatos de Saída

# Saída no terminal (padrão) — relatório colorido com nota
npx ecc-agentshield scan

# JSON — para integração com CI/CD
npx ecc-agentshield scan --format json

# Markdown — para documentação
npx ecc-agentshield scan --format markdown

# HTML — relatório autossuficiente com tema escuro
npx ecc-agentshield scan --format html > security-report.html

Correção Automática

Aplique correções seguras automaticamente (apenas correções marcadas como auto-corrigíveis):

npx ecc-agentshield scan --fix

Isso irá:

• Substituir segredos codificados por referências a variáveis de ambiente
• Restringir permissões curinga para alternativas mais específicas
• Nunca modificar sugestões manuais

Análise Profunda Opus 4.6

Execute o pipeline adversário de três agentes para uma análise mais profunda:

# Requer ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY=sua-chave
npx ecc-agentshield scan --opus --stream

Isso executa:

1. Atacante (Red Team) — encontra vetores de ataque
2. Defensor (Blue Team) — recomenda fortalecimento
3. Auditor (Veredito Final) — sintetiza ambas as perspectivas

Inicializar Configuração Segura

Crie uma nova configuração .claude/ segura do zero:

npx ecc-agentshield init

Cria:

• settings.json com permissões restritas e lista de negação
• CLAUDE.md com melhores práticas de segurança
• mcp.json como placeholder

Ação do GitHub

Adicione ao seu pipeline de CI:

- uses: affaan-m/agentshield@v1
  with:
    path: '.'
    min-severity: 'medium'
    fail-on-findings: true

Níveis de Severidade

Nota	Pontuação	Significado
A	90-100	Configuração segura
B	75-89	Problemas menores
C	60-74	Precisa de atenção
D	40-59	Riscos significativos
F	0-39	Vulnerabilidades críticas

Interpretando Resultados

Achados Críticos (corrija imediatamente)

• Chaves de API ou tokens codificados em arquivos de configuração
• Bash(*) na lista de permissão (acesso irrestrito ao shell)
• Injeção de comando em hooks via interpolação ${file}
• Servidores MCP que executam shell

Achados Altos (corrija antes da produção)

• Instruções de execução automática em CLAUDE.md (vetor de injeção de prompt)
• Listas de negação ausentes nas permissões
• Agentes com acesso desnecessário a Bash

Achados Médios (recomendado)

• Supressão silenciosa de erros em hooks (2>/dev/null, || true)
• Hooks de segurança PreToolUse ausentes
• Instalação automática npx -y em configurações de servidores MCP

Achados Informativos (conscientização)

• Descrições ausentes em servidores MCP
• Instruções proibitivas corretamente sinalizadas como boa prática

Links

• GitHub: github.com/affaan-m/agentshield
• npm: npmjs.com/package/ecc-agentshield