Metadata-Version: 2.4
Name: penbot
Version: 2.3.1
Summary: AI Chatbot Penetration Testing Framework
Author: terminal48
License: MIT
Project-URL: Homepage, https://gitlab.com/yan-ban/penbot
Project-URL: Documentation, https://gitlab.com/yan-ban/penbot/-/tree/main/docs
Project-URL: Repository, https://gitlab.com/yan-ban/penbot
Project-URL: Issues, https://gitlab.com/yan-ban/penbot/-/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langgraph>=0.2.0
Requires-Dist: langgraph-checkpoint-sqlite>=2.0.0
Requires-Dist: langchain>=0.2.0
Requires-Dist: langchain-anthropic>=0.1.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pydantic-settings>=2.2.0
Requires-Dist: click>=8.1.7
Requires-Dist: rich>=13.7.1
Requires-Dist: aiohttp>=3.9.4
Requires-Dist: httpx>=0.27.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: jsonpath-ng>=1.6.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: jinja2>=3.1.3
Requires-Dist: prometheus-client>=0.20.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: structlog>=24.1.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: langchain-openai>=0.1.0
Provides-Extra: full
Requires-Dist: fastapi>=0.110.0; extra == "full"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "full"
Requires-Dist: slowapi>=0.1.9; extra == "full"
Requires-Dist: PyJWT>=2.8.0; extra == "full"
Requires-Dist: playwright>=1.43.0; extra == "full"
Requires-Dist: weasyprint>=62.0; extra == "full"
Requires-Dist: reportlab>=4.1.0; extra == "full"
Requires-Dist: python-docx>=1.1.0; extra == "full"
Requires-Dist: pypdf>=4.0.0; extra == "full"
Requires-Dist: Pillow>=10.0.0; extra == "full"
Requires-Dist: prometheus-fastapi-instrumentator>=7.0.0; extra == "full"
Requires-Dist: tavily-python>=0.5.0; extra == "full"
Provides-Extra: recon
Requires-Dist: tavily-python>=0.5.0; extra == "recon"
Provides-Extra: think
Provides-Extra: ml
Requires-Dist: sentence-transformers>=2.2.0; extra == "ml"
Requires-Dist: faiss-cpu>=1.7.0; extra == "ml"
Requires-Dist: numpy>=1.24.0; extra == "ml"
Provides-Extra: ml-viz
Requires-Dist: sentence-transformers>=2.2.0; extra == "ml-viz"
Requires-Dist: faiss-cpu>=1.7.0; extra == "ml-viz"
Requires-Dist: numpy>=1.24.0; extra == "ml-viz"
Requires-Dist: scikit-learn>=1.3.0; extra == "ml-viz"
Requires-Dist: matplotlib>=3.8.0; extra == "ml-viz"
Provides-Extra: dev
Requires-Dist: pytest>=8.1.1; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.6; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: black>=24.3.0; extra == "dev"
Requires-Dist: ruff>=0.3.5; extra == "dev"
Dynamic: license-file

<div align="center">

```
██████╗ ███████╗███╗   ██╗██████╗  ██████╗ ████████╗
██╔══██╗██╔════╝████╗  ██║██╔══██╗██╔═══██╗╚══██╔══╝
██████╔╝█████╗  ██╔██╗ ██║██████╔╝██║   ██║   ██║   
██╔═══╝ ██╔══╝  ██║╚██╗██║██╔══██╗██║   ██║   ██║   
██║     ███████╗██║ ╚████║██████╔╝╚██████╔╝   ██║   
╚═╝     ╚══════╝╚═╝  ╚═══╝╚═════╝  ╚═════╝    ╚═╝   
```

<img src="docs/evidence/penbot_logo.png" alt="PenBot Logo" width="180"/>

</div>

[![PyPI version](https://img.shields.io/pypi/v/penbot.svg)](https://pypi.org/project/penbot/)
[![Pipeline Status](https://gitlab.com/yan-ban/penbot/badges/main/pipeline.svg)](https://gitlab.com/yan-ban/penbot/-/pipelines)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![OWASP LLM Top 10](https://img.shields.io/badge/OWASP-LLM%20Top%2010-orange.svg)](https://owasp.org/www-project-top-10-for-large-language-model-applications/)
[![OWASP ASI](https://img.shields.io/badge/OWASP-ASI%202026-red.svg)](https://genai.owasp.org/initiatives/agentic-security/)
[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](CONTRIBUTING.md)

Multi-agent adversarial testing framework for AI chatbots and agentic
systems. Orchestrates specialized security agents to find vulnerabilities
in conversational AI through prompt injection, social engineering,
encoding attacks, RAG poisoning, tool exploitation, and MCP protocol abuse.

---

## Install

```bash
pip install penbot              # Core: CLI + REST API testing
pip install penbot[full]        # Adds dashboard, Playwright, PDF/DOCX reports
pip install penbot[ml]          # Adds embedding-based attack memory
```

From source:

```bash
git clone https://gitlab.com/yan-ban/penbot.git
cd penbot
pip install -e .
```

Docker:

```bash
docker pull registry.gitlab.com/yan-ban/penbot:latest
```

---

## Run

```bash
penbot onboard                                  # First-run setup
penbot wizard                                   # Configure a target
penbot test --config configs/clients/target.yaml
penbot doctor                                   # Verify environment
```

Dashboard:

```bash
penbot dashboard   # http://localhost:8000/dashboard
```

---

## CLI

```
penbot onboard     First-run setup
penbot doctor      Environment health check
penbot wizard      Configure new target
penbot test        Run security test
penbot dashboard   Start Mission Control
penbot sessions    Manage past sessions
penbot agents      Browse agents
penbot patterns    Search attack library
penbot report      Generate report
penbot benchmark   Score detection against mock chatbots
penbot watch       Continuous testing
```

See [CLI Reference](docs/CLI_REFERENCE.md).

---

## Features

- **14 specialized agents** — jailbreak, encoding, social engineering, RAG, tool exploitation, MCP exploit, exfiltration, indirect injection, action safety, compliance, and more
- **1,398+ attack patterns** across 27 curated libraries (including 20 MCP protocol-attack patterns)
- **22 vulnerability detectors** — two-layer detection (pattern + LLM) with finding chaining and guardrail fingerprinting
- **OWASP LLM Top 10 (2025) + Agentic Top 10 (2026)** coverage, including ASI02 and ASI04
- **Model Context Protocol (MCP) testing** — tool-description poisoning, resource URI traversal, list_changed bait-and-switch, cross-server pivots, sampling API abuse
- **Multi-agent coordination** — voting, hybrid attack composition, domain-aware campaign planning
- **Persistence verification** — post-test replay confirms findings are reproducible
- **Endpoint reconnaissance** — two-phase API surface mapping with framework detection
- **Evolutionary generation** — novel attacks via genetic algorithms with semantic retrieval (sentence-transformers + FAISS)
- **Web dashboard** — live Mission Control, session replay, OWASP report, real-time WebSocket streaming
- **Regression testing and purple-team mode** for CI-friendly defense validation

---

## Technology

- **LangGraph** — multi-agent workflow orchestration
- **Claude Sonnet 4.5** — attack generation
- **FastAPI** — API + WebSocket server (requires `penbot[full]`)
- **Playwright** — browser automation (requires `penbot[full]`)
- **SQLite** — session persistence

### Install Extras

| Extra | Command | What it adds |
|-------|---------|-------------|
| Core | `pip install penbot` | CLI, REST API testing, security agents, attack pattern libraries |
| Full | `pip install penbot[full]` | Dashboard, Playwright, PDF/DOCX reports, OpenAI provider, Tavily recon |
| Recon | `pip install penbot[recon]` | Tavily web search for target reconnaissance |
| Think | `pip install penbot[think]` | MCP-based enhanced reasoning |
| ML | `pip install penbot[ml]` | Embedding-based attack memory (sentence-transformers, FAISS) |
| ML-Viz | `pip install penbot[ml-viz]` | ML + scikit-learn & matplotlib for notebooks |

---

## Documentation

| Document | Description |
|----------|-------------|
| [Developer Guide](docs/DEVELOPER_GUIDE.md) | How PenBot works under the hood |
| [Architecture](docs/ARCHITECTURE.md) | System design and diagrams |
| [Methodology](docs/METHODOLOGY.md) | Attack strategies |
| [Configuration](docs/CONFIGURATION.md) | YAML and environment setup |
| [CLI Reference](docs/CLI_REFERENCE.md) | Command-line usage |
| [API Reference](docs/API_REFERENCE.md) | REST and WebSocket |
| [Agents](docs/AGENTS.md) | Agent system details |
| [Detection](docs/DETECTION.md) | Vulnerability detectors |
| [Advanced](docs/ADVANCED.md) | RAG, tools, evolutionary |
| [OWASP Coverage](docs/OWASP_COVERAGE.md) | Compliance mapping |
| [Test Example](docs/TEST_EXAMPLE.md) | Test walkthrough |

---

## Responsible Use

This tool is for authorized security testing only.

Permitted: testing your own systems, security research with written
permission, contracted red team engagements, pre-deployment validation.

Prohibited: testing without authorization, attacking production systems
maliciously, extracting proprietary data.

Built-in safeguards include authorization verification, a blocklist for
public AI services, rate limiting, and audit logging.

---

## Project Status

| Aspect | Status |
|--------|--------|
| Development | Under active development |
| Tests | 1,517 passing |
| Skipped | 11 (optional deps) |
| Docker | Multi-stage build |

---

## References

- [OWASP Top 10 for LLM Applications (2025)](https://genai.owasp.org/llm-top-10/)
- [OWASP Top 10 for Agentic Applications (2026)](https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026/)
- Kumar et al. (2024). *AmpleGCG-Plus.* [arXiv:2410.22143](https://arxiv.org/abs/2410.22143)
- Zhang et al. (2025). *Verbalized Sampling.* [arXiv:2510.01171](https://arxiv.org/abs/2510.01171)
- *Hiding in the AI Traffic: Abusing MCP for LLM-Powered Agentic Red Teaming.* [arXiv:2511.15998](https://arxiv.org/abs/2511.15998)

---

## Acknowledgments

- [Elder Plinius / L1B3RT4S](https://github.com/elder-plinius) — jailbreak pattern research
- [Manus AI](https://manus.im) — context engineering principles
- [LangChain](https://github.com/langchain-ai/langgraph) — LangGraph framework
- [Anthropic](https://anthropic.com)
- [OWASP](https://owasp.org) — LLM Top 10 framework

---

## License

MIT — see [LICENSE](LICENSE).
