penbot 2.2.0__tar.gz → 2.4.0__tar.gz

penbot-2.4.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: penbot
+Version: 2.4.0
+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,542 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).

penbot-2.4.0/README.md

@@ -0,0 +1,195 @@
+<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,542 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).