<div align="center">

<img src="assets/Cracken.png" alt="Cracken Logo" width="200">

# Cracken
### AI Penetration Testing Framework

[![Python](https://img.shields.io/badge/Python-3.10%20|%203.11%20|%203.12-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.txt)
[![Version](https://img.shields.io/badge/Version-0.2.0--alpha-orange.svg)](https://github.com/keyreyla/cracken)
[![Tests](https://img.shields.io/badge/Tests-670%2B%20passed-brightgreen.svg)](https://github.com/keyreyla/cracken/actions)

**Cracken** — automated penetration testing powered by AI.
Multi-agent, multi-provider, with TUI, headless CLI, and MCP server modes.

</div>

---

## Quick Start

### Option A: uv (recommended)

```bash
# Install uv (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone & setup
git clone https://github.com/keyreyla/cracken.git
cd cracken
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e "."
playwright install chromium      # browser tool (optional)
cracken login                    # setup API keys
cracken                          # launch TUI
```

### Option B: pip (standard Python)

```bash
git clone https://github.com/keyreyla/cracken.git
cd cracken
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e "."
playwright install chromium
cracken login
cracken
```

## Python Version Support

| Python | Status |
|--------|--------|
| 3.10   | ✅ Supported |
| 3.11   | ✅ Supported |
| 3.12   | ✅ **Recommended** |
| 3.13   | ⚠️ Experimental |
| 3.14   | ❌ Not supported (Docker base image issue) |

## Install Options (Dependency Variants)

Cracken uses optional dependency extras so you only install what you need:

```bash
uv pip install -e "."              # Core only (lightest) — LLM, TUI, CLI, tools
uv pip install -e ".[rag]"         # + RAG engine (sentence-transformers, faiss-cpu)
uv pip install -e ".[dev]"         # + Dev tools (pytest, black, mypy, isort)
uv pip install -e ".[all]"         # Everything above
```

**Note on `[dev]`**: `ruff` may fail to install in containerized environments (filesystem overlay bug). Use `uv pip install black mypy isort pytest pytest-asyncio` as workaround.

## Features

| Feature | Details |
|---------|---------|
| **Multi-Agent Modes** | `/assist` (single-shot), `/agent` (autonomous), `/crew` (orchestrator + workers), `/interact` (guided) |
| **Live Model Switch** | `/model` command with interactive popup — ↑↓ Enter Esc, real-time from 9Router |
| **9Router Proxy** | Auto-detect relay, fetch models & providers, seamless auth via `cracken login` |
| **Auth Wizard** | 3 flows: 9Router relay, OpenAI-compatible relay, manual provider config (OpenAI, Anthropic, Gemini, DeepSeek, Groq, Tavily) |
| **Extensible Tools** | Drop a tool in `cracken/tools/<name>/__init__.py` — auto-discovered |
| **RAG Engine** | Optional FAISS + sentence-transformers for semantic knowledge retrieval |
| **Report Generator** | Auto-generate Markdown/HTML pentest reports with attack graphs |
| **MCP Server** | Expose as MCP server (STDIO/SSE) — `/mcp add stdio <name> <command>` |
| **MCP Client** | Connect to external MCP servers with auto-discovery (`/mcp add npx -y <package>`) |
| **Security First** | Scope validation, command injection guards, API key leak prevention, dedicated `tests/security/` |
| **Async Architecture** | Full async/await — concurrent tool execution, non-blocking agent loops |

## TUI Commands

| Command | Description |
|---------|-------------|
| `/assist <task>` | Single instruction + tool execution |
| `/agent <task>` | Autonomous agent loop |
| `/crew <task>` | Multi-agent orchestration |
| `/interact <task>` | Guided interactive chat |
| `/model` | Show/switch model interactive popup |
| `/target <host>` | Set assessment target |
| `/workspace <name>` | Create/activate workspace |
| `/notes` | View saved findings |
| `/report` | Generate pentest report |
| `/tools` | List available tools |
| `/mcp add <name> <command>` | Add MCP server (e.g. `npx -y package`) |
| `/mcp list` | Browse configured MCP servers |
| `/help` | Show help |
| `/clear` | Clear chat |

## MCP Server Setup

```bash
# In TUI — simple mode (auto-detect stdio):
/mcp add npx -y @modelcontextprotocol/server-filesystem /tmp

# Explicit mode:
/mcp add stdio my-server npx -y @modelcontextprotocol/server-filesystem
/mcp add sse my-server https://example.com/sse
```

Config saved to `~/.cracken/mcp_servers.json`. Timeout: 300s (plenty for `npx` first download).

## Configuration

Config stored in `~/.cracken/`:

| File | Purpose |
|------|---------|
| `~/.cracken/litellm.json` | Provider config (API keys, model, api_base) |
| `~/.cracken/9router.json` | 9Router relay config |
| `~/.cracken/mcp_servers.json` | MCP server definitions |

## Project Structure

```
cracken/
  agents/
    cracken_agent/  — Single autonomous agent
    crew/           — Multi-agent orchestrator
    prompts/        — Jinja2 prompt templates
  config/           — Settings, constants, 9Router, LiteLLM config
  interface/
    tui/            — TUI (Textual): app.py, screens.py, widgets.py, cracken.tcss
    cli.py          — Headless CLI mode
    login_cli.py    — Auth wizard
    reporter.py     — Report generator
  knowledge/        — FAISS RAG, embeddings
  llm/              — LiteLLM wrapper, memory
  mcp/              — MCP client manager, server transports
  runtime/          — Local and Docker execution
  tools/            — Built-in tools (browser, terminal, notes, web_search, finish)
  workspaces/       — Workspace isolation
tests/
  unit/             — Unit tests
  security/         — Security tests (API key leakage, injection)
  integration/      — Integration tests
assets/
  Cracken.png       — Project logo
```

## Development

```bash
source .venv/bin/activate
uv pip install -e ".[dev]"        # install dev deps
python3 -m pytest tests/ -v --tb=short   # 670+ tests
python3 -m pytest tests/unit/ tests/security/ -x -q   # fast
```

### Textual Dev Mode (live CSS reload)
```bash
textual run --dev cracken
```
Edit `cracken/interface/tui/cracken.tcss` — changes appear instantly without restart.

## Legal

Only use against systems you have **explicit written authorization** to test.
Unauthorized access is illegal.

## License

MIT — Copyright (c) 2026 keyreyla.
See [LICENSE.txt](LICENSE.txt) for full text.

*Fork of [PentestAgent](https://github.com/GH05TCREW/pentestagent) by Masic.*