Ravage

Ravage is an evidence-first CLI for assessing a running web application that you own or are explicitly authorized to test. It combines deterministic reconnaissance and validation with an optional model-driven attack loop, while keeping scope, authentication, traffic accounting, and evidence in code-owned boundaries.

Ravage is a pre-1.0 research alpha. Use disposable environments and a written rules of engagement. Security testing can change application state; Ravage does not remediate findings or deploy fixes.

Quickstart · Authentication · Results · Capabilities · Documentation

Requirements

• Python 3.12
• Git
• macOS, Linux, or WSL
• Docker only for containerized tools, XBEN, and integration tests
• A provider API key only for model-driven commands

The normal first scan needs no model key, browser, Docker daemon, or external scanner.

Install from source

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

The bootstrap creates .venv and installs the workspace. Use scripts/bootstrap.sh --dev for development dependencies, --browser for browser support, or --install-browser to install Chromium as well.

Five-minute local quickstart

Start your application first. This example assumes it is listening on http://127.0.0.1:3000.

1. Create a scoped engagement brief and private environment file:

   root@kitploit:~

   ravage init http://127.0.0.1:3000 \
     --brief ravage-brief.yaml \
     --env-file .env.ravage \
     --description "Authorized assessment of my local development app."
   

2. Review ravage-brief.yaml. Check the target, in-scope routes, exclusions, request budget, rate limit, objectives, and success criteria.

3. Run a no-model surface scan:

   root@kitploit:~

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

The command prints the run directory. Copy that path and use it as RUN_DIR in the inspection commands below.

Run the model-driven agent

Add a supported provider key, such as OPENAI_API_KEY, to .env.ravage. Ravage reads this file directly; do not shell-source it.

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

--allow-paid-models is an explicit acknowledgement that the run can incur provider charges. Model selection, local providers, and reproducible profiles are documented in Model providers.

Authenticated testing

Add a dedicated test identity to the brief:

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

Fill in the generated secret references, verify the session, then attack with the selected identity:

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

Form login, bearer tokens, and fixed static headers are supported. Managed credentials stay inside the authenticated HTTP owner; process, Python, and command lanes are blocked when an identity is selected. See Authentication for setup and limitations.

Authorized remote targets

Remote execution is fail-closed and requires an explicit flag. Start with a low-impact surface scan:

ravage init https://staging.example.test \
  --brief ravage-brief.yaml \
  --env-file .env.ravage \
  --description "Authorized assessment of my staging application."

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

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

For a model-driven remote run:

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

Authorized remote attacks default to the whole-run low-noise policy: native metered HTTP only, sub-1-RPS pacing, a physical-request ceiling, conservative GET/HEAD caching and deduplication, adaptive backoff, bounded retries, and circuit breaking. The durable ledger survives resume. Details are in Architecture.

Understand the results

Ravage distinguishes observations, candidate findings, and confirmed vulnerabilities. A CTF flag is one possible proof, not a requirement. On an ordinary application, a run can be useful and successful without finding any flag; confirmed vulnerabilities are still written to the report.

Once an attack run starts, its canonical private machine-readable artifact is RUN_DIR/report.json, including incomplete runs. --report also writes RUN_DIR/report.md.

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

For structured HTTP captured by the agent graph:

ravage traffic list RUN_DIR
ravage traffic show RUN_DIR REQUEST_ID

The report includes evidence references, request-accounting quality, completion status, and the reason an incomplete run stopped. Never treat an unvalidated model assertion as a confirmed finding.

Capabilities

Knowledge skills can guide prioritization, but cannot add tools, expand scope, or confirm findings. Start with:

ravage skills list builtin
ravage skills validate builtin

The Improvement Lab ingests sanitized prior-run structure, evaluates candidate patches in independent workspaces, archives accepted and rejected versions, and requires matched no-regression evidence before promotion. It is a sidecar: it does not mutate the source checkout or silently promote itself.

Passive orbital and packet artifacts can be inspected separately:

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

SATCOM support is passive parsing and analysis, not a radio transmitter or spacecraft-control system.

Development

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

Docker-backed integration tests and frozen XBEN comparisons are separate release gates. Read Benchmarking before interpreting case results; one lucky flag is not evidence of a reliable improvement.

Documentation

• How to use Ravage
• Setup and troubleshooting
• Authentication
• Architecture
• Skills
• Passive SATCOM
• Improvement Lab
• Benchmarking
• Security policy
• Contributing

Use ravage --help and ravage COMMAND --help for the exact options in your checkout.

License

Apache License 2.0. See LICENSE, DISCLAIMER, and SECURITY.md.