roycrew 1.0.0

AI-Powered Penetration Testing Assistant

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

Tool	Category	Description
Nmap	Scanning	Network port scanning and service detection
Masscan	Scanning	High-speed port scanning
Nuclei	Vuln Scan	Template-based vulnerability scanning
SQLMap	Exploitation	SQL injection testing
Hydra	Exploitation	Network brute forcing
Metasploit	Exploitation	Exploitation framework
FFUF	Discovery	Web fuzzing and directory brute-force
HTTPx	Discovery	HTTP probing and tech detection
Katana	Discovery	Web crawling
Amass	Recon	Subdomain enumeration
Assetfinder	Recon	Subdomain discovery
Arjun	Discovery	HTTP parameter discovery
AlterX	Recon	Subdomain wordlist generation
ShuffleDNS	Recon	DNS brute forcing
SSL Scanner	Analysis	SSL/TLS analysis
Scout Suite	Cloud	Cloud security auditing
Wayback URLs	Recon	Historical URL retrieval
Cert Transparency	Recon	Certificate log search

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