Evidência primeiro teste de segurança web autônomo para alvos controlados e autorizados. Com laboratórios reproduzíveis, trilhas de auditoria, relatórios e benchmarking XBEN.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7171/c6015851ea85c8a14cf1ecf4737ff05aaafe1413ed484c69d433e3700aa1c1b8.png" alt="Ravage logo" width="360">
</p>
# 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](#início-rápido-local-em-cinco-minutos) ·
[Autenticação](#testes-autenticados) ·
[Resultados](#entenda-os-resultados) ·
[Recursos](#recursos) ·
[Documentação](#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
~~~bash
git clone https://github.com/duriantaco/ravage.git
cd ravage
scripts/bootstrap.sh
source .venv/bin/activate
ravage doctor
~~~
O bootstrap cria <code>.venv</code> e instala o workspace. Use
<code>scripts/bootstrap.sh --dev</code> para dependências de desenvolvimento,
<code>--browser</code> para suporte a navegador, ou
<code>--install-browser</code> 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
<code>http://127.0.0.1:3000</code>.
1. Crie um brief de engajamento com escopo e um arquivo de ambiente privado:
~~~bash
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 <code>ravage-brief.yaml</code>. 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:
~~~bash
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
<code>RUN_DIR</code> nos comandos de inspeção abaixo.
## Executar o agente orientado por modelo
Adicione uma chave de provedor compatível, como <code>OPENAI_API_KEY</code>, ao
<code>.env.ravage</code>. Ravage lê este arquivo diretamente; não o carregue via shell.
~~~bash
ravage doctor --workflow attack --brief ravage-brief.yaml
ravage attack ravage-brief.yaml --allow-paid-models --report
~~~
<code>--allow-paid-models</code> é 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](https://github.com/duriantaco/ravage/blob/main/docs/model-providers.md).
## Testes autenticados
Adicione uma identidade de teste dedicada ao brief:
~~~bash
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:
~~~bash
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](https://github.com/duriantaco/ravage/blob/main/docs/authentication.md) 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:
~~~bash
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:
~~~bash
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](https://github.com/duriantaco/ravage/blob/main/docs/architecture.md).
## 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 é
<code>RUN_DIR/report.json</code>, incluindo execuções incompletas.
<code>--report</code> também grava <code>RUN_DIR/report.md</code>.
~~~bash
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:
~~~bash
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
| Recurso | Ponto de entrada | Observações |
| --- | --- | --- |
| Reconhecimento e sondas determinísticos | <code>ravage scan</code> | Nenhum modelo necessário |
| Avaliação orientada por modelo | <code>ravage attack</code> | Limitada por evidências e escopo |
| Autenticação gerenciada | <code>ravage auth</code> | Formulário, bearer, cabeçalho estático |
| Inspeção e repetição de tráfego | <code>ravage traffic</code> | Artefatos com escopo |
| Habilidades de conhecimento | <code>ravage skills</code>, <code>ravage code-bug</code> | Consultivo |
| Inspeção passiva de SATCOM | <code>ravage satcom inspect</code> | Sem transmissão |
| Avaliação XBEN | <code>ravage xben</code> | Harness de pesquisa baseado em Docker |
| Laboratório de Melhorias | <code>scripts/improvement_lab.py</code> | Arquivo isolado |
Habilidades de conhecimento podem orientar a priorização, mas não podem adicionar ferramentas,
expandir escopo ou confirmar achados. Comece com:
~~~bash
ravage skills list builtin
ravage skills validate builtin
~~~
O [Laboratório de Melhorias](https://github.com/duriantaco/ravage/blob/main/docs/improvement-lab.md) 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:
~~~bash
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
~~~bash
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](https://github.com/duriantaco/ravage/blob/main/docs/benchmarking.md) antes de interpretar resultados de
casos; uma flag de sorte não é evidência de uma melhoria confiável.
## Documentação
- [Como usar Ravage](https://github.com/duriantaco/ravage/blob/main/docs/how-to-use.md)
- [Configuração e solução de problemas](https://github.com/duriantaco/ravage/blob/main/docs/setup.md)
- [Autenticação](https://github.com/duriantaco/ravage/blob/main/docs/authentication.md)
- [Arquitetura](https://github.com/duriantaco/ravage/blob/main/docs/architecture.md)
- [Habilidades](https://github.com/duriantaco/ravage/blob/main/docs/skills.md)
- [SATCOM passivo](https://github.com/duriantaco/ravage/blob/main/docs/satcom.md)
- [Laboratório de Melhorias](https://github.com/duriantaco/ravage/blob/main/docs/improvement-lab.md)
- [Benchmarking](https://github.com/duriantaco/ravage/blob/main/docs/benchmarking.md)
- [Política de segurança](https://github.com/duriantaco/ravage/blob/main/SECURITY.md)
- [Contribuindo](https://github.com/duriantaco/ravage/blob/main/CONTRIBUTING.md)
Use <code>ravage --help</code> e <code>ravage COMMAND --help</code> para as
opções exatas no seu checkout.
## Licença
Apache License 2.0. Consulte [LICENSE](https://github.com/duriantaco/ravage/blob/main/LICENSE), [DISCLAIMER](https://github.com/duriantaco/ravage/blob/main/DISCLAIMER.md) e
[SECURITY.md](https://github.com/duriantaco/ravage/blob/main/SECURITY.md).