ROYCREW

AI-Powered Penetration Testing Assistant

ROYCREW is an autonomous penetration testing agent that combines OpenAI GPT-4o with the Model Context Protocol (MCP) and a RAG knowledge base. It helps security professionals conduct authorized penetration tests through natural language commands.

Features

• Interactive Chat Mode — Free-form conversation with the AI agent for guided pentesting
• Automated Workflows — Pre-built pentest workflows (Recon, Web App, Network, Full Pentest)
• Autonomous Agent Mode — Goal-driven autonomous operation using Pentesting Task Trees (PTT)
• 18 Security Tools via MCP — Nmap, Nuclei, SQLMap, Hydra, Metasploit, FFUF, Masscan, HTTPx, Katana, Amass, Arjun, Assetfinder, AlterX, ShuffleDNS, SSL Scanner, and more
• RAG Knowledge Base — Embedding-based retrieval for pentesting knowledge
• Streaming Output — Real-time display of LLM responses and tool results
• Automated Reporting — Markdown reports with findings, severity ratings, and remediation

Quick Start

1. Install Dependencies

cd roycrew
pip install -r requirements.txt

2. Configure API Key

cp .env.example .env
# Edit .env and add your OpenAI API key

3. Run

python main.py

4. Configure Tools (Optional)

From the main menu, select Option 4 to configure MCP tool servers. ROYCREW will auto-detect installed security tools on your system.

Project Structure

roycrew/
├── main.py                    # Entry point
├── config/
│   ├── app_config.py          # Singleton config (API keys, client)
│   └── constants.py           # Branding, prompts, limits
├── core/
│   ├── pentest_agent.py       # Main orchestrator
│   ├── agent_runner.py        # LLM query execution with streaming
│   ├── agent_mode_controller.py  # Autonomous agent loop
│   ├── model_manager.py       # Token counting (tiktoken)
│   ├── ptt_reasoning.py       # Task tree prompt engineering
│   └── task_tree_manager.py   # Hierarchical task tree
├── knowledge/
│   └── wordlist.txt           # Default knowledge base
├── rag/
│   ├── embedding.py           # Embedding test script
│   └── knowledge_base.py      # RAG with cosine similarity
├── reporting/
│   └── generators.py          # Markdown report generators
├── tools/
│   ├── mcp_manager.py         # MCP server connections
│   └── configure_mcp.py       # Interactive tool configuration
├── ui/
│   ├── conversation_manager.py # Token-aware chat history
│   └── menu_system.py         # Terminal UI
└── workflows/
    ├── workflow_definitions.py # 4 predefined workflows
    └── workflow_engine.py      # Sequential step execution

Supported Tools

Operating Modes

Interactive Mode

Chat directly with the AI agent. Use natural language to describe what you want to test.

Automated Workflows

Choose from 4 pre-built workflows:

1. Reconnaissance — Target information gathering
2. Web Application — OWASP-focused web app testing
3. Network Infrastructure — Network-level assessment
4. Full Pentest — All phases combined

Agent Mode (Autonomous)

Provide a goal and target. The agent autonomously:

• Generates a Pentesting Task Tree (PTT)
• Selects and executes tasks by priority
• Analyzes results and generates follow-up tasks
• Produces a final report

Requirements

• Python 3.10+
• OpenAI API key
• Node.js + npm (for MCP tool servers)
• Security tools installed on your system

Disclaimer

ROYCREW is designed for authorized security testing only. Always ensure you have proper written authorization before conducting penetration tests. The authors are not responsible for any misuse of this tool.

License

MIT License