danoszz/penthera

Penthera Security Scanner

Scanner de segurança leve para URLs, repositórios locais e auditoria de máquina (macOS). Sempre execute o portão de autorização antes de qualquer varredura.

Crítico: Portão de autorização

Não execute o Penthera até que a autorização seja confirmada.

Antes da primeira varredura em uma sessão, peça ao usuário para confirmar UMA das seguintes opções:

1. Eles possuem o alvo (aplicativo, servidor, projeto).
2. Eles têm autorização por escrito do proprietário do sistema.
3. O alvo é localhost ou um laboratório privado que eles controlam.

Se o usuário solicitar a varredura de um domínio de terceiros (ex.: google.com, example.com) sem alegar propriedade ou autorização, pare e recuse. Em caso de dúvida, não faça a varredura.

Para a política completa, consulte references/authorization.md.

Pré-voo

Execute antes da primeira varredura:

bash skills/penthera/scripts/preflight.sh [URL]

A partir da raiz do repositório. Passe a URL alvo para alertar em alvos que não sejam localhost. Corrija quaisquer erros antes de prosseguir.

Resolver comando CLI

Use o que estiver disponível:

penthera --version          # após npm link
node bin/penthera.js --version   # a partir da raiz do repositório

Todos os exemplos abaixo usam penthera; substitua por node bin/penthera.js quando necessário.

Árvore de decisão

Intenção do usuário	Padrão de comando
Primeira vez / inseguro	penthera (assistente interativo — TTY) ou penthera-scan
Escanear uma URL ativa	penthera <url> --profile standard -o reports/scan.json
Escanear apenas repositório (segredos, rotas)	penthera --repo . -o reports/repo-scan.json
URL + fonte combinados	penthera <url> --repo . -o reports/scan.json --sarif reports/scan.sarif
Comparar com varredura anterior	penthera <url> -o reports/scan.json --baseline reports/previous.json
Endpoints autenticados	Adicione --auth-cookie ou --auth-bearer / variáveis de ambiente PENTHERA_*
Auditoria de máquina macOS	penthera --machine

Comportamento seguro padrão

• Sempre use --profile standard a menos que o usuário solicite explicitamente testes mais profundos.
• Escreva relatórios em reports/ (ignorado pelo git), nunca dentro de skills/penthera/.
• Após a varredura, leia o relatório .md companheiro e resuma as descobertas por gravidade com recomendações de correção.

Portão de modo destrutivo

Estas flags enviam payloads de ataque. Exigem confirmação explícita do usuário antes do uso:

• --deep — sondas SQLi, SSTI, SSRF, XSS, CMDi
• --fuzz — fuzzing de API baseado em propriedades
• --all — ativa recon + deep + fuzz
• --profile deep — cobertura máxima

Se o usuário pedir "teste de penetração completo" ou "varredura profunda", confirme que ele possui o alvo e aceita testes baseados em payload.

Fluxo de trabalho 1: Auditoria pré-lançamento

Gatilhos: "escanear meu app de staging", "auditoria de segurança antes do deploy", "verificar meu app em busca de vulnerabilidades"

1. Confirme a autorização (veja o portão acima).
2. Execute o pré-voo.
3. Execute:

mkdir -p reports
penthera https://staging.example.com --profile standard -o reports/scan.json

4. Leia reports/scan.md — resuma descobertas críticas/altas/médias.
5. Recomende correções concretas por descoberta.
6. Observe o código de saída: 0 = sem críticas/altas; 1 = críticas/altas encontradas; 2 = varredura falhou.

Fluxo de trabalho 2: Repositório + ativo combinados

Gatilhos: "escanear meu app Next.js e staging", "varredura black-box e white-box"

1. Confirme a autorização para a URL.
2. Execute o pré-voo com a URL.
3. Execute:

mkdir -p reports
penthera https://staging.example.com --repo . --profile standard \
  -o reports/scan.json --sarif reports/scan.sarif

4. Resuma descobertas da URL (cabeçalhos, TLS, CORS, autenticação) e descobertas do repositório (segredos, rotas de API, limites de confiança).
5. Ofereça-se para enviar SARIF via GitHub Actions (veja references/output-and-ci.md).

Fluxo de trabalho 3: CI / regressão de baseline

Gatilhos: "comparar com a última varredura", "apenas novas descobertas", "verificação de regressão"

1. Confirme a autorização e que reports/previous.json existe (ou peça ao usuário o caminho do baseline).
2. Execute:

mkdir -p reports
penthera https://staging.example.com --profile standard \
  -o reports/scan.json --baseline reports/previous.json

3. Relate: contagem de novas descobertas, contagem de resolvidas, contagem de inalteradas (impresso no stderr durante a varredura).
4. Foque o resumo apenas nas descobertas novas.

Varreduras autenticadas

Apenas após o portão de autorização passar:

# Token Bearer
PENTHERA_BEARER=eyJ... penthera https://myapp.com --profile standard -o reports/scan.json

# Cookie de sessão
penthera https://myapp.com --auth-cookie "session=abc123" -o reports/scan.json

# Flags explícitas
penthera https://myapp.com --auth-bearer "eyJ..." -o reports/scan.json

Variáveis de ambiente: PENTHERA_BEARER, PENTHERA_COOKIE.

Varredura de segredos apenas no repositório

Gatilhos: "encontrar segredos codificados", "escanear este repositório em busca de chaves"

Não é necessária autorização de URL para análise de repositório local:

penthera --repo . -o reports/repo-scan.json

Resuma as descobertas de segredos; lembre o usuário de rotacionar quaisquer credenciais expostas.

Exemplos

Exemplo 1: Verificação rápida em localhost

Usuário: "Escanear meu app localhost na porta 3000"

Ações:

1. Confirme localhost — autorização satisfeita.
2. bash skills/penthera/scripts/preflight.sh http://localhost:3000
3. penthera http://localhost:3000 --profile quick -o reports/scan.json
4. Resuma reports/scan.md.

Exemplo 2: Staging antes do deploy

Usuário: "Auditar staging.myapp.com antes de enviar"

Ações:

1. Pergunte: "Você possui ou tem autorização por escrito para staging.myapp.com?"
2. Após confirmação, execute varredura com perfil padrão e saída JSON + markdown.
3. Liste primeiro os itens críticos/altos com etapas de remediação.

Exemplo 3: Alvo não autorizado (deve recusar)

Usuário: "Escanear google.com em busca de vulnerabilidades"

Ações:

1. Não execute o Penthera.
2. Explique que escanear sistemas de terceiros sem autorização não é permitido.
3. Ofereça-se para escanear o próprio aplicativo ou localhost do usuário.

Não use esta habilidade para

• Ajuda geral de programação, clima ou tarefas não relacionadas
• Escanear sistemas que o usuário não possui ou não tem permissão para testar
• Exploração maliciosa ou exfiltração de dados

Recursos adicionais

• Perfis e flags: references/profiles-and-flags.md
• Formatos de saída e CI: references/output-and-ci.md
• Solução de problemas: references/troubleshooting.md
• Política de autorização: references/authorization.md