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

Autonomous AI Cybersecurity Platform & Offensive Intelligence Core

---

📖 Introduction

ChainRaptor is an advanced, open-source, AI-powered offensive security framework. Designed for penetration testers, red teamers, and security researchers, it acts as an intelligent orchestration layer bridging the gap between Large Language Models (LLMs) and real-world cybersecurity tools.

Instead of manually running commands, you can chat with ChainRaptor using natural language. The AI will autonomously decide which tools to use, execute them on your host system (after asking for permission), analyze the output, and proceed with the next steps of the engagement.

✨ Features

• 💬 Native Terminal Chat UI: A beautiful, fully interactive terminal interface built with Rich.
• 🧠 Multi-Provider AI Support: Seamlessly switch between Google Gemini, Anthropic Claude, OpenAI, OpenRouter, and fully offline local models via Ollama.
• 🛠️ Automated Tool Execution: The AI can execute tools like Nmap, Gobuster, Nuclei, and more directly on your system.
• 📦 Auto-Dependency Resolution: If a tool is missing, the AI will formulate the exact installation command (e.g., winget install nmap) and prompt you to run it.
• 🔌 MCP Compatibility: Acts as a Model Context Protocol (MCP) server, allowing you to plug ChainRaptor directly into AI IDEs like Cursor, Cline, or Claude Desktop.
• 🩸 "Blood-Red" Aesthetic: A cyberpunk, red-and-black immersive hacker visual interface.

---

🚀 Installation Guide

ChainRaptor is built in Python and runs seamlessly across all major operating systems.

🪟 Windows Installation

1. Install Python 3.9+.
2. Clone the repository and navigate into the folder:

   git clone https://github.com/yourusername/chainraptor.git
   cd chainraptor

3. Install the dependencies:

   pip install -r requirements.txt

   (We highly recommend installing Ollama if you wish to run models locally).

🐧 Linux Installation

1. Ensure Python and Pip are installed:

   sudo apt update
   sudo apt install python3 python3-pip git

2. Clone the repository and navigate into the folder:

   git clone https://github.com/yourusername/chainraptor.git
   cd chainraptor

3. Install the dependencies:

   pip3 install -r requirements.txt

   (To install Ollama for local models: curl -fsSL https://ollama.com/install.sh | sh)

🍎 macOS Installation

1. Install Python using Homebrew:

   brew install python git

2. Clone and navigate into the folder:

   git clone https://github.com/yourusername/chainraptor.git
   cd chainraptor

3. Install the dependencies:

   pip3 install -r requirements.txt

   (To install Ollama for local models, download it from ollama.com or run brew install --cask ollama).

---

💻 How to Run ChainRaptor

ChainRaptor utilizes a Client-Server architecture. You must run the background server, and then connect to it using the Terminal Chat Client (or an MCP IDE).

1. Start the API Server (Background) Open a terminal and start the server. This handles the actual execution of tools.

python chainraptor.py

2. Start the Interactive AI Chat (Foreground) Open a second terminal and launch the chat interface:

python chainraptor_chat.py

• You will be asked to select your AI Provider (Anthropic, Google, OpenAI, OpenRouter, or Local Ollama).
• You can change your model at any time by typing /model <model-name> in the chat.
• Type /models to see a list of all available models for your selected provider.

---

🤖 LLM Model Recommendations

For the AI to accurately parse logs, decide on penetration testing methodologies, and not hallucinate outputs, selecting the right model is critical.

Cloud API Models (Recommended)

If you are using API keys, these models are battle-tested for ChainRaptor:

• Google Gemini: gemini-2.5-flash (Extremely fast and generous free tier)
• Anthropic: claude-3-7-sonnet-20250219 (The absolute best for logical reasoning and coding)
• OpenAI: gpt-4o (Highly reliable tool execution)

Local / Offline Models (Ollama)

If you want to run the AI 100% locally with zero API keys and complete privacy, use Ollama. Below is a guide on which model to download based on your system specifications.

🟢 Low-End Systems (4GB - 6GB RAM)

If you have an older laptop or limited RAM, use a 3B parameter model. They are extremely fast but may struggle with very complex logic.

• Model: phi3 or llama3.2:3b
• Command: ollama run phi3

🟡 Mid-Range Systems "The Sweet Spot" (8GB - 16GB RAM/VRAM)

This is the recommended tier. 7B - 8B parameter models are smart enough to perfectly orchestrate cybersecurity tools while running quickly on standard gaming laptops or modern PCs.

• Models: llama3:8b, qwen2.5:7b, or mistral:7b
• Command: ollama run llama3

🔴 High-End Workstations (32GB+ RAM/VRAM)

If you have an RTX 3090/4090 or a Mac Studio, you can run massive, enterprise-grade open-weights models that rival GPT-4 in intelligence.

• Models: llama3:70b or qwen2.5:72b
• Command: ollama run llama3:70b

---

⚠️ Disclaimer

ChainRaptor is built for educational purposes and authorized security auditing only. The developers are not responsible for any misuse of this tool. Always ensure you have explicit, written permission from the target network owners before executing any scans or exploits.