Ravage

Ravage é uma CLI baseada em evidências para avaliar uma aplicação web em execução que você possui ou está explicitamente autorizado a testar. Ela combina reconhecimento determinístico e validação com um loop de ataque opcional orientado por modelo, mantendo escopo, autenticação, contabilização de tráfego e evidências dentro de limites controlados por código.

Ravage é um alfa de pesquisa pré-1.0. Use ambientes descartáveis e regras de engajamento por escrito. Testes de segurança podem alterar o estado da aplicação; Ravage não corrige descobertas nem implanta correções.

Início rápido · Autenticação · Resultados · Recursos · Documentação

Requisitos

• Python 3.12
• Git
• macOS, Linux ou WSL
• Docker apenas para ferramentas containerizadas, XBEN e testes de integração
• Uma chave de API do provedor apenas para comandos orientados por modelo

O primeiro scan normal não precisa de chave de modelo, navegador, daemon Docker ou scanner externo.

Instalar a partir do código-fonte

git clone https://github.com/duriantaco/ravage.git
cd ravage
scripts/bootstrap.sh
source .venv/bin/activate
ravage doctor

O bootstrap cria .venv e instala o workspace. Use scripts/bootstrap.sh --dev para dependências de desenvolvimento, --browser para suporte a navegador, ou --install-browser para instalar também o Chromium.

Início rápido local em cinco minutos

Inicie sua aplicação primeiro. Este exemplo assume que ela está escutando em http://127.0.0.1:3000.

1. Crie um brief de engajamento com escopo e um arquivo de ambiente privado:

   root@kitploit:~

   ravage init http://127.0.0.1:3000 \
     --brief ravage-brief.yaml \
     --env-file .env.ravage \
     --description "Avaliação autorizada do meu aplicativo de desenvolvimento local."
   

2. Revise o ravage-brief.yaml. Verifique o alvo, rotas no escopo, exclusões, orçamento de requisições, limite de taxa, objetivos e critérios de sucesso.

3. Execute um scan de superfície sem modelo:

   root@kitploit:~

   ravage doctor --workflow scan --brief ravage-brief.yaml
   ravage scan ravage-brief.yaml --probe surface_map --report
   

O comando imprime o diretório de execução. Copie esse caminho e use-o como RUN_DIR nos comandos de inspeção abaixo.

Executar o agente orientado por modelo

Adicione uma chave de provedor compatível, como OPENAI_API_KEY, ao .env.ravage. Ravage lê este arquivo diretamente; não o carregue via shell.

ravage doctor --workflow attack --brief ravage-brief.yaml
ravage attack ravage-brief.yaml --allow-paid-models --report

--allow-paid-models é um reconhecimento explícito de que a execução pode gerar cobranças do provedor. Seleção de modelos, provedores locais e perfis reproduzíveis estão documentados em Provedores de modelo.

Testes autenticados

Adicione uma identidade de teste dedicada ao brief:

ravage auth add ravage-brief.yaml \
  --identity user \
  --type form \
  --login /login \
  --health /account \
  --marker Logout \
  --env-file .env.ravage

Preencha as referências de segredo geradas, verifique a sessão e então ataque com a identidade selecionada:

ravage auth check ravage-brief.yaml --identity user
ravage attack ravage-brief.yaml \
  --identity user \
  --allow-paid-models \
  --report

Login por formulário, tokens bearer e cabeçalhos estáticos fixos são suportados. Credenciais gerenciadas permanecem dentro do proprietário HTTP autenticado; canais de processo, Python e comando são bloqueados quando uma identidade é selecionada. Consulte Autenticação para configuração e limitações.

Alvos remotos autorizados

A execução remota é fail-closed e requer um sinalizador explícito. Comece com um scan de superfície de baixo impacto:

ravage init https://staging.example.test \
  --brief ravage-brief.yaml \
  --env-file .env.ravage \
  --description "Avaliação autorizada do meu aplicativo de staging."

ravage doctor --workflow scan \
  --brief ravage-brief.yaml \
  --authorized-remote-target

ravage scan ravage-brief.yaml \
  --probe surface_map \
  --authorized-remote-target \
  --report

Para uma execução remota orientada por modelo:

ravage attack ravage-brief.yaml \
  --authorized-remote-target \
  --allow-paid-models \
  --report

Ataques remotos autorizados usam por padrão a política de baixo ruído para toda a execução: HTTP nativo medido apenas, ritmo abaixo de 1 RPS, teto de requisições físicas, cache e deduplicação conservadores de GET/HEAD, backoff adaptativo, novas tentativas limitadas e circuit breaking. O ledger durável sobrevive à retomada. Os detalhes estão em Arquitetura.

Entenda os resultados

Ravage distingue observações, achados candidatos e vulnerabilidades confirmadas. Uma flag de CTF é uma possível prova, não um requisito. Em uma aplicação comum, uma execução pode ser útil e bem-sucedida sem encontrar nenhuma flag; vulnerabilidades confirmadas ainda são gravadas no relatório.

Quando uma execução de ataque começa, seu artefato canônico privado legível por máquina é RUN_DIR/report.json, incluindo execuções incompletas. --report também grava RUN_DIR/report.md.

ravage observe RUN_DIR
ravage audit verify RUN_DIR
ravage report RUN_DIR --brief ravage-brief.yaml

Para HTTP estruturado capturado pelo grafo do agente:

ravage traffic list RUN_DIR
ravage traffic show RUN_DIR REQUEST_ID

O relatório inclui referências de evidências, qualidade da contabilização de requisições, status de conclusão e o motivo pelo qual uma execução incompleta parou. Nunca trate uma afirmação de modelo não validada como um achado confirmado.

Recursos

Habilidades de conhecimento podem orientar a priorização, mas não podem adicionar ferramentas, expandir escopo ou confirmar achados. Comece com:

ravage skills list builtin
ravage skills validate builtin

O Laboratório de Melhorias ingere a estrutura sanitizada de execuções anteriores, avalia patches candidatos em workspaces independentes, arquiva versões aceitas e rejeitadas e exige evidências correspondentes de não-regressão antes da promoção. É um sidecar: não muta o checkout do código-fonte nem se promove silenciosamente.

Artefatos passivos orbitais e de pacotes podem ser inspecionados separadamente:

ravage satcom inspect orbit.tle --format tle --output orbit-report.json
ravage satcom inspect capture.bin \
  --format ccsds-space-packets \
  --direction auto \
  --output packet-report.json

O suporte a SATCOM é análise e parsing passivos, não um transmissor de rádio ou sistema de controle de espaçonave.

Desenvolvimento

scripts/bootstrap.sh --dev
source .venv/bin/activate
python -m pytest -m "not integration" -q
python -m ruff check --select E9,F .
python scripts/qa/check_docs.py
python scripts/qa/check_release.py

Testes de integração com Docker e comparações XBEN congeladas são portões de lançamento separados. Leia Benchmarking antes de interpretar resultados de casos; uma flag de sorte não é evidência de uma melhoria confiável.

Documentação

• Como usar Ravage
• Configuração e solução de problemas
• Autenticação
• Arquitetura
• Habilidades
• SATCOM passivo
• Laboratório de Melhorias
• Benchmarking
• Política de segurança
• Contribuindo

Use ravage --help e ravage COMMAND --help para as opções exatas no seu checkout.

Licença

Apache License 2.0. Consulte LICENSE, DISCLAIMER e SECURITY.md.