ravage

Setup

Ravage is source-checkout-first. Install from this repository and run the ravage CLI from the checkout virtual environment so the docs, examples, labs, and benchmark evidence match the code you are running.

Requirements

Use Ravage only on systems you own or are explicitly authorized to test. The active CLI is localhost-first. Public/DNS targets are blocked by default even when they are in scope; test a local or staging copy exposed on http://127.0.0.1:* or http://localhost:*.

Checkout Install

Use this path when developing or running directly from the repository:

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

Create the starter files:

ravage init --target-url http://127.0.0.1:8080

This writes:

Edit both files before running against a real target. .env is only a starter; keep real API keys private and do not commit them.

If you want to run the same steps manually, create a Python 3.12 virtualenv and install the repository root in editable mode:

python3.12 -m venv .venv
. .venv/bin/activate
python -m pip install "setuptools>=68" wheel
python -m pip install --no-build-isolation -e .
ravage --help

If an old virtualenv command still imports orchestrator, rerun bootstrap. It repairs stale .venv activation paths and reinstalls the editable checkout:

scripts/bootstrap.sh

Tool Runtime

Python package installation does not install scanners such as nmap, ffuf, katana, nuclei, or sqlmap.

Check what is available:

ravage tools list
ravage tools check

The recommended repeatable path is Docker. It hides host dependency drift and matches Ravage’s scoped tool-runtime path:

scripts/install_tools.sh --method docker --execute
ravage tools check

On Linux, Kali, or WSL where host tools are preferred:

scripts/install_tools.sh --method apt --execute
ravage tools check

On macOS with Homebrew:

scripts/install_tools.sh --method brew --execute
ravage tools check

To preview the install plan without changing the machine, omit --execute.

Run attacks and scans with --tool-runtime auto unless you need to force a specific path. auto uses the scoped Docker-backed path for supported external tools when scope firewalling is available.

Setup Check

Before spending model calls, run:

set -a; source .env; set +a
ravage setup check --brief brief.yaml --model-profile hosted-openai --model-tier low

ravage setup check validates:

If a check fails, the CLI prints a concrete fix and a [next] section with the next command to run. For machine-readable automation:

ravage setup check --brief brief.yaml --json

Human CLI output uses a green/cyan terminal theme by default in interactive terminals. Set RAVAGE_COLOR=never to disable it or RAVAGE_COLOR=always to force it in unusual terminal environments. JSON output stays plain.

First Local Run

Start a local lab:

ravage lab up ravage-acme-box

Run a no-model deterministic scan:

ravage scan examples/labs/ravage-acme-box/brief.yaml \
  --run-dir runs/quickstart-acme-scan \
  --tool-runtime auto

Verify outputs:

ravage audit verify runs/quickstart-acme-scan
python -m json.tool runs/quickstart-acme-scan/report.json | head -80

A healthy setup has a run directory with audit.db, report.json, scan.stdout, and workspace/.

Model Setup

Use the model-driven agent only after ravage scan works.

For a local OpenAI-compatible route such as Ollama:

RAVAGE_OLLAMA_MODEL=qwen2.5-coder:32b \
OLLAMA_BASE_URL=http://localhost:11434/v1 \
ravage attack examples/labs/ravage-acme-box/brief.yaml \
  --model-profile local-ollama \
  --model-tier mid \
  --tool-runtime auto \
  --memory off

For hosted OpenAI-compatible routes, set the provider key and explicitly acknowledge paid model use:

OPENAI_API_KEY=... \
ravage attack examples/labs/ravage-acme-box/brief.yaml \
  --model-profile hosted-openai \
  --model-tier low \
  --tool-runtime auto \
  --memory off \
  --allow-paid-models

Inspect route readiness before running:

ravage setup check --brief brief.yaml --model-profile hosted-openai --model-tier low

Provider-specific variables are documented in Model Providers.

Brief Setup

The wrapper commands infer --target-url from the first HTTP or HTTPS URL in scope.in_scope. If the brief starts with CIDRs, hostnames, or multiple allowed origins, either put the primary base URL first or pass --target-url explicitly.

Generate a starter brief from the CLI:

ravage init --target-url http://127.0.0.1:8080
ravage brief template --target-url http://127.0.0.1:8080 > brief.yaml
ravage brief template --help

Minimal brief:

engagement_id: "99999999-9999-4999-8999-999999999999"
scope:
  in_scope:
    - "http://127.0.0.1:8080"
  out_of_scope: []
roe:
  max_rps: 5
  no_destructive_actions: true
  data_handling: "placeholders_only"
objectives:
  - "web_application_assessment"
budget:
  max_cost_usd: 5.0
  max_runtime_min: 20

For a user-owned Docker or staging app, publish it to localhost and put that localhost URL in the brief:

ravage scan brief.yaml \
  --target-url http://127.0.0.1:8080 \
  --tool-runtime auto

If the engagement also needs a public hosting sanity check, keep the active target as localhost and add an explicit live website in brief context:

context:
  description: "Local staging copy of the app."
  hosting_check:
    live_site: "https://example.com"

When a Markdown report is written, Ravage runs a separate hosting-layer report agent after the localhost test and records curl -I results for HTTPS/HTTP apex and www variants in report.md.

Use web_application_assessment for normal web tests and api_security_assessment for API-heavy targets. Specific classes like xss, jwt, or sql_injection are better for targeted retests only. Clean benchmark or local CTF-style runs should keep broad objectives and let the agent derive hypotheses from the challenge description and live target evidence.

Troubleshooting

This site is open source. Improve this page.