Metadata-Version: 2.5
Name: redveil
Version: 0.1.0
Summary: Production-quality web vulnerability PoC & evidence framework for authorized security testing
Author: Security Research Team
License: MIT
License-File: LICENSE
Keywords: bug-bounty,evidence,pentest,poc,security,vdp,vulnerability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.3; extra == 'dev'
Description-Content-Type: text/markdown

# 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.

[![status](https://img.shields.io/badge/status-Phase_1--5_complete-brightgreen)](#status)
[![checks](https://img.shields.io/badge/built--in_checks-17-blue)](#plugins)
[![python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue)](#installation)
[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)

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

```bash
# 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:

```toml
[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](USER_GUIDE.md) — installation, concepts, CLI reference,
  scope configuration examples, output interpretation, safety, and
  troubleshooting.
- [CHANGELOG.md](CHANGELOG.md) — version history and release notes.
- [docs/architecture.md](docs/architecture.md) — internal architecture,
  request lifecycle, safety model, plugin contract, event taxonomy, and
  testing strategy.
- [examples/](examples/) — runnable scope file templates for staging,
  authenticated, multi-principal, and OOB scenarios.

## License

MIT — see [LICENSE](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.