Content
<div align="center">
# Cracken 🦑
### AI-Powered Penetration Testing Framework
[](https://www.python.org/)
[](LICENSE.txt)
[](https://github.com/keyreyla/cracken/releases)
[](https://github.com/keyreyla/cracken)
[](https://github.com/keyreyla/cracken)
[](https://github.com/keyreyla/cracken/pkgs/container/cracken)
[](https://github.com/keyreyla/cracken/actions)
[](https://github.com/psf/black)
[](https://github.com/keyreyla/cracken/blob/main/CONTRIBUTING.md)
**Cracken** — automated penetration testing powered by AI.
Built on LiteLLM, supporting any provider. Run locally, inside Docker, or as an MCP server for Claude Desktop, Cursor, n8n, and more.
</div>
---
## Features
| Feature | Details |
|---------|---------|
| **🤖 Multi-Agent Modes** | 4 modes: Assist (single-shot), Agent (autonomous loop), Crew (orchestrator + workers), Interact (guided chat) |
| **🔌 MCP Server** | Expose as MCP server (STDIO / SSE) — integrate with Claude Desktop, Cursor, n8n, custom clients |
| **🧠 Report Generator** | Auto-generate penetration test reports in Markdown or HTML from findings and session logs |
| **🐳 Docker Ready** | Pre-built Ubuntu and Kali Linux images — `docker compose run` and you're in |
| **🔐 Security First** | Scope validation, command injection guards, API key leak prevention built-in |
| **🧩 Extensible Tools** | Self-registering tool system — drop a new tool in `tools/<name>/` and it's available |
| **📚 Playbooks** | THP3 methodology playbooks for recon, network, and web application testing |
| **🔍 RAG Engine** | Optional FAISS + sentence-transformers for semantic knowledge retrieval from local docs |
| **⚡ Async Architecture** | Full async/await — concurrent tool execution, non-blocking agent loops |
---
## Quick Start
```bash
# Clone
git clone https://github.com/keyreyla/cracken.git
cd cracken
# Auto setup
./scripts/setup.sh # Linux/macOS
.\scripts\setup.ps1 # Windows
# Or manual
python -m venv venv
source venv/bin/activate
pip install -e ".[all]"
playwright install chromium
```
## Configuration
Create a `.env` file (or use `cracken login` for interactive setup):
```env
ANTHROPIC_API_KEY=sk-ant-...
CRACKEN_MODEL=claude-sonnet-4-20250514
# Optional
OPENAI_API_KEY=sk-... # OpenAI provider
GEMINI_API_KEY=... # Google Gemini
TAVILY_API_KEY=... # Web search tool
```
Config is loaded from `~/.cracken/env` (global) > `CWD/.env` (project) > package root `.env`.
```bash
# Interactive setup — configures provider, model, API keys
cracken login
```
## Usage
```bash
cracken # Launch TUI
cracken -t 192.168.1.1 # TUI with target pre-set
cracken tui --docker # Run inside Docker sandbox
cracken run -t target.com --playbook thp3_web # Headless mode
```
### TUI Commands
| Command | Description |
|---------|-------------|
| `/assist <task>` | Single instruction + tool execution, returns immediately |
| `/agent <task>` | Autonomous agent loop: think → tool → observe → repeat |
| `/crew <task>` | Multi-agent orchestration with specialist workers |
| `/interact <task>` | Guided interactive chat — you stay in control |
| `/report` | Generate narrative LLM report |
| `/report md` | Fast Markdown report |
| `/report html` | Fast HTML report with dark theme |
| `/notes` | View saved findings |
| `/target <host>` | Set assessment target |
| `/tools` | List available tools |
| `/spawn <target>` | Spawn a child MCP agent |
| `/workspace <name>` | Manage workspaces |
| `/mcp <cmd>` | Add, list, or manage MCP servers |
## Report Generator
Reports are generated from:
- **Notes** — findings saved during assessment (`loot/notes.json`)
- **Session logs** — all tool calls, outputs, and agent reasoning
- **Structured metadata** — targets, ports, CVEs, credentials, services
```bash
# In TUI
/report md → Markdown
/report html → HTML with dark theme
# Headless
cracken run -t target.com --task "full scan" --report auto
# → loot/reports/<target>_<timestamp>.md
# Via MCP (from any client)
generate_report fmt="html"
```
## Docker
```bash
# Ubuntu base image
docker compose run --rm cracken
# Kali Linux (Metasploit, SQLMap, Hydra, etc.)
docker compose --profile kali run --rm cracken-kali
```
Images: `ghcr.io/keyreyla/cracken:latest` / `:kali`
## MCP Server
Cracken can operate as an MCP server — integrate into any MCP-compatible client.
### STDIO (local clients)
```bash
cracken mcp_server --type stdio
```
### SSE (network clients)
```bash
cracken mcp_server --type sse --host 0.0.0.0 --port 8080
```
### Claude Desktop Configuration
```json
{
"mcpServers": {
"cracken": {
"command": "cracken",
"args": ["mcp_server", "--type", "stdio"]
}
}
}
```
### Exposed MCP Tools
| Category | Tools |
|----------|-------|
| **Status / Config** | `get_server_status`, `get_config`, `update_config` |
| **Task Execution** | `run_task` (sync), `run_task_async` (returns task ID) |
| **Task Inspection** | `list_tasks`, `get_task_status`, `get_task_result`, `await_tasks` |
| **Task Control** | `cancel_task` |
| **Tool Management** | `list_tools`, `enable_tool`, `disable_tool` |
| **Conversation** | `get_conversation_history`, `reset_conversation` |
| **Memory** | `store_memory`, `retrieve_memory`, `clear_memory` |
| **Observability** | `get_logs`, `get_metrics`, `generate_report` |
### Async Task Pattern
```
run_task_async task="Enumerate subdomains of example.com"
run_task_async task="Run nmap SYN scan on example.com"
await_tasks task_ids=["<id1>", "<id2>"] timeout_seconds=300
get_task_result task_id="<id1>"
```
## CLI Reference
```bash
cracken [COMMAND] [OPTIONS]
Commands:
tui Launch TUI (interactive mode)
run Headless mode with task or playbook
login Interactive provider setup
mcp Manage MCP server connections
mcp_server Expose Cracken as an MCP server (stdio/sse)
tools List, call, or inspect tools
workspace Workspace lifecycle commands
target Add or list targets
Global Flags:
-t, --target Assessment target (IP/hostname/URL)
-m, --model LLM model override
-d, --docker Use Docker sandbox for tool execution
-v, --version Show version
```
## Development
```bash
pip install -e ".[dev]"
pytest # 625+ tests
pytest --cov=cracken # coverage report
black cracken && ruff check cracken # format & lint
```
See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
## Project Structure
```
cracken/
agents/ — Agent implementations (single, crew, shadow graph)
crew/ — Multi-agent orchestrator, worker pool
pa_agent/ — Single autonomous agent
prompts/ — Jinja2 prompt templates
config/ — Settings, constants, 9Router client
interface/ — TUI (Textual), CLI (Typer), login, reporter
knowledge/ — FAISS RAG engine, indexer, shadow knowledge graph
llm/ — LiteLLM wrapper, conversation memory
mcp/ — MCP client manager, server transports
playbooks/ — THP3 methodology playbooks
runtime/ — Local and Docker tool execution
tools/ — Built-in tools registry
workspaces/ — Workspace isolation and lifecycle
loot/ — Persisted findings (git-ignored)
mcp_examples/ — Example MCP configurations
tests/ — Pytest suite (625+ tests)
```
## Architecture Overview
```
┌─────────────────────────────────────────────────────┐
│ User Interface │
│ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │
│ │ TUI │ │ CLI │ │ MCP Client (3rd) │ │
│ │ (Textual)│ │ (Typer) │ │ Claude/Cursor/n8n │ │
│ └────┬─────┘ └────┬─────┘ └────────┬──────────┘ │
│ └─────────────┼─────────────────┘ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Agent Core │ │
│ │ (Base/PaAgent│ │
│ │ /Crew) │ │
│ └──────┬───────┘ │
│ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │
│ │ LLM │ │ Runtime │ │ Tool Registry │ │
│ │(LiteLLM) │ │(Local/ │ │ (Self-registering)│ │
│ │ │ │ Docker) │ │ │ │
│ └──────────┘ └──────────┘ └───────────────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │
│ │ RAG │ │ MCP │ │ Workspace/Notes │ │
│ │ (FAISS) │ │ Server │ │ Persistence │ │
│ └──────────┘ └──────────┘ └───────────────────┘ │
└─────────────────────────────────────────────────────┘
```
## FAQ
**Q: Does Cracken require a GPU?**
A: No. The RAG engine (optional) benefits from a GPU for embedding generation, but the core agent works on CPU.
**Q: Can I use Cracken with Ollama/local models?**
A: Yes — LiteLLM supports Ollama. Set `OLLAMA_BASE_URL` in `.env` and use model prefix `ollama/`.
**Q: How is this different from other AI pentest tools?**
A: Cracken combines multi-agent orchestration, MCP server capability, and full autonomy in a single package — it works both as a standalone TUI and as a drop-in agent for any MCP client.
**Q: Can I use Cracken headless/CI?**
A: Yes — `cracken run` accepts a task and produces reports. Use `--report auto` to save results without a TTY.
## Legal
Only use against systems you have **explicit written authorization** to test.
Unauthorized access is illegal. See [SECURITY.md](SECURITY.md) for our disclosure policy.
## License
MIT — Copyright (c) 2025 Masic, 2026 keyreyla.
See [LICENSE.txt](LICENSE.txt) for full text.
---
*This project is a fork of [PentestAgent](https://github.com/GH05TCREW/pentestagent) — the original AI penetration testing framework by Masic. Rebranded and enhanced by [keyreyla](https://github.com/keyreyla).*
