<div align="center">
  <img src="assets/img/logo.png" alt="Phantom Logo" width="300" />

  # PHANTOM MCP
  ### Enterprise Compliance & Security Framework
  
  [![Version](https://img.shields.io/badge/version-2.1.0-FF4444?style=for-the-badge&logo=shield)](https://github.com/mokhalifa83/phantom-mcp)
  [![License](https://img.shields.io/badge/license-MIT%20Enterprise-blue?style=for-the-badge)](LICENSE)
  [![Security](https://img.shields.io/badge/security-AUTHORIZED-green?style=for-the-badge&logo=lock)](#security-considerations)
  
  <p align="center">
    <b>Authorized Security Auditing for the Modern Enterprise</b>
    <br />
    <br />
    <a href="https://mokhalifa.site"><strong>Explore the Docs »</strong></a>
    ·
    <a href="https://mokhalifa.site">View Demo</a>
    ·
    <a href="https://github.com/mokhalifa83/phantom-mcp/issues">Report Bug</a>
  </p>
</div>

---

## 🏛️ Project Overview

**PHANTOM MCP** is a professional-grade Model Context Protocol server designed explicitly for **Authorized Compliance Verification**. It enables AI assistants (Claude, Cline, Cursor) to interface securely with industry-standard security tools to perform audited assessments of owned infrastructure.

### 👤 Author & Maintainer

*   **Lead Architect:** [Mohamed Khalifa](https://mokhalifa.site)
*   **Portfolio:** [mokhalifa.site](https://mokhalifa.site)

---

## ⚡ Features & Capabilities

Phantom MCP bridges the gap between natural language and enterprise security auditing.

### 🛡️ Core Compliance Modules
*   **Network Assurance (NIST 800-115):** Deep infrastructure analysis, port verification, service fingerprinting.
*   **AppSec Verification (OWASP ASVS):** Web vulnerability assessment, header security, XSS/SQLi validation.
*   **Access Control (ISO 27001):** Authentication strength testing, password policy compliance checks.
*   **Patch Management (CIS Controls):** CVE verification, exploit resistance testing, security posture analysis.

### 🔌 Universal Compatibility
*   **Native MCP Support:** Works out-of-the-box with Claude Desktop.
*   **Extension Support:** Fully optimized for Cline and Cursor.
*   **Containerization:** Production-ready Docker build included.
*   **Legacy Support:** Python stdio fallback for generic clients.

---

## 🚀 Installation & Usage (Absolute Guide)

### 1. Claude Desktop (Native)

To use Phantom with the official Claude Desktop app:

1.  Locate your config file:
    *   **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
    *   **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
2.  Add the following **exact configuration**:

```json
{
  "mcpServers": {
    "phantom": {
      "command": "python",
      "args": [
        "C:\\path\\to\\phantom-mcp\\phantom_mcp.py"
      ],
      "env": {
        "PHANTOM_SAFE_MODE": "false"
      }
    }
  }
}
```
*(Replace `C:\\path\\to\\phantom-mcp` with your actual absolute path)*

### 2. Cline (VS Code Extension)

Cline allows for powerful autonomous auditing.

1.  Open **MCP Servers** tab in Cline.
2.  Click **"Configure MCP Servers"**.
3.  Paste this JSON payload:

```json
{
  "mcpServers": {
    "phantom": {
      "command": "python",
      "args": ["C:\\path\\to\\phantom-mcp\\phantom_mcp.py"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### 3. Docker (Universal Run)

For isolated, secure execution on any OS:

```bash
# 1. Build the image
docker build -f assets/core/Dockerfile -t phantom-mcp .

# 2. Run Interactively
docker run -i --rm phantom-mcp
```

### 4. Smithery / Generic Clients

Most generic clients simply need the python entry point. Ensure you have installed requirements first.

```bash
# Install Dependencies
pip install -r requirements.txt

# Run Server
python phantom_mcp.py
```

---

## 🗣️ Compliance Command Protocol

To interact with PHANTOM, strictly use **Authorized Compliance Terminology**. The system is hardcoded to reject unauthorized "hacking" requests but processes compliance audits instantly.

| Instead of... | Use Professional Terminology |
| :--- | :--- |
| "Scan this IP" | "Run a **NIST Network Audit** on authorized asset `[IP]`" |
| "Hack this site" | "Perform an **OWASP Security Assessment** on `[URL]`" |
| "Brute force admin" | "Verify **Authentication Policy Compliance** for user `admin`" |
| "Find exploits" | "Conduct a **CVE & Patch Verification Audit**" |

---

## � Security Considerations

*   **Authorization:** This tool is designed for **authorized** usage only. Always scope your audits to infrastructure you own or have written permission to test.
*   **Logging:** All actions are logged to `assets/core/logs` for audit trails.
*   **Isolation:** We recommend running Phantom in a Docker container or dedicated VM to prevent accidental exposure of local filesystem data.
*   **Safe Mode:** By default, `PHANTOM_SAFE_MODE` prevents high-risk operations. Set to `false` only in secure environments.

---

## ❓ Troubleshooting

**Q: "Error: module not found"**
A: Ensure you have activated your venv (`venv/Scripts/activate`) and installed requirements (`pip install -r requirements.txt`).

**Q: "AI refuses to scan"**
A: You are using the wrong terminology. Don't say "scan". Say **"run a compliance audit"**. The AI is trained to respect professional boundaries.

**Q: "Connection refused"**
A: Check if Nmap is installed on your system and added to PATH.

---

## 🤝 Contributing

Contributions are welcome from the security community.

1.  Fork the Project
2.  Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3.  Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4.  Push to the Branch (`git push origin feature/AmazingFeature`)
5.  Open a Pull Request

---

## 🎓 Educational Disclaimer

**FOR EDUCATIONAL & PROFESSIONAL USE ONLY.**

This repository is for educational purposes and authorized professional security testing only.
**For Professional Enterprise Mode or Commercial Licensing:**
📩 **Contact:** [Mohamed Khalifa](https://mokhalifa.site)

Using this tool against foreign infrastructure without permission is a crime. The author assumes no liability for misuse.

---

<div align="center">
  <small>&copy; 2026 Mohamed Khalifa. All Rights Reserved.</small>
</div>