Evidencia primero de pruebas autónomas de seguridad web para objetivos controlados y autorizados. Con laboratorios reproducibles, pistas de auditoría, informes y evaluación comparativa XBEN.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7171/c6015851ea85c8a14cf1ecf4737ff05aaafe1413ed484c69d433e3700aa1c1b8.png" alt="Ravage logo" width="360">
</p>
# Ravage
Ravage es una CLI basada en evidencia para evaluar una aplicación web en ejecución que
posees o para la que tienes autorización explícita de prueba. Combina reconocimiento
y validación deterministas con un bucle de ataque opcional guiado por modelos, manteniendo
el alcance, la autenticación, el registro de tráfico y la evidencia dentro de límites
controlados por código.
Ravage es un alfa de investigación previa a la versión 1.0. Usa entornos desechables y un
acuerdo de reglas de enfrentamiento por escrito. Las pruebas de seguridad pueden cambiar el estado de la aplicación; Ravage
no corrige hallazgos ni implementa soluciones.
[Inicio rápido](#inicio-rápido-local-en-cinco-minutos) ·
[Autenticación](#pruebas-autenticadas) ·
[Resultados](#comprender-los-resultados) ·
[Capacidades](#capacidades) ·
[Documentación](#documentación)
## Requisitos
- Python 3.12
- Git
- macOS, Linux o WSL
- Docker solo para herramientas contenedorizadas, XBEN y pruebas de integración
- Una clave de API del proveedor solo para comandos guiados por modelos
El primer escaneo normal no necesita clave de modelo, navegador, demonio de Docker ni
escáner externo.
## Instalación desde el código fuente
~~~bash
git clone https://github.com/duriantaco/ravage.git
cd ravage
scripts/bootstrap.sh
source .venv/bin/activate
ravage doctor
~~~
El bootstrap crea <code>.venv</code> e instala el espacio de trabajo. Usa
<code>scripts/bootstrap.sh --dev</code> para dependencias de desarrollo,
<code>--browser</code> para soporte de navegador, o
<code>--install-browser</code> para instalar también Chromium.
## Inicio rápido local en cinco minutos
Inicia tu aplicación primero. Este ejemplo asume que está escuchando en
<code>http://127.0.0.1:3000</code>.
1. Crea un informe de compromiso con alcance y un archivo de entorno privado:
~~~bash
ravage init http://127.0.0.1:3000 \
--brief ravage-brief.yaml \
--env-file .env.ravage \
--description "Evaluación autorizada de mi aplicación de desarrollo local."
~~~
2. Revisa <code>ravage-brief.yaml</code>. Verifica el objetivo, las rutas dentro del alcance,
las exclusiones, el presupuesto de solicitudes, el límite de velocidad, los objetivos y los criterios de éxito.
3. Ejecuta un escaneo de superficie sin modelo:
~~~bash
ravage doctor --workflow scan --brief ravage-brief.yaml
ravage scan ravage-brief.yaml --probe surface_map --report
~~~
El comando imprime el directorio de ejecución. Copia esa ruta y úsala como
<code>RUN_DIR</code> en los comandos de inspección a continuación.
## Ejecutar el agente guiado por modelos
Agrega una clave de proveedor compatible, como <code>OPENAI_API_KEY</code>, a
<code>.env.ravage</code>. Ravage lee este archivo directamente; no lo cargues desde el shell.
~~~bash
ravage doctor --workflow attack --brief ravage-brief.yaml
ravage attack ravage-brief.yaml --allow-paid-models --report
~~~
<code>--allow-paid-models</code> es un reconocimiento explícito de que la ejecución
puede generar cargos del proveedor. La selección de modelos, los proveedores locales y los perfiles
reproducibles están documentados en [Proveedores de modelos](https://github.com/duriantaco/ravage/blob/main/docs/model-providers.md).
## Pruebas autenticadas
Agrega una identidad de prueba dedicada al informe:
~~~bash
ravage auth add ravage-brief.yaml \
--identity user \
--type form \
--login /login \
--health /account \
--marker Logout \
--env-file .env.ravage
~~~
Completa las referencias de secretos generadas, verifica la sesión y luego ataca con
la identidad seleccionada:
~~~bash
ravage auth check ravage-brief.yaml --identity user
ravage attack ravage-brief.yaml \
--identity user \
--allow-paid-models \
--report
~~~
Se admiten inicio de sesión por formulario, tokens de portador y encabezados estáticos fijos. Las credenciales
gestionadas permanecen dentro del propietario HTTP autenticado; los canales de proceso, Python y
comandos están bloqueados cuando se selecciona una identidad. Consulta
[Autenticación](https://github.com/duriantaco/ravage/blob/main/docs/authentication.md) para la configuración y las limitaciones.
## Objetivos remotos autorizados
La ejecución remota es de cierre seguro ante fallos y requiere una bandera explícita. Comienza con un
escaneo de superficie de bajo impacto:
~~~bash
ravage init https://staging.example.test \
--brief ravage-brief.yaml \
--env-file .env.ravage \
--description "Evaluación autorizada de mi aplicación 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 una ejecución remota guiada por modelos:
~~~bash
ravage attack ravage-brief.yaml \
--authorized-remote-target \
--allow-paid-models \
--report
~~~
Los ataques remotos autorizados usan por defecto la política de bajo ruido para toda la ejecución: HTTP
nativo medido únicamente, ritmo inferior a 1 RPS, un límite físico de solicitudes, almacenamiento en caché
y deduplicación conservadores de GET/HEAD, retroceso adaptativo, reintentos limitados y
corte de circuito. El registro duradero sobrevive a la reanudación. Los detalles están en
[Arquitectura](https://github.com/duriantaco/ravage/blob/main/docs/architecture.md).
## Comprender los resultados
Ravage distingue observaciones, hallazgos candidatos y vulnerabilidades
confirmadas. Una bandera CTF es una posible prueba, no un requisito. En una
aplicación ordinaria, una ejecución puede ser útil y exitosa sin encontrar ninguna
bandera; las vulnerabilidades confirmadas aún se escriben en el informe.
Una vez que comienza una ejecución de ataque, su artefacto canónico privado legible por máquina es
<code>RUN_DIR/report.json</code>, incluidas las ejecuciones incompletas.
<code>--report</code> también escribe <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 estructurado capturado por el grafo del agente:
~~~bash
ravage traffic list RUN_DIR
ravage traffic show RUN_DIR REQUEST_ID
~~~
El informe incluye referencias de evidencia, calidad del registro de solicitudes, estado de
finalización y la razón por la que se detuvo una ejecución incompleta. Nunca trates una afirmación
de modelo no validada como un hallazgo confirmado.
## Capacidades
| Capacidad | Punto de entrada | Notas |
| --- | --- | --- |
| Reconocimiento y sondas deterministas | <code>ravage scan</code> | No requiere modelo |
| Evaluación guiada por modelos | <code>ravage attack</code> | Limitada por evidencia y alcance |
| Autenticación gestionada | <code>ravage auth</code> | Formulario, portador, encabezado estático |
| Inspección y reproducción de tráfico | <code>ravage traffic</code> | Artefactos con alcance |
| Habilidades de conocimiento | <code>ravage skills</code>, <code>ravage code-bug</code> | Consultivo |
| Inspección pasiva SATCOM | <code>ravage satcom inspect</code> | Sin transmisión |
| Evaluación XBEN | <code>ravage xben</code> | Entorno de investigación basado en Docker |
| Laboratorio de mejora | <code>scripts/improvement_lab.py</code> | Archivo aislado |
Las habilidades de conocimiento pueden guiar la priorización, pero no pueden agregar herramientas, ampliar el alcance
ni confirmar hallazgos. Comienza con:
~~~bash
ravage skills list builtin
ravage skills validate builtin
~~~
El [Laboratorio de mejora](https://github.com/duriantaco/ravage/blob/main/docs/improvement-lab.md) ingiere la estructura de ejecuciones anteriores
saneada, evalúa parches candidatos en espacios de trabajo independientes, archiva
versiones aceptadas y rechazadas, y requiere evidencia de no regresión coincidente antes de la
promoción. Es un componente auxiliar: no muta el checkout del código fuente ni
se promueve silenciosamente.
Los artefactos pasivos orbitales y de paquetes se pueden inspeccionar por separado:
~~~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
~~~
El soporte SATCOM es análisis y parseo pasivo, no un transmisor de radio ni un
sistema de control de naves espaciales.
## Desarrollo
~~~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
~~~
Las pruebas de integración respaldadas por Docker y las comparaciones XBEN congeladas son
compuertas de lanzamiento separadas. Lee [Evaluación comparativa](https://github.com/duriantaco/ravage/blob/main/docs/benchmarking.md) antes de interpretar
los resultados de casos; una bandera afortunada no es evidencia de una mejora confiable.
## Documentación
- [Cómo usar Ravage](https://github.com/duriantaco/ravage/blob/main/docs/how-to-use.md)
- [Configuración y solución de problemas](https://github.com/duriantaco/ravage/blob/main/docs/setup.md)
- [Autenticación](https://github.com/duriantaco/ravage/blob/main/docs/authentication.md)
- [Arquitectura](https://github.com/duriantaco/ravage/blob/main/docs/architecture.md)
- [Habilidades](https://github.com/duriantaco/ravage/blob/main/docs/skills.md)
- [SATCOM pasivo](https://github.com/duriantaco/ravage/blob/main/docs/satcom.md)
- [Laboratorio de mejora](https://github.com/duriantaco/ravage/blob/main/docs/improvement-lab.md)
- [Evaluación comparativa](https://github.com/duriantaco/ravage/blob/main/docs/benchmarking.md)
- [Política de seguridad](https://github.com/duriantaco/ravage/blob/main/SECURITY.md)
- [Contribuciones](https://github.com/duriantaco/ravage/blob/main/CONTRIBUTING.md)
Usa <code>ravage --help</code> y <code>ravage COMMAND --help</code> para las
opciones exactas en tu checkout.
## Licencia
Licencia Apache 2.0. Consulta [LICENSE](https://github.com/duriantaco/ravage/blob/main/LICENSE), [DISCLAIMER](https://github.com/duriantaco/ravage/blob/main/DISCLAIMER.md) y
[SECURITY.md](https://github.com/duriantaco/ravage/blob/main/SECURITY.md).