Metadata-Version: 2.5
Name: r3d-agent
Version: 0.2.12
Summary: Autonomous AI penetration testing CLI agent with a built-in exploit engine
License: MIT
License-File: LICENSE
Keywords: agent,ai,cli,exploit,pentest,security
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: openai>=1.50.0
Requires-Dist: prompt-toolkit<4,>=3.0.43
Requires-Dist: pydantic>=2.7.0
Requires-Dist: rich>=13.7.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: web
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'web'
Description-Content-Type: text/markdown

# 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

| Area | Details |
|------|---------|
| **Agent loop** | Plan → Act → Observe → Re-plan (ReAct). Streaming tool-use with any supported LLM. |
| **Providers** | Anthropic Claude, OpenAI / OpenRouter / Groq / Ollama / vLLM (any OpenAI-compatible endpoint). |
| **Tools** | Shell, file I/O, findings recorder, exploit engine, payload generator, web search (Perplexity / Jina). |
| **Exploit engine** | Pluggable modules (check → exploit), automatic ranking. Ships with example PHP-CGI arg-injection. |
| **Payload generator** | Reverse & bind shells for Linux/Windows/PHP/Python/Node/Ruby/Java. Base64/gzip/XOR/printf encoding. |
| **Safety** | Command allow/block-lists, risk matrix (strict / normal / unsafe), human-in-the-loop confirm. |
| **Audit** | SHA-256 hash-chained JSONL log — tamper-evident, verifiable with `r3d audit verify`. |
| **Reports** | Markdown, JSON and self-contained HTML. Findings with severity, evidence, remediation. |
| **Cross-platform** | Linux, macOS, Windows, Android/Termux. Auto-detects OS, arch, shell. No root required on Termux. |

---

## Quick start

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

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

| Platform | Path |
|----------|------|
| Linux / macOS | `~/.config/r3d/config.toml` |
| Windows | `%APPDATA%\r3d\config.toml` |
| Termux | `~/.config/r3d/config.toml` |

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:

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

```bash
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](LICENSE).

---

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