<div align="center">

Cracken 🦑

AI-Powered Penetration Testing Framework

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

# 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):

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.

# Interactive setup — configures provider, model, API keys
cracken login

Usage

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

# 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

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

cracken mcp_server --type stdio

SSE (network clients)

cracken mcp_server --type sse --host 0.0.0.0 --port 8080

Claude Desktop Configuration

{
  "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

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

pip install -e ".[dev]"
pytest                         # 625+ tests
pytest --cov=cracken           # coverage report
black cracken && ruff check cracken   # format & lint

See 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 for our disclosure policy.

License

MIT — Copyright (c) 2025 Masic, 2026 keyreyla.
See LICENSE.txt for full text.

---

This project is a fork of PentestAgent — the original AI penetration testing framework by Masic. Rebranded and enhanced by keyreyla.