ravage - AI powered web security testing for authorized tar

项目说明

<p align="center">
<img src="assets/ra.png" alt="Ravage logo" width="360">
</p>

Ravage

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

<p align="center">
<img src="assets/demo.gif" alt="Ravage running an authorized local XBEN benchmark" width="997">
<br>
_{Illustrati XBEN run; paths and lifecycle options vary by preset.}
</p>

Ravage is a pre-1.0 research alpha. Use disposable en 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

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

Install from source

~~~bash
git clone
cd ravage
scripts/bootstrap.sh
source .venv/bin/activate
ravage doctor
~~~

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

Fi local quickstart

Start your application first. This example assumes it is listening on
<code>

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

~~~bash
ravage init \
--brief ra.yaml \
--en .en \
--description "Authorized assessment of my local de app."
~~~

2. Review <code>ra.yaml</code>. Check the target, in-scope routes,
exclusions, request budget, rate limit, objectives, and success criteria.

3. Run a no-model surface scan:

~~~bash
ravage doctor --workflow scan --brief ra.yaml
ravage scan ra.yaml --probe surface_map --report
~~~

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

Run the model-dri

Add a supported provider key, such as <code>OPENAI_API_KEY</code>, to
<code>.en</code>. Ravage reads this file directly; do not shell-source
it.

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

For an application checkout you are authorized to test, opt into source-guided
with a local Python source directory:

~~~bash
ravage attack ra.yaml \
--source-root /path/to/application \
--allow-paid-models \
--report
~~~

This mode maps bounded Flask and FastAPI route-to-sink flows locally, adds only
structural metadata to the attack surface, and automatically only
statically bound, non-mutating GET/query SQL-injection hypotheses whose complete
scalar query shape is known. POST, body, form, path, dynamic, and relatively
bound candidates remain prioritization hints. Tra is capped by files,
bytes, directories, and directory entries; included source that exceeds a cap
fails closed. Hidden, temporary, , ,
dependency, cache, and build directories are excluded and reported. These
exclusions and static matches are not li: Ravage still requires
differential runtime
e. The private source map contains structural identifiers such as route
and input names, relative file paths, and line numbers; a bounded subset is
sent to the configured model. Source snippets, function bodies, unrelated
constant , and absolute source paths are not stored or sent.
Dynamic routes, unsupported route or direct-flow patterns, skipped symlinks,
and files that cannot be parsed can reduce co; the run records that
co as incomplete instead of claiming a clean result. Here,
<code>analysis_complete</code> means every included file parsed and every
recognized bounded pattern was handled. It is not a claim of whole-program
co. Resume requires the same source snapshot, analyzer contract, and
candidate map.

For read-only review across UTF-8 source, configuration, and documentation files,
use the separate repository-review agent:

~~~bash
ravage review /path/to/application
~~~

It can autonomously list files and omissions, search text, and request bounded
excerpts from one frozen snapshot. It has no target, shell, browser, probe, or
project-execution tools. Results are model-authored source-review candidates with
references generated from exact captured excerpts. The JSON keeps paths, lines,
excerpt and file digests, and the snapshot identity; it does not persist the raw
snapshot. The default model profile is local; selecting a hosted profile requires
<code>--allow-paid-models</code> and sends requested source context to that
provider. See
Offline Repository Context.

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

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

Hosted models receive the engagement brief, selected discovered state, prior
findings, and tool obser 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 sensiti or
production data unless the engagement permits that disclosure. Use a local
model route when target e must remain local.

Li

Local XBEN

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

~~~bash
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 e under
<code>runs/demo</code>, 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 li demo, Ravage can assess HCL AppScan's deliberately
TestFire banking site. HCL publishes
<a href=" as a dynamic scanning sample</a>.
Review that authorization, export <code>OPENAI_API_KEY</code>, and explicitly
acknowledge the remote target:

~~~bash
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
; 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-destructi finding. The target is a shared public demo and
may occasionally be una or reset by its operator.

Authenticated testing

Add a dedicated test identity to the brief:

~~~bash
ravage auth add ra.yaml \
--identity user \
--type form \
--login /login \
--health /account \
--marker Logout \
--en .en
~~~

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

~~~bash
ravage auth check ra.yaml --identity user
ravage attack ra.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:

~~~bash
ravage auth map ra.yaml \
--identity alice \
--identity bob \
--include-anonymous
~~~

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

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

~~~bash
ravage auth matrix ra.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:

~~~bash
ravage init \
--brief ra.yaml \
--en .en \
--description "Authorized assessment of my staging application."

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

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

For a model-dri run:

~~~bash
ravage attack ra.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, conser
GET/HEAD caching and deduplication, adapti, bounded retries, and
circuit breaking. The durable ledger survi. Details are in
Architecture.

Understand the results

Ravage distinguishes obser, candidate findings, and confirmed
. 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 are still written to the report.

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

~~~bash
ravage obser
ravage audit RUN_DIR
ravage report RUN_DIR --brief ra.yaml
~~~

For structured HTTP captured by the agent graph:

~~~bash
ravage traffic list RUN_DIR
ravage traffic show RUN_DIR REQUEST_ID
~~~

The report includes e references, request-accounting quality, completion
status, and the reason an incomplete run stopped. Missing or unreadable expected
e makes the report incomplete; an empty incomplete report has Unknown
risk. Ne an un model assertion as a confirmed finding.

ravage observe prints a private, temporary access link. The obser
authenticated requests for run data and actions and binds to loopback by default.

Capabilities

| Capability | Entry point | Notes |
| --- | --- | --- |
| Deterministic recon and probes | <code>ravage scan</code> | No model required |
| Model-dri | <code>ravage attack</code> | E and scoped |
| Source-guided | <code>ravage attack --source-root</code> | Local Flask/FastAPI mapping; li required |
| Read-only repository review | <code>ravage review</code> | Frozen multi-language text context; source-backed candidates |
| Managed authentication | <code>ravage auth</code> | Sessions, role-aware map, authorization matrix |
| Traffic inspection and replay | <code>ravage traffic</code> | Scoped artifacts |
| Knowledge skills | <code>ravage skills</code>, <code>ravage code-bug</code> | Ad |
| Passi inspection | <code>ravage satcom inspect</code> | No transmit |
| Curated li | <code>ravage demo xben</code>, <code>ravage demo testfire</code> | Local XBEN or scope-locked HCL TestFire target |
| XBEN e | <code>ravage xben</code> | Docker-based research harness |
| Impro Lab | <code>scripts/impro.py</code> | Isolated archive |

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

~~~bash
ravage skills list builtin
ravage skills builtin
~~~

The Impro Lab ingests sanitized prior-run
structure, e candidate patches in independent workspaces, archives
accepted and rejected , and requires matched no-regression e
before promotion. Promotable receipts must trace back to separately signed,
archi e. It is a sidecar: it does not mutate the source
checkout or silently promote itself.

Passi and packet artifacts can be inspected separately:

~~~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
~~~

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

De

~~~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
~~~

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

Documentation

Use <code>ravage --help</code> and <code>ravage COMMAND --help</code> for the
exact options in your checkout.

License

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

项目信息

开发语言：Python

Star 数：50

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕AI powered web security testing for authorized targets展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。