MCP Killchain

🔴 mcp-killchain

Black-Box Attack-Path Analyzer for MCP Servers


mcp-killchain is a security research tool that answers one critical question:

*"Can this MCP server enable an AI agent to autonomously steal data without human interaction?"*

🎯 Overview

mcp-killchain performs black-box analysis of Model Context Protocol (MCP) servers to identify potential attack paths. It predicts exploits without executing tools, making it safe for production environments.

Core Purpose

The tool detects Parasitic Toolchain Attacks - scenarios where:

• External attacker-controlled data is ingested (EIT)
• Private/sensitive data is accessed (PAT)
• Data is exfiltrated externally (NAT)
• All without human approval

✨ Features

🔍 Multi-Factor Detection

• Kill Chain Detection: Identifies EIT → PAT → NAT attack sequences
• Schema Poisoning Analysis: Detects hidden instructions in tool definitions
• Implicit Poisoning Detection (MCP-ITP): Identifies subtle coercion patterns
• Behavioral Analysis: Compares tool descriptions vs. actual capabilities
• YARA Pattern Matching: Detects known malicious patterns
• External Resource Validation: Identifies SSRF and parasitic attack risks
• Privilege Analysis: Detects least privilege violations
• Manifest Integrity: Verifies tool definition integrity and version pinning
• Autonomy & Stealth Assessment: Evaluates autonomous execution potential

🚀 Scan Modes

• Standard Mode: Fast analysis using schema and pattern matching (no LLM required)
• Enhanced Mode: Deep semantic analysis with LLM-based classification (requires API key)

📊 Risk Scoring

Computes MCP Security Score (MCP-SS) on a 0-10 scale based on:

• Kill chain existence and severity
• Tool privilege levels
• Chain complexity
• Autonomy indicators
• YARA signals
• Poisoning confidence
• Behavioral mismatches
• External resource risks
• Privilege violations
• Manifest integrity

📦 Installation

Prerequisites

• Python 3.10 or higher (Python 3.8+ supported, but 3.10+ recommended)
• pip (Python package manager)
• Git (for cloning the repository)

Step-by-Step Installation

1. Clone the Repository

git clone https://github.com/UudhhayK/mcp-killchain.git
cd mcp-killchain

2. Create a Virtual Environment (Recommended)

On Linux/Mac/WSL:

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

On Windows (PowerShell):

# Create virtual environment
python -m venv venv

# Activate virtual environment
.\venv\Scripts\Activate.ps1

On Windows (Command Prompt):

# Create virtual environment
python -m venv venv

# Activate virtual environment
venv\Scripts\activate.bat

3. Install the Package

# Install in editable mode
pip install -e .

# Or install with optional dependencies
pip install -e ".[all]"

4. Verify Installation

# Check if the command is available
mcp-killchain --help

Optional Dependencies

The tool works without these, but they enhance functionality:

• YARA: For advanced pattern matching

  # Linux/Mac: Install system dependencies first
  sudo apt-get install yara libyara-dev  # Debian/Ubuntu
  brew install yara  # macOS
  
  # Then install Python package
  pip install yara-python

• LLM Support: For enhanced scan mode

  pip install openai anthropic

• Test Server: For local testing

  pip install fastapi uvicorn

🎬 Demo

mcp-killchain Demo

*Watch the tool in action: scanning MCP servers, detecting kill chains, and generating security reports.*

🚀 Quick Start

Basic Usage

# Scan an MCP server endpoint
mcp-killchain scan --endpoint http://localhost:3333

# Standard mode (no LLM required)
mcp-killchain scan --endpoint http://localhost:3333 --scan-mode standard

# Enhanced mode (requires LLM key)
mcp-killchain scan --endpoint http://localhost:3333 --scan-mode enhanced --llm-key sk-...

With Authentication

# Add custom headers for authentication
mcp-killchain scan --endpoint https://mcp.example.com \
  --header "Authorization: Bearer token123" \
  --header "X-API-Key: key456"

Output Formats

# Detailed output (default)
mcp-killchain scan --endpoint http://localhost:3333 --detailed

# Quiet mode (minimal output)
mcp-killchain scan --endpoint http://localhost:3333 --quiet

📖 Usage Examples

Example 1: Standard Scan

mcp-killchain scan --endpoint http://localhost:3333 --scan-mode standard

Output:

╔═══════════════════════════════════════════════════════════════╗
║                                                               ║
║     ███╗   ███╗ ██████╗     ██╗  ██╗██╗██╗     ██╗            ║
║     ████╗ ████║██╔═══██╗    ██║ ██╔╝██║██║     ██║            ║
║     ██╔████╔██║██║   ██║    █████╔╝ ██║██║     ██║            ║
║     ██║╚██╔╝██║██║   ██║    ██╔═██╗ ██║██║     ██║            ║
║     ██║ ╚═╝ ██║╚██████╔╝    ██║  ██╗██║███████╗██║            ║
║     ╚═╝     ╚═╝ ╚═════╝     ╚═╝  ╚═╝╚═╝╚══════╝╚═╝            ║
║                                                               ║
║     🔍 Black-Box Attack-Path Analyzer for MCP Servers      ║
║     🛡️  Security Research Tool by Uudhhay                    ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Target: http://localhost:3333
Scan Mode: STANDARD
────────────────────────────────────────────────────────────────

[CRITICAL] MCP Kill Chain(s) Detected
----------------------------------------------------------------------

Chain #1: fetch_url → read_logs → send_email
  Autonomous: YES
  Requires Approval: NO
  Stealth: LOW
  ⚠️  WARNING: This chain can execute autonomously!

Chain #2: web_search → read_logs → webhook_post
  Autonomous: YES
  Requires Approval: NO
  Stealth: LOW
  ⚠️  WARNING: This chain can execute autonomously!

----------------------------------------------------------------------
Scoring Factors:
  kill_chains: 3.50
  privileges: 2.00
  complexity: 0.40
  autonomy: 2.00
  yara_signals: 0.50
  poisoning: 0.32
  behavioral: 0.30
  implicit_poisoning: 0.60
  external_resources: 0.32
  privilege_violations: 0.50
  manifest_integrity: 0.50
======================================================================

Example 2: Enhanced Scan with LLM

mcp-killchain scan --endpoint http://localhost:3333 \
  --scan-mode enhanced \
  --llm-key sk-proj-... \
  --detailed

Example 3: Custom Headers and Timeout

mcp-killchain scan --endpoint https://api.example.com/mcp \
  --header "Authorization: Bearer token" \
  --header "X-Custom-Header: value" \
  --timeout 60

🔬 How It Works

Analysis Flow

1. Tool Enumeration: Calls tools/list to collect all available tools
2. Capability Classification: Categorizes tools into EIT, PAT, NAT roles
3. YARA Scanning: Detects malicious patterns in tool definitions
4. Schema Poisoning Analysis: Identifies hidden instructions
5. Kill Chain Graph Building: Constructs EIT → PAT → NAT attack paths
6. Autonomy Assessment: Evaluates autonomous execution potential
7. Risk Scoring: Computes MCP Security Score (0-10)
8. Reporting: Generates human-readable and JSON reports

Detection Methods

• Schema-Based Analysis: Analyzes JSON schema parameters (50% weight)
• Semantic Analysis: Context-aware pattern matching (30% weight)
• LLM-Based Analysis: Deep semantic understanding via OpenAI/Anthropic (25% weight)
• Pattern Matching: Traditional keyword detection (20% weight)

🛡️ Security Features

What We Detect

• ✅ Kill Chains: Complete EIT → PAT → NAT attack sequences
• ✅ Schema Poisoning: Hidden instructions in tool definitions
• ✅ Implicit Poisoning (MCP-ITP): Subtle coercion patterns (84.2% ASR)
• ✅ Behavioral Mismatches: Tools that do more than described
• ✅ External Resource Risks: SSRF and parasitic attack vectors
• ✅ Privilege Violations: Excess capabilities and least privilege issues
• ✅ Manifest Tampering: Unauthorized tool definition changes
• ✅ Autonomous Execution: Chains that require no human approval

Threat Model

• MCP servers may be malicious or compromised
• Tool descriptions may contain hidden instructions
• LLMs cannot reliably distinguish data vs. instructions
• Individually safe tools can form autonomous kill chains
• Attacks may be silent and persistent

📋 Command Reference

Main Command

mcp-killchain scan [OPTIONS]

Options

Examples

# Basic scan
mcp-killchain scan --endpoint http://localhost:3333

# Enhanced scan with authentication
mcp-killchain scan --endpoint https://api.example.com \
  --scan-mode enhanced \
  --llm-key sk-proj-... \
  --header "Authorization: Bearer token"

# Quiet mode
mcp-killchain scan --endpoint http://localhost:3333 --quiet

🧪 Testing

Test Server

A vulnerable MCP test server is included for testing:

# Start test server
cd test_server
python server.py

# In another terminal, scan it
mcp-killchain scan --endpoint http://localhost:3333 --scan-mode standard

📊 Output Format

Text Report

The tool generates color-coded text reports with:

• Risk severity (CRITICAL, HIGH, MEDIUM, LOW)
• MCP Security Score (0-10)
• Detected kill chains with details
• Scoring factors breakdown

JSON Report

For programmatic use, JSON output is available:

{
  "risk": "CRITICAL",
  "score": 9.2,
  "severity": "CRITICAL",
  "chains": [
    {
      "chain": ["fetch_url", "read_file", "send_email"],
      "valid": true,
      "autonomous": true,
      "stealth": "HIGH"
    }
  ],
  "factors": {
    "kill_chains": 3.50,
    "privileges": 2.00,
    "autonomy": 2.00
  }
}

🔧 Advanced Configuration

Custom YARA Rules

mcp-killchain scan --endpoint http://localhost:3333 \
  --yara-rules /path/to/custom/rules

Environment Variables

# LLM API keys (optional)
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

# Automatically detected if not provided via --llm-key

🐛 Troubleshooting

Common Installation Issues

Issue: python: command not found or python3: command not found

Solution:

• Windows: Download Python from python.org and ensure "Add Python to PATH" is checked during installation
• Linux/Mac: Install Python using your package manager:

  # Ubuntu/Debian
  sudo apt-get install python3 python3-pip python3-venv
  
  # macOS (with Homebrew)
  brew install python3

Issue: pip: command not found

Solution:

# Linux/Mac
python3 -m ensurepip --upgrade

# Windows
python -m ensurepip --upgrade

Issue: ERROR: Failed building wheel for yara-python

Solution:

• Windows: Install Microsoft Visual C++ Build Tools
• Linux: Install system dependencies:

  sudo apt-get install yara libyara-dev python3-dev build-essential

• macOS: Install via Homebrew:

  brew install yara

• Note: YARA is optional. The tool works without it using fallback pattern matching.

Issue: ModuleNotFoundError: No module named 'yara.engine'

Solution: This is a namespace collision that the tool handles automatically. If issues persist:

# Reinstall the package
pip uninstall mcp-killchain
pip install -e .

Issue: Permission denied when installing

Solution:

• Use a virtual environment (recommended):

  python3 -m venv venv
  source venv/bin/activate  # Linux/Mac
  # or
  .\venv\Scripts\Activate.ps1  # Windows PowerShell

• Or use --user flag:

  pip install --user -e .

Virtual Environment Issues

Issue: Virtual environment not activating

Windows PowerShell:

# If you get "execution of scripts is disabled", run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Linux/Mac:

# Ensure you're in the project directory
cd mcp-killchain
source venv/bin/activate

Issue: Command not found after installation

Solution:

• Ensure virtual environment is activated
• Reinstall the package:

  pip install -e .

• Verify installation:

  which mcp-killchain  # Linux/Mac
  where mcp-killchain  # Windows

📚 Research Context

This tool is based on recent security research:

• Parasitic Toolchain Attacks (Sep 2025): External data injection leading to autonomous chains
• MCP-ITP: Implicit Tool Poisoning (Jan 2026): Subtle coercion with 84.2% ASR
• MCPTox Benchmark (Aug 2025): Tool poisoning patterns with 72.8% ASR

👤 Author

Uudhhay

Security Research Tool for MCP Protocol Analysis

⚠️ Disclaimer

This tool is for security research and assessment purposes only. Use responsibly and only on systems you own or have explicit permission to test.

🔴 mcp-killchain - *Predicting exploits before they happen*