R3D — Autonomous AI Pentest CLI Agent

v0.2.0 — Red-team reconnaissance, exploitation and reporting driven by LLMs.

R3D is a cross-platform CLI agent that plans and executes penetration-testing workflows autonomously. It pairs a ReAct agent loop with a built-in exploit engine, safety guardrails and hash-chained audit logging.

Features

Quick start

# 1. Install (Python ≥ 3.10)
pip install -e .          # from source
# — or —
pip install r3d-agent     # from PyPI (when published)

# 2. Set an LLM provider key
export ANTHROPIC_API_KEY="sk-ant-..."
# — or —
export OPENAI_API_KEY="sk-..."

# 3. Run
r3d "Scan 192.168.1.0/24 for common web vulnerabilities"
r3d scan 10.0.0.5 --ports 80,443,8080
r3d recon example.com --modules dns,whois,headers
r3d doctor                 # check environment health

Termux (Android, no root)

pkg install python rust binutils -y
pip install -e .
r3d doctor

CLI reference

r3d [GOAL]                  Interactive or one-shot agent run
r3d scan TARGET             Quick scan wrapper
r3d recon TARGET            Recon wrapper
r3d exploit TARGET          Exploit wrapper
r3d payload                 Generate payloads
r3d session list|resume|delete|export
r3d report SESSION_ID       Build report from session findings
r3d audit show|verify       Inspect / verify audit log
r3d config                  Show / wizard config
r3d tools                   List registered tools
r3d doctor                  Environment health check
r3d --version               Print version

Run r3d --help or r3d <command> --help for full details.

Configuration

R3D reads config.toml from a platform-appropriate location:

Settings can also be supplied via environment variables (R3D_PROVIDER, R3D_MODEL, R3D_SAFETY_MODE, …) or the CLI flags.

Run r3d config --wizard for an interactive setup.

Writing a custom tool

Create a Python package that exposes a class inheriting r3d.tools.base.BaseTool and register it as an entry point under the r3d.tools group:

# In your package's pyproject.toml
[project.entry-points."r3d.tools"]
my_tool = "my_package:MyTool"

R3D discovers and loads it automatically at startup.

Project layout

r3d/
├── __init__.py          # version
├── __main__.py          # python -m r3d
├── agent.py             # ReAct agent loop
├── audit.py             # hash-chained audit log
├── cli.py               # typer CLI
├── config.py            # TOML config + env overlay
├── context.py           # session / conversation state
├── errors.py            # exception hierarchy + retry
├── exploit.py           # exploit engine ABC + runner
├── exploits/            # built-in exploit modules
├── logger.py            # Rich console output
├── payloads.py          # shell generators + encoders
├── planner.py           # LLM planning step
├── providers/           # LLM provider adapters
│   ├── anthropic_provider.py
│   ├── openai_provider.py
│   └── retry.py         # failover wrapper
├── redact.py            # secret scrubbing
├── repl.py              # interactive REPL
├── report.py            # MD / JSON / HTML reporting
├── safety.py            # command risk checker
├── system_prompt.py     # dynamic system prompt builder
└── tools/               # agent tool implementations
    ├── shell.py
    ├── file.py
    ├── finding.py
    ├── exploit_tool.py
    └── web.py

Development

pip install -e ".[dev]" --break-system-packages
pytest                     # unit tests
pytest -m "not live"       # skip tests that call real APIs
ruff check r3d/            # lint
mypy r3d/                  # type check

License

MIT — see LICENSE.

Disclaimer: R3D is intended for authorized security testing only. Always obtain written permission before testing systems you do not own.