# 19 – Pentesting Agent

End-to-end example of the **Ziran Pentesting Agent** — an LLM-driven
autonomous red-teaming loop that plans, executes, reasons, and reports
on the security posture of an AI agent.

## Architecture

```
┌──────────────┐
│  Orchestrator │
│  (public API) │
└──────┬───────┘
       │
  ┌────▼─────┐      ┌─────────────┐
  │ LangGraph │◄────►│ AgentScanner│
  │  4-node   │      │  (Ziran)    │
  │  graph    │      └─────────────┘
  └────┬──────┘
       │
  ┌────▼──────────┐
  │ Deduplicator  │
  │ (LLM embed.)  │
  └───────────────┘
```

## Prerequisites

| Requirement | Version |
|-------------|---------|
| Python      | ≥ 3.10  |
| Ziran       | ≥ 0.6.0 |
| OpenAI key  | any     |

```bash
pip install ziran[pentest]
# or
uv pip install ziran[pentest]
```

Set your LLM credentials in `examples/.env`:

```env
OPENAI_API_KEY=sk-...
```

## Files

| File              | Description                                      |
|-------------------|--------------------------------------------------|
| `main.py`         | Autonomous mode — fully automated pentesting run  |
| `interactive.py`  | Interactive mode — human-in-the-loop REPL          |
| `run.sh`          | Convenience launcher                               |

## Running

### Autonomous mode

```bash
# From repository root
./examples/19-pentesting-agent/run.sh

# Or directly
python examples/19-pentesting-agent/main.py
```

### Interactive mode

```bash
python examples/19-pentesting-agent/interactive.py
```

In interactive mode you can type directives like:

```
pentest> Focus on SQL injection via the search tool
pentest> Try to exfiltrate data through the email tool
pentest> status
pentest> quit
```

### CLI

```bash
ziran pentest \
  --framework mock \
  --goal "Find prompt injection vulnerabilities" \
  --llm-provider openai \
  --llm-model gpt-4o \
  --max-iterations 5
```

## Output

Reports are saved to `pentest_results/` in JSON and Markdown format.
