Metadata-Version: 2.4
Name: roycrew
Version: 1.0.1
Summary: AI-Powered Penetration Testing Assistant
Project-URL: Homepage, https://github.com/roycrew/roycrew
Project-URL: Bug Tracker, https://github.com/roycrew/roycrew/issues
Author: ROYCREW
License: MIT License
        
        Copyright (c) 2026 ROYCREW
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Keywords: ai,mcp,ollama,penetration-testing,security
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: colorama>=0.4.6
Requires-Dist: fastapi>=0.115.9
Requires-Dist: langchain-community>=0.3.24
Requires-Dist: langchain>=0.3.25
Requires-Dist: mcp>=1.6.0
Requires-Dist: numpy>=2.2.5
Requires-Dist: ollama>=0.4.8
Requires-Dist: openai-agents>=0.0.14
Requires-Dist: openai>=1.78.1
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: reportlab>=4.4.0
Requires-Dist: requests>=2.31.0
Requires-Dist: uvicorn>=0.34.0
Provides-Extra: metasploit
Requires-Dist: pymetasploit3>=1.0.6; extra == 'metasploit'
Description-Content-Type: text/markdown

# 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

```bash
cd roycrew
pip install -r requirements.txt
```

### 2. Configure API Key

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

### 3. Run

```bash
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
