ravage

Ravage Docs

This directory backs the GitHub Pages documentation. The linked docs below are the current operator and technical references for the source-checkout workspace.

New readers should start with Setup, then How To Use. Setup covers ravage init, ravage setup check, tools, models, and brief basics; How To Use gives the shortest path from checkout to local lab run to report inspection.

The current evidence release is the frozen Ravage-only 2026-07-12 XBEN baseline: 85 / 104 exact flags with provider-usage list-price cost accounting. A cross-agent referee table has not yet been published.

The operational source of truth is:

• README: current project summary, source install, quickstart, validation, and packaging status.
• Setup: source install, ravage init, ravage setup check, external tool runtime, model routes, brief setup, remote-target flags, and troubleshooting.
• How To Use: practical install, local labs, attack, scan, observation, memory, XBEN, and troubleshooting.
• AI Web Operator Guide: running ravage attack, ravage scan, local tools, lab boxes, observation, and troubleshooting.
• Model Providers: Ollama, LM Studio, vLLM, LiteLLM, hosted OpenAI, native Anthropic Claude, and model route inspection.
• Memory Design: planned local SQLite memory model, redaction, review policy, retention, and evaluation standard.
• Benchmarking: XBEN validation, preflight, hosted-model canaries, scoring, evidence, and report interpretation.
• XBEN Comparison Runbook: description-only comparison contract, canary command, and report acceptance checks.
• Current XBEN Evidence: frozen 85 / 104 Run 3 result, cost accounting, provenance, audit, and hashes.
• Competitor Harness: isolated external-agent comparison, disk preflight, adapter shape, and false-positive scoring.
• Referee Launch Plan: current evidence-release copy and the proof requirements for a future cross-agent table.
• Run 3 Execution Record: historical frozen GPT-5.4 route, pricing, benchmark commit, command, and run contract.
• Benchmarks And Local Test Boxes: lab matrix, flag counts, local scoring policy, and latest recorded local run notes.

The technical source of truth is:

• Architecture: current implemented system design, model loop, tool runtime, source-guided workflows, evidence gates, and safety model.
• Open Core And Pro Reports: Apache-2.0 core, paid report formats, and the ravage_pro.report extension contract.
• Technical Guide: code map, model/action contract, workflow rules, evidence rules, XBEN modes, and test strategy.
• Differentiation Roadmap: roadmap and remaining product/engineering gaps.

Superseded execution plans live under archive/ as repository history and are excluded from the published docs site. If historical material conflicts with ravage --help, Architecture, or Technical Guide, the current docs and CLI help win.

Current Truth

Ravage is a source-checkout research workspace with publishable package boundaries. The current public command is ravage, provided by the packages/ravage workspace member. The runtime package boundary is packages/ravage; the repository root remains a development workspace and should not be published as the package. Shared schemas are packaged as ravage-schemas, while their Python import path remains pentest_schemas. Publishable package versions follow semantic versioning and should match release tags such as vMAJOR.MINOR.PATCH.

ravage attack runs the real model-driven ai-web loop. It calls an OpenAI-compatible model, requires a JSON action, executes a scoped tool, records the observation, and repeats until final or the turn budget is reached. It writes report.json, audit.db, stdout, and workspace artifacts.

ravage scan is deterministic DAST. It performs scoped discovery and typed probes without an LLM action loop, writes the same run shape as attack, and supports explicit resume from a run directory, workspace directory, or report.json.

Tool runtime is capability-aware. Briefs can declare required and optional capabilities such as port_scan, dir_bruteforce, and crawl. Ravage writes workspace/capabilities.json, blocks missing required capabilities before model spend unless --allow-degraded is passed, and tells the agent which tools or fallbacks are available. The ravage-perimeter-box lab now exercises this path with a two-port local target that needs scoped port scanning and content discovery before the full attack surface is visible.

Local lab boxes are intentionally vulnerable and must stay local or isolated:

• ravage-acme-box: 4 flags, medium.
• ravage-forgeops-box: 6 flags, hard.
• ravage-node-market-box: 5 flags, medium.
• ravage-perimeter-box: 5 flags, hard, multi-port recon.

Ravage Memory is design-stage in the current public CLI. Public benchmark and agent runs should keep memory off unless a future release explicitly exposes reviewed memory modes in ravage --help.

Fake-model tests only prove loop mechanics and scoring behavior. They are not benchmark performance.

XBEN support has explicit context modes:

• black-box: benchmark description is visible; source code, case names, and difficulty levels are withheld.
• white-box: source context may guide candidates, but reported findings still require dynamic confirmation.

This site is open source. Improve this page.