MCP-Scan

English | 中文

Command usage: USAGE.md · 中文

An AI Agent-driven automated MCP Server security scanning and vulnerability detection tool, developed by Tencent Zhuque Lab.

✨ Features

• 🤖 Intelligent Agent System: Supports single-stage (fast code audit) and three-stage (Info Collection → Code Audit → Vulnerability Review) scanning modes
• 🔍 Deep Code Analysis: Automatically identifies project structure, tech stack, and potential security vulnerabilities
• 📊 SARIF 2.1.0 Output: CLI mode outputs SARIF 2.1.0 JSON by default, natively consumable by GitHub Code Scanning, Azure DevOps, VS Code, and more
• 🔌 AIG Platform Integration: Interactive scanning via the Web UI with real-time three-stage pipeline results
• 🎯 Dedicated Model Configuration: Configure specialized LLMs for different tasks (thinking, coding, fast response, etc.)
• 📊 Security Scoring System: Automatically calculates project security scores and risk levels
• 🛠️ Extensible Tool System: Easily add custom tools and features
• 📝 Detailed Logging: Full execution process logged with loguru
• 🐛 Debug Mode: Integrated Laminar tracing for easy debugging
• 🕵️ Agent Skill Auditing: Automatically detects and audits Agent Skill project consistency (SKILL.md vs code implementation)
• ⚡ Static Pre-scan: Regex-based scanning for high-risk patterns (curl|bash, cloud metadata, credential theft, etc.) before Agent launch, generating prompt injection context

🚀 Quick Start

Install from PyPI

pip install aig-mcp-scan
aig-mcp-scan --repo ./myproject -o result.sarif.json

The flags below are the same when the command is aig-mcp-scan instead of python main.py.

1. Clone the Project

git clone <your-repo>
cd mcp-scan

2. Install Dependencies

Recommended using uv (faster, auto-manages virtual environments):

uv sync

Or using pip:

pip install -r requirements.txt

3. Run a Scan

mcp-scan supports two usage modes:

Mode 1: Standalone CLI (default single-stage mode)

Outputs SARIF 2.1.0 JSON to stdout by default, suitable for CI/CD integration and fast scanning:

# Basic scan
python main.py --repo ./myproject

# Save results to a file
python main.py --repo ./myproject -o result.sarif.json

# Use a specific model
python main.py --repo ./myproject -m "anthropic/claude-3.5-sonnet"

# Provide API Key via environment variable (no --api_key needed)
export LLM_API_KEY="sk-or-v1-xxxxx"
python main.py --repo ./myproject

# Use a custom prompt
python main.py --repo ./myproject --prompt "Focus on SQL injection vulnerabilities"

# Enable debug mode
python main.py --repo ./myproject --debug

# Combined usage
python main.py --repo ./myproject \
  -m "google/gemini-2.5-pro" \
  -p "Focus on authentication and authorization issues" \
  --debug \
  -o report.sarif.json

# Dynamic analysis (targeting a running MCP Server)
python main.py \
  --server_url "http://localhost:8000/sse" \
  --prompt "Test tool poisoning vulnerabilities"

CLI mode characteristics: Uses single-stage scanning by default (code audit only, ~3x faster than three-stage), outputs SARIF 2.1.0 JSON, natively consumable by GitHub Code Scanning, Azure DevOps, GitLab Security Dashboard, VS Code Problems panel, and other SARIF-aware tools.

Mode 2: AIG Platform Web UI (three-stage mode)

mcp-scan is integrated into the AIG platform, enabling interactive scanning via the Web UI with real-time three-stage pipeline results displayed on the frontend.

Steps:

1. Start the AIG Web service and Agent process

# Start the Web service
go build -o ai-infra-guard ./cmd/cli/main.go
./ai-infra-guard webserver --server 127.0.0.1:8088

# In another terminal, start the Agent process
go build -o agent ./cmd/agent
AIG_SERVER=127.0.0.1:8088 ./agent

2. Use via browser

Open your browser and navigate to http://127.0.0.1:8088:

• Select MCP Scan from the left sidebar
• Add your LLM API Key and model name (e.g., deepseek-v4-flash) in Model Configuration
• Choose input method: upload a source code archive (.zip) or enter a GitHub repository URL
• Click Start Scan

3. View results

During the scan, the three-stage pipeline (Info Collection → Code Audit → Vulnerability Review) progress and results are displayed in real-time on the Web frontend, culminating in a complete report with vulnerability details, risk levels, and a security score.

How it works: When a scan task is submitted from the Web UI, the Go backend dispatches it to the Agent process, which automatically invokes mcp-scan with --aig-mode. Structured JSON logs are output to stdout via mcpLogger, parsed by the Go backend, and pushed to the frontend in real-time. Users do not need to manually run the --aig-mode command.

📖 CLI Options Reference

Option	Shorthand	Description	Default
--repo	-	Required for static scanning. Path to the project to scan (can be omitted when using --server_url for dynamic analysis)	-
--prompt	-p	Custom scan prompt	""
--model	-m	LLM model name	deepseek/deepseek-v3.2-exp
--api_key	-k	API key (falls back to env vars LLM_API_KEY/OPENAI_API_KEY/OPENROUTER_API_KEY)	From env vars
--base_url	-u	API base URL	https://openrouter.ai/api/v1
--debug	-	Enable debug mode (includes Laminar tracing)	False
--server_url	-	Remote MCP server URL (enables dynamic analysis mode)	None
--header	-	Custom HTTP header (key:value), can be used multiple times	[]
--language	-	Output language (zh/en)	zh
--aig-mode	-	Enable AIG integration mode: outputs structured JSON logs for the Go backend. Automatically invoked by the AIG platform; not needed for standalone CLI use	False
--output	-o	Save scan results to a JSON file	None

Configuration priority (high to low): CLI arguments > Environment variables > Code defaults

📊 SARIF Output Format

CLI mode outputs SARIF 2.1.0 JSON by default, containing:

• rules: Statically declares the full MCP01–MCP10 + 3 supplemental classification rules (Name Confusion, Rug Pull, Tool Shadowing), always output even if no vulnerabilities are found
• results: Each vulnerability maps to a rule ID, including level (error/warning/note), locations (file + line number), and partialFingerprints (dedup hash). Remediation guidance is included in message.text and preserved separately in properties.suggestion; prose recommendations are not emitted as machine-applicable SARIF fixes.
• properties: Security score, primary language, LLM used, scan duration

Migration note: earlier releases carried the remediation text in results[].fixes[0].description.text. That field is no longer emitted — read results[].properties.suggestion instead (the same text is also appended to message.text).

SARIF files can be uploaded directly to GitHub Code Scanning:

# GitHub Actions example
python main.py --repo ./myproject -o results.sarif.json
# Then use github/codeql-action/upload-sarif@v3 in your workflow

MCP Risk Classification

mcp-scan uses 10 MCP-specific security risk categories plus 3 supplemental classifications:

Rule ID	Name	Description
MCP01	Token & Secret Exposure	Credential theft and key leakage
MCP02	Privilege Escalation & Scope Creep	Overly broad tool permission definitions
MCP03	Tool Poisoning Attack	Legitimate tools injected with malicious logic
MCP04	Supply Chain Attack	Dependency tampering, malicious third-party servers
MCP05	Command Injection & Execution	Untrusted input constructing system commands
MCP06	Prompt Injection Attack	Context-injected malicious instructions hijacking the model
MCP07	Insufficient Auth & Authorization	Missing identity verification leading to privilege escalation
MCP08	Missing Audit & Telemetry	Lack of tamper-proof call logs
MCP09	Shadow MCP Server	Unauthorized MCP instances deployed
MCP10	Context Injection & Over-sharing	Sensitive context leaking across sessions
Name Confusion	Name Confusion Attack	Similar names inducing incorrect tool calls
Rug Pull Attack	Rug Pull Attack	Changing behavior after gaining trust
Tool Shadowing Attack	Tool Shadowing Attack	Redefining same-named tools to override legitimate behavior

⚙️ Configuration

Create a .env file or set environment variables in your system. The program auto-loads .env on startup and also recognizes system environment variables.

Main LLM Configuration

# OpenRouter API Key (required)
OPENROUTER_API_KEY=your-api-key-here

# Default model
DEFAULT_MODEL=deepseek/deepseek-v3.2-exp

# API base URL
DEFAULT_BASE_URL=https://openrouter.ai/api/v1

Dedicated LLM Configuration

Configure specialized models for different tasks, each with its own API key and base URL:

# Thinking model (for deep reasoning)
THINKING_MODEL=google/gemini-2.5-pro
THINKING_BASE_URL=https://openrouter.ai/api/v1
THINKING_API_KEY=  # Optional, uses main API key if not set

# Coding model (for code generation and analysis)
CODING_MODEL=anthropic/claude-sonnet-4.5
CODING_BASE_URL=https://openrouter.ai/api/v1
CODING_API_KEY=  # Optional, uses main API key if not set

Debug & Logging Configuration

# Laminar API Key (for debug mode tracing)
LAMINAR_API_KEY=your-laminar-api-key

# Log level
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

📁 Project Structure

mcp-scan/
├── mcp_scan/               # Core package (installable via uv/pip)
│   ├── agent/             # Agent core implementation
│   │   ├── agent.py       # Main Agent (single-stage/three-stage scan dispatch)
│   │   └── base_agent.py  # Base Agent class (challenge mechanism + result truncation)
│   ├── tools/             # Tool modules
│   │   ├── registry.py    # Tool registration system
│   │   ├── thinking/      # Thinking tool
│   │   ├── finish/        # Finish tool
│   │   ├── file/          # File operation tools
│   │   └── execute/       # Code execution tools
│   ├── utils/             # Utility functions
│   │   ├── config.py      # Configuration management
│   │   ├── llm.py         # LLM base wrapper
│   │   ├── llm_manager.py # LLM manager (multi-model support)
│   │   ├── loging.py      # Logging configuration
│   │   ├── parse.py       # XML parsing
│   │   ├── project_analyzer.py # Project analysis tools
│   │   ├── extract_vuln.py     # Vulnerability extraction (structured file/line localization)
│   │   ├── pre_scan.py         # Static pre-scan (14 high-risk pattern regex detection)
│   │   ├── sarif_formatter.py  # SARIF 2.1.0 formatter (MCP01-MCP10 rule system)
│   │   ├── tool_context.py     # Tool context
│   │   └── aig_logger.py       # Structured logging
│   ├── redteam/           # Multi-turn red-teaming module
│   │   ├── orchestrator.py # Red-team orchestrator
│   │   ├── attacker.py    # Attack strategy execution
│   │   ├── evaluator.py   # Response evaluation
│   │   └── report.py      # Report generation
│   ├── prompt/            # Prompt templates
│   │   ├── system_prompt.md   # System prompt
│   │   └── agents/            # Per-stage Agent prompts
│   │       ├── project_summary.md # Info collection (incl. Skill detection)
│   │       ├── code_audit.md      # Code audit (incl. Skill consistency audit)
│   │       └── vuln_review.md     # Vulnerability review
│   ├── main.py            # Package entry (CLI)
│   └── __main__.py        # python -m mcp_scan entry
├── main.py                 # Thin shell for AIG Go backend compatibility (uv run main.py)
├── pyproject.toml          # Project config (version 0.2.0, Python >=3.10)
├── py.typed                # PEP 561 type marker
├── requirements.txt        # Dependencies
├── env.example            # Environment variable template
└── README.md              # This document

🔧 How It Works

Scan Modes

mcp-scan supports two scanning modes, switched via the --aig-mode flag:

Single-Stage Mode (CLI default, without --aig-mode)

1. Static Pre-scan
   ├── Regex scan for 14 high-risk pattern categories
   └── Generate prompt injection Agent context

2. Code Audit
   ├── Inject project directory tree as context
   ├── LLM-driven deep code analysis
   ├── Challenge mechanism to detect sensitive patterns in tool results
   └── Tool result truncation to prevent context overflow

3. Output SARIF 2.1.0 JSON

~3x faster than three-stage, suitable for CI/CD integration and quick scans.

Three-Stage Mode (--aig-mode)

1. Information Collection
   ├── Analyze project structure
   ├── Identify tech stack
   └── Identify project type (regular project / Agent Skill)

2. Code Audit
   ├── Deep code analysis
   ├── Identify security issues
   └── If Agent Skill, perform consistency audit (Intent Alignment Check)

3. Vulnerability Review
   ├── Consolidate discovered vulnerabilities
   ├── Assess risk levels
   └── Generate detailed report

Outputs structured JSON to stdout via mcpLogger for the AIG platform Go backend to parse.

Agent Skill Audit

If a SKILL.md file exists in the project root, the tool automatically triggers an Agent Skill consistency audit:

• Intent Alignment: Compares SKILL.md descriptions with code implementations in scripts/.
• Hidden Behavior Detection: Checks for hidden functionality not mentioned in the description.
• Output Format Validation: Verifies code output matches the described expected format.

🤝 Development

It is recommended to use uv for local development environment management (supports Python >=3.10). To initialize the dev environment:

uv sync --extra dev --extra test

Before committing, it is recommended to run at least:

uv run ruff check . --fix
uv run ruff format .

Running Tests

uv run pytest

Viewing Logs

Log files are located in the project root directory, named agent_YYYYMMDD_HHMMSS.log.

📄 License

MIT License

🙏 Acknowledgments

Tencent Zhuque Lab AI-Infra-Guard project team.

---

Note: This tool is intended for legitimate security testing and code auditing only. Do not use it for unauthorized system testing.