redveil

Evidence-first web vulnerability PoC framework. Not an exploit toolkit.

redveil is a defensive security assessment framework that runs an auditable discover → detect → safely validate → collect evidence → assess → report pipeline against a target web application. Every outbound HTTP request passes through a strict scope controller, every component reports progress through an in-process event bus, and every finding ships with reproducible request artifacts and step-by-step reproduction procedures.

What it is

redveil is a CLI-first framework for authorized web security assessments. You give it a scope file describing where it is allowed to send requests and what credentials to use, and it produces a Markdown / JSON / HTML report of every finding it can prove — without writing a single exploit payload. Every finding includes a sanitized cURL command that reproduces it on demand, the captured response excerpt, the CWE / OWASP taxonomy tags, attack scenarios, code examples across multiple frameworks, and ordered remediation steps.

What it is NOT

• Not an exploit framework. No reverse shells, no persistence primitives, no credential extraction, no data exfiltration, no denial-of-service.
• Not a destructive payload toolkit. SQLi and CMDi are time-based blind probes only — they never extract rows, never execute commands.
• Not a public-internet scanner. The framework enforces a strict host allowlist and is intended for authorized assessment only.

Safety

Every check declares its required safety profile. The runtime refuses to execute any check that exceeds the operator's chosen profile. The profiles are PASSIVE (observation only), LOW_IMPACT (safe probes), and ACTIVE (authenticated IDOR, time-based blind SQLi, OOB SSRF via the operator's callback domain, time-based CMDi detection — each bounded and non-destructive).

The ACTIVE profile requires explicit acknowledged_safety_terms=true in the scope file. The framework will not include reverse shells, persistence, credential extraction, denial-of-service, or data destruction — by design and going forward.

Use only against systems you own or have explicit written authorization to test. The authors disclaim all responsibility for unauthorized use.

Quick example

# Install
git clone https://github.com/your-org/redveil.git
cd redveil
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Scan a public surface with default (PASSIVE) checks
redveil scan https://staging.example.com --scope examples/scope.staging.yaml

# List all built-in check plugins
redveil list-checks

# Re-render a report from an existing findings.json
redveil report reports/staging.example.com

Reports land under reports/<target-name>/ as summary.md, findings.json, per-finding findings/<id>.md, and a self-contained report.html.

Status

All five development phases are complete:

• Phase 1 — Configuration, scope controller, rate-limited HTTP client, plugin registry, event bus, lifecycle state machine, CLI.
• Phase 2 — Finding model, evidence store with sanitization, vulnerability knowledge base, deduplicator, report renderers.
• Phase 3 — Discovery (crawler, subdomain finder) and passive check plugins (security headers, CORS, methods, disclosure, source maps, open redirect indicator, session cookie).
• Phase 4 — Low-impact check plugins (reflected XSS, source map fingerprinting, additional disclosure heuristics).
• Phase 5 — Active check plugins (time-based blind SQLi, OOB SSRF, time-based CMDi, path traversal indicator, BOLA / IDOR across multiple test principals, BFLA, GraphQL introspection, mass assignment).

The release ships with 17 built-in check plugins and 900+ unit and integration tests. The local vulnerable Flask lab under tests/lab/ exercises the full pipeline end-to-end.

Architecture

The package is organized into focused subpackages:

• core — orchestration, scope control, event bus, lifecycle
• http — async HTTP client, request/response abstractions, rate limiter
• discovery — crawling, endpoint and parameter enumeration
• checks — 17 built-in vulnerability check plugins
• validation — safe-in-place validators and PoC executors
• evidence — request/response capture, hashing, sanitization
• findings — finding model, severity scoring, deduplication
• reporting — report renderers (Markdown, JSON, HTML)
• plugins — plugin discovery and the Check base class
• cli — Typer-based command-line interface

Plugins

Every check is a plugin. Adding a new check means subclassing redveil.plugins.base.Check, declaring metadata (id, name, category, safety profile, CWE / OWASP tags), and registering through the redveil.checks entry-point group:

[project.entry-points."redveil.checks"]
my-check = "my_pkg.checks.my_check:MyCheck"

The orchestrator wires each plugin with the framework's HTTP client and scope controller. Plugins cannot instantiate their own HTTP client — bind() validates that the supplied client is bound to the orchestrator's scope.

Documentation

• USER_GUIDE.md — installation, concepts, CLI reference, scope configuration examples, output interpretation, safety, and troubleshooting.
• CHANGELOG.md — version history and release notes.
• docs/architecture.md — internal architecture, request lifecycle, safety model, plugin contract, event taxonomy, and testing strategy.
• examples/ — runnable scope file templates for staging, authenticated, multi-principal, and OOB scenarios.

License

MIT — see LICENSE.

Disclaimer

This tool is provided for defensive security testing only. The authors disclaim all responsibility for any unauthorized or unlawful use. Always obtain explicit, written authorization before testing any system you do not own.