# Cyber Master MCP Server v1.0

## AI-Powered Cybersecurity Automation Platform

**155 Security Tools** | **AI-Powered** | **MCP Compatible**

---

## Table of Contents

1. [What is This?](#what-is-this)
2. [Features](#features)
3. [System Requirements](#system-requirements)
4. [Installation](#installation)
5. [Setup Guide](#setup-guide)
6. [How to Use](#how-to-use)
7. [Available Tools](#available-tools)
8. [Configuration](#configuration)
9. [Troubleshooting](#troubleshooting)
10. [FAQ](#faq)

---

## What is This?

Cyber Master MCP Server is a complete cybersecurity toolkit that works with AI assistants like Claude, ChatGPT, or VS Code Copilot. It provides 155+ security tools that you can control through natural language.

**Example:**
- You: "Scan example.com for open ports"
- AI: Uses nmap_scan tool to scan the target
- You: "Check for SQL injection vulnerabilities"
- AI: Uses sqlmap_scan tool to test the target

---

## Features

- **155 Security Tools** - Network, web, cloud, binary analysis
- **AI Integration** - Works with Claude Desktop, VS Code Copilot, Cursor
- **Website Cloner** - Clone websites with anti-detection
- **Bug Bounty Workflows** - Automated recon and testing
- **Real-time Monitoring** - Live process dashboard
- **Smart Caching** - Faster repeated scans
- **Error Recovery** - Automatic retry and fallback

---

## System Requirements

### Minimum Requirements
- **OS:** Linux (Ubuntu 20.04+), macOS 12+, or Windows 10+
- **RAM:** 8GB minimum (16GB recommended)
- **Storage:** 10GB free space
- **Python:** 3.8 or higher
- **Internet:** Required for tool downloads and scanning

### Recommended
- **Kali Linux** - All tools pre-installed
- **RAM:** 32GB for full scanning
- **CPU:** 4+ cores for parallel scanning

---

## Installation

### Step 1: Clone the Repository

```bash
# Open terminal and navigate to desired location
cd ~/Desktop

# Clone the repository
https://github.com/CyberMaster000/Cyber-Master-MCP.git
# Enter the directory
cd cyber-master
```

### Step 2: Create Virtual Environment

```bash
# Create virtual environment
python3 -m venv cyber-env

# Activate it (Linux/Mac)
source cyber-env/bin/activate

# Activate it (Windows)
# cyber-env\Scripts\activate
```

### Step 3: Install Dependencies

```bash
# Install Python packages
pip install -r requirements.txt
```

### Step 4: Install Security Tools

```bash
# On Kali Linux (most tools pre-installed)
sudo apt update && sudo apt install -y \
  nmap masscan rustscan amass subfinder nuclei nikto \
  gobuster feroxbuster ffuf dirb dirsearch httpx katana \
  sqlmap wpscan hydra john hashcat ghidra radare2 gdb \
  binwalk volatility3 prowler trivy

# On Ubuntu/Debian
sudo apt update && sudo apt install -y nmap nikto sqlmap hydra
```

### Step 5: Verify Installation

```bash
# Check if tools are installed
which nmap
which nuclei
which gobuster

# Should return paths like /usr/bin/nmap
```

---

## Setup Guide

### Step 1: Start the Server

```bash
# Make sure virtual environment is activated
source cyber-env/bin/activate

# Start the MCP server
python3 cyber_master_server.py

# You should see:
# ✅ CyberMaster AI MCP Server Started
# 📊 Port: 8888
```

### Step 2: Test Server Health

```bash
# Open new terminal and test
curl http://localhost:8888/health

# Should return JSON with server status
```

### Step 3: Configure AI Client

#### For Claude Desktop:

1. Open Claude Desktop
2. Go to Settings > MCP Servers
3. Add new server with this config:

```json
{
  "mcpServers": {
    "cyber-master": {
      "command": "python3",
      "args": [
        "/full/path/to/cyber-master/cyber_master_mcp.py",
        "--server",
        "http://localhost:8888"
      ],
      "timeout": 300
    }
  }
}
```

#### For VS Code Copilot:

1. Open VS Code
2. Go to Settings (Ctrl+,)
3. Search for "MCP"
4. Add server configuration:

```json
{
  "servers": {
    "cyber-master": {
      "type": "stdio",
      "command": "python3",
      "args": [
        "/full/path/to/cyber-master/cyber_master_mcp.py",
        "--server",
        "http://localhost:8888"
      ]
    }
  }
}
```

### Step 4: Restart AI Client

Close and reopen your AI client (Claude Desktop or VS Code).

### Step 5: Verify Connection

Ask your AI assistant:
```
"Can you check the health of the Cyber Master server?"
```

If connected, it will use the server_health tool.

---

## How to Use

### Basic Usage

1. **Start the server:**
   ```bash
   cd cyber-master
   source cyber-env/bin/activate
   python3 cyber_master_server.py
   ```

2. **Open your AI assistant** (Claude Desktop, VS Code Copilot, etc.)

3. **Start asking questions:**

### Example Commands

#### Network Scanning
```
"Scan 192.168.1.1 for open ports using nmap"
"Run a comprehensive scan on example.com"
"Do a quick port scan on 10.0.0.1"
```

#### Web Application Testing
```
"Check example.com for SQL injection vulnerabilities"
"Scan for XSS vulnerabilities on target.com"
"Find hidden directories on website.com"
"Test for command injection on api.target.com"
```

#### Vulnerability Assessment
```
"Run a vulnerability scan on target.com using nuclei"
"Check for common misconfigurations on server.com"
"Scan for known CVEs in the target system"
```

#### Website Cloning
```
"Clone the website example.com with all assets"
"Create a phishing simulation of login.example.com"
"Clone target.com with depth 2 and download assets"
```

#### Bug Bounty Workflow
```
"Start a bug bounty recon workflow for target.com"
"Find all subdomains of example.com"
"Enumerate parameters on api.target.com"
```

#### Binary Analysis
```
"Analyze this binary file for vulnerabilities"
"Check if this ELF binary has security protections"
"Find ROP gadgets in this binary"
```

#### Cloud Security
```
"Audit my AWS account for security issues"
"Scan my Kubernetes cluster for vulnerabilities"
"Check my Docker images for CVEs"
```

---

## Available Tools

### Network Tools (25+)
- `nmap_scan()` - Port scanning
- `rustscan_fast_scan()` - Ultra-fast port scanning
- `masscan_high_speed()` - High-speed port scanning
- `autorecon_comprehensive()` - Full reconnaissance
- `amass_scan()` - Subdomain enumeration

### Web Tools (40+)
- `nuclei_scan()` - Vulnerability scanning
- `nikto_scan()` - Web server scanning
- `sqlmap_scan()` - SQL injection testing
- `gobuster_scan()` - Directory enumeration
- `ffuf_scan()` - Web fuzzing
- `wpscan_analyze()` - WordPress scanning

### Binary Tools (25+)
- `ghidra_analysis()` - Reverse engineering
- `radare2_analyze()` - Binary analysis
- `gdb_peda_debug()` - Debugging
- `checksec_analyze()` - Security checks

### Cloud Tools (20+)
- `prowler_scan()` - AWS security
- `trivy_scan()` - Container scanning
- `kube_hunter_scan()` - Kubernetes testing

### Bug Bounty Tools (20+)
- `bugbounty_reconnaissance_workflow()` - Full recon
- `bugbounty_vulnerability_hunting()` - Vuln hunting
- `bugbounty_osint_gathering()` - OSINT collection

---

## Configuration

### Server Configuration

Edit `cyber-master-mcp.json`:

```json
{
  "mcpServers": {
    "cyber-master": {
      "command": "python3",
      "args": [
        "/path/to/cyber_master_mcp.py",
        "--server",
        "http://localhost:8888"
      ],
      "timeout": 300
    }
  }
}
```

### Server Options

```bash
# Start on different port
python3 cyber_master_server.py --port 9000

# Start with debug mode
python3 cyber_master_server.py --debug

# Start with both
python3 cyber_master_server.py --port 9000 --debug
```

### Environment Variables

```bash
# Set custom port
export CYBERMASTER_PORT=9000

# Set custom host
export CYBERMASTER_HOST=0.0.0.0

# Set log level
export CYBERMASTER_LOG=DEBUG
```

---

## Troubleshooting

### Problem: Server Won't Start

**Solution:**
```bash
# Check Python version
python3 --version

# Should be 3.8 or higher

# Check if port is in use
netstat -tlnp | grep 8888

# Kill existing process if needed
kill -9 <PID>
```

### Problem: Tools Not Found

**Solution:**
```bash
# Check if tool is installed
which nmap

# Install missing tools
sudo apt install nmap

# Check PATH
echo $PATH
```

### Problem: AI Client Can't Connect

**Solution:**
1. Verify server is running:
   ```bash
   curl http://localhost:8888/health
   ```

2. Check MCP configuration path is correct

3. Restart AI client

4. Check server logs for errors

### Problem: Permission Denied

**Solution:**
```bash
# Make scripts executable
chmod +x cyber_master_server.py
chmod +x cyber_master_mcp.py

# Check file permissions
ls -la
```

### Problem: Slow Performance

**Solution:**
```bash
# Use faster scanning profile
python3 cyber_master_server.py --debug

# Check system resources
htop

# Reduce concurrent scans
# Edit server config to limit threads
```

---

## FAQ

### Q: Can I use this on Windows?
**A:** Yes, but Kali Linux is recommended for full functionality. On Windows, use WSL2.

### Q: Do I need to install all 155 tools?
**A:** No. Start with core tools (nmap, nuclei, gobuster). Install others as needed.

### Q: Is this legal?
**A:** Only use on systems you own or have written permission to test. Unauthorized testing is illegal.

### Q: Can I run this without AI?
**A:** Yes. You can use the Python API directly. See the code examples in the source.

### Q: How do I update?
**A:** 
```bash
cd cyber-master
git pull
pip install -r requirements.txt
```

### Q: Can I contribute?
**A:** Yes! Fork the repository and submit a pull request.

---

## Safety Notice

⚠️ **IMPORTANT:**
- Only use on systems you own or have authorization to test
- Unauthorized scanning is illegal and unethical
- Always get written permission before testing
- Use in isolated lab environments for learning
- Follow responsible disclosure for any vulnerabilities found

---

## Support

- **Author:** Nikhil Gupta
- **Email:** nikhilguptaji8@gmail.com
---

## License

This project is for educational and authorized security testing purposes only.

---

**Made with ❤️ by Nikhil Gupta for AI-powered security automation**