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.

_{Illustrative local XBEN run; paths and lifecycle options vary by preset.}

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 ·
Live demo ·
Authentication ·
Results ·
Capabilities ·
Documentation

Requirements

• Python 3.12
• Git
• macOS, Linux, or WSL
• Docker for process-capable model-driven attacks, 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:

   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:

   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.

Unauthenticated process-capable attacks use Docker by default. Ravage never
silently falls back to host execution. The explicit
--tool-runtime host option runs model-selected shell and Python on
your machine; use it only in a disposable localhost environment. Child
processes receive a minimal environment without provider keys, but explicit
host execution can still read files available to your user account.

Hosted models receive the engagement brief, selected discovered state, prior
findings, and tool observations that may include target response data. That
information leaves your machine and is handled under the provider's terms and
retention controls. Do not use a hosted route for sensitive customer or
production data unless the engagement permits that disclosure. Use a local
model route when target evidence must remain local.

Live demos

Local XBEN

For a short live demo, set XBEN_ROOT to the benchmarks
directory in an XBEN checkout, start Docker, and export
OPENAI_API_KEY. Then run:

ravage demo xben

Ravage builds a fresh local XBEN-009 target, attacks it with the pinned
GPT-5.4 high profile, scores the result, saves the evidence under
runs/demo, and removes the target and its local image. The preset
limits the run to ten model requests, ten turns, ten minutes, and $1.50.

Authorized TestFire website

For a live domain-name demo, Ravage can assess HCL AppScan's deliberately
vulnerable TestFire banking site. HCL publishes
demo.testfire.net as a dynamic scanning sample.
Review that authorization, export OPENAI_API_KEY, and explicitly
acknowledge the remote target:

ravage demo testfire --authorized-remote-target

This command cannot accept another hostname. It permits only the curated login
routes, GET/HEAD plus the login POST, and a code-owned set of harmless login
values; stacked, destructive, and time-delay payloads are rejected before
dispatch. It also disables process, scanner, recovery, and autonomous lanes,
caps the whole run at 24 physical requests and 0.5 RPS, and stops after one
non-destructive, evidence-backed finding. The target is a shared public demo and
may occasionally be unavailable or reset by its operator.

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.

With at least two configured identities, first map which read-only routes each
role can see:

ravage auth map ravage-brief.yaml \
  --identity alice \
  --identity bob \
  --include-anonymous

The map follows a small, deterministic GET-only frontier across every selected
identity. It records conservatively shaped routes and parameter names, not
exact URLs, response bodies, or query values. Recognized IDs and ambiguous path
segments become placeholders. A difference is only a review candidate; it is
not a vulnerability claim.

Confirm a reviewed, operator-supplied resource with the authorization matrix:

ravage auth matrix ravage-brief.yaml authorization-matrix.yaml

The plan names each explicit GET URL, its allowed and denied actors (including
anonymous), and a secret-backed response marker. Ravage does not discover or
guess resource IDs. See the
authentication guide for map
safety limits, the matrix plan format, receipt boundaries, 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. Promotable receipts must trace back to separately signed,
archived execution evidence. 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.