MCP-Scan - Documentación¶
Analizador Estático de Seguridad para Servidores MCP (Model Context Protocol)
Introducción¶
MCP-Scan es una herramienta de análisis estático de seguridad especializada en servidores que implementan el Model Context Protocol (MCP). A diferencia de herramientas SAST genéricas, MCP-Scan está diseñada específicamente para detectar vulnerabilidades en el contexto de interacción entre modelos de lenguaje (LLM) y herramientas externas.
Características Principales¶
- Análisis multi-lenguaje: Python, TypeScript, JavaScript, Go (parcial)
- 46+ detectores de vulnerabilidades en 14 clases (A-N)
- Análisis de flujo de datos (taint): intra e inter-procedural
- Detección de superficie MCP: tools, resources, prompts
- Scoring MSSS: puntuación de seguridad 0-100 con niveles de cumplimiento
- Múltiples formatos de salida: JSON, SARIF 2.1.0, Evidence Bundle
- Integraciones avanzadas: CodeQL, LLM (Ollama), Clasificador ML
Documentación¶
Guía de Usuario¶
Documentación completa para usuarios que quieren usar la herramienta.
| Documento | Descripción |
|---|---|
| Instalación | Cómo instalar mcp-scan |
| Inicio Rápido | Primeros pasos y ejemplos básicos |
| Comandos CLI | Referencia completa de todos los comandos |
| Configuración | Fichero de configuración YAML completo |
| Modos de Análisis | Fast vs Deep mode en detalle |
| Formatos de Salida | JSON, SARIF, Evidence Bundle |
| Gestión de Baseline | Gestión de hallazgos aceptados |
| Integración CI/CD | GitHub Actions, GitLab CI, Jenkins |
| Integración LSP | Servidores de lenguaje para análisis de tipos |
| Casos de Uso | Ejemplos prácticos del mundo real |
Documentación para Analistas¶
Documentación técnica detallada sobre el funcionamiento interno de la herramienta.
| Documento | Descripción |
|---|---|
| Arquitectura del Motor | Pipeline completo y componentes |
| Análisis de Taint | Algoritmo de flujo de datos en detalle |
| Motor de Patrones | Sistema de detección por reglas |
| Clasificador ML | 29 features, algoritmo, limitaciones |
| Detección LLM | Análisis semántico con Ollama |
| Integración CodeQL | Confirmación con CodeQL |
| Integración LSP | Servidores de lenguaje, call graphs, detección type-aware |
| Clases de Vulnerabilidad | Todas las clases A-N explicadas |
| Sistema de Scoring MSSS | Cálculo de puntuación y pesos |
| Superficie MCP | Detección de tools, resources, prompts |
| Especificación de Permisos | NUEVO: Estándar de inferencia de permisos MCP v1.0 |
| Deduplicación | Sistema de deduplicación de findings |
| Limitaciones | Limitaciones conocidas de cada feature |
Documentación para Desarrolladores¶
Guía de integración de mcp-scan como librería Go.
| Documento | Descripción |
|---|---|
| Instalación como Librería | Instalación con go get |
| API Pública | Referencia completa de tipos y métodos |
| Ejemplos de Integración | Muchos ejemplos de código |
| Patrones de Uso | Casos comunes de integración |
| Manejo de Errores | Gestión de errores |
| Concurrencia | Thread safety y uso concurrente |
| Extensión | Reglas y reporters personalizados |
Testing¶
Documentación sobre la suite de tests.
| Documento | Descripción |
|---|---|
| Estructura de Tests | Organización de los tests |
| Fixtures | Fixtures de código vulnerable/benigno |
| DVMCP | Damn Vulnerable MCP Server |
| Ejecutar Tests | Comandos para ejecutar tests |
| Estado Actual | Cobertura y estado de tests |
English Documentation (User Guide)¶
| Document | Description |
|---|---|
| Quickstart | Getting started in 5 minutes |
| Installation | How to install mcp-scan |
| CLI Reference | Complete CLI command reference |
| Configuration | YAML configuration options |
| Output Formats | JSON, SARIF, Evidence Bundle |
| CI/CD Integration | GitHub Actions, GitLab CI |
| Advanced Detectors | LLM, CodeQL, LSP, ML detectors |
| ML Detection | ML-based prompt injection detection |
| Baseline Management | Managing accepted findings |
| Use Cases | Practical real-world examples |
| Analysis Modes | Fast vs Deep mode in detail |
English Documentation (Analyst)¶
| Document | Description |
|---|---|
| Overview | Analysis engine overview |
| Engine Architecture | Complete pipeline and components |
| Analysis Pipeline | Complete analysis pipeline |
| Taint Analysis | Data flow analysis explained |
| Pattern Engine | Pattern-based detection system |
| MCP Surface | MCP surface extraction |
| Rules Reference | Complete rules reference |
| Vulnerability Classes | All vulnerability classes A-N |
| MSSS Scoring | Security scoring system |
| Permissions Specification | NEW: MCP Permission Inference Specification v1.0 |
| ML Classifier | 29 features, algorithm, limitations |
| LLM Detection | Semantic analysis with Ollama |
| CodeQL Integration | CodeQL confirmation |
| LSP Integration | Language servers, call graphs, type-aware detection |
| Limitations | Known limitations of each feature |
English Documentation (Developer)¶
| Document | Description |
|---|---|
| Architecture | Internal architecture |
| API Reference | Go API reference |
| Go API | Using mcp-scan as a library |
| Library Installation | Installing with go get |
| Type Inference | Type inference system |
| Import Resolver | Module resolution |
| Call Graph | Call graph construction |
| Pattern Engine | Pattern matching engine |
| Taint Analysis | Taint engine internals |
| Surface Extraction | MCP surface extraction |
| LSP Integration | Language Server Protocol |
| CodeQL Integration | CodeQL queries and integration |
| LLM Detection | LLM-based detection |
| ML Classifier | ML classifier implementation |
| ML Architecture | Technical architecture of ML system |
| ML Development Process | Development history and lessons learned |
| Operations Guide | Running in production |
| Injection Markers | Prompt injection markers |
| Prompt Flow Detection | Prompt flow analysis |
| CodeQL Rules Analysis | CodeQL rules deep dive |
| Deduplication | Finding deduplication system |
| Concurrency | Thread safety and concurrent use |
| Integration Examples | Many code examples |
| Extension | Custom rules and reporters |
| Error Handling | Error management |
| Usage Patterns | Common integration cases |
English Documentation (Deployment)¶
| Document | Description |
|---|---|
| Deployment README | Deployment overview |
| Production Guide | Running mcp-scan in production |
English Documentation (Testing)¶
| Document | Description |
|---|---|
| Testing README | Testing overview |
| Test Structure | Test organization |
| Fixtures | Vulnerable/benign code fixtures |
| DVMCP | Damn Vulnerable MCP Server |
| Run Tests | Commands to run tests |
| Current Status | Coverage and test status |
Documentacion en Espanol (Despliegue)¶
| Documento | Descripcion |
|---|---|
| README Despliegue | Vision general del despliegue |
| Produccion | Ejecutar mcp-scan en produccion |
Resumen de Clases de Vulnerabilidad¶
| Clase | Nombre | Descripción | Modo |
|---|---|---|---|
| A | RCE | Ejecución remota de código (shell, eval) | Fast/Deep |
| B | Filesystem | Path traversal y acceso a ficheros | Fast/Deep |
| C | SSRF | Server-Side Request Forgery | Fast/Deep |
| D | SQLi | SQL Injection | Fast/Deep |
| E | Secrets | Credenciales hardcodeadas, tokens | Fast/Deep |
| F | Auth | Vulnerabilidades en cookies, JWT, OAuth | Fast/Deep |
| G | Tool Poisoning | Inyección de prompts en descripciones | Fast/Deep |
| H | Prompt Injection | Flujo de datos entre prompts | Deep |
| I | Privilege Escalation | Abuso de privilegios multi-tool | Deep |
| J | Cross-Tool | Fuga de datos entre herramientas | Deep |
| K | AuthN/AuthZ | Bypass de autenticación | Deep |
| L | Lifecycle | Carga de plugins, hot reload | Fast/Deep |
| M | Hidden Network | Canales ocultos, conexiones no documentadas | Fast/Deep |
| N | Supply Chain | Vulnerabilidades en dependencias | Fast/Deep |
Features Avanzadas¶
Análisis de Taint (Flujo de Datos)¶
| Feature | Descripción | Estado |
|---|---|---|
| Intra-procedural | Análisis dentro de funciones | Completo |
| Inter-procedural | Análisis entre funciones (call graph) | Completo |
| Property Taint | Seguimiento de propiedades de objetos | Completo |
| Closures | Análisis de scopes anidados | Completo |
Detección Avanzada¶
| Feature | Requisitos | Estado | Precisión |
|---|---|---|---|
| Clasificador ML | Ninguno (built-in) | Completo | 91% accuracy, 0.94 ROC-AUC |
| Detección LLM | Ollama/Claude/OpenAI | Completo | Multi-proveedor |
| CodeQL | CodeQL CLI instalado | Completo | Alta |
| LSP | Language server | Completo | Type-aware |
📖 Documentación detallada: Advanced Detectors (EN)
Formatos de Salida¶
| Formato | Uso Principal |
|---|---|
| JSON | Procesamiento programático |
| SARIF 2.1.0 | GitHub Code Scanning, CI/CD |
| Evidence Bundle | Auditorías, compliance |
Inicio Rápido¶
# Instalar
go install github.com/mcphub/mcp-scan/cmd/mcp-scan@latest
# Escanear un proyecto (modo rápido)
mcp-scan scan ./mi-servidor-mcp
# Escaneo profundo con SARIF
mcp-scan scan ./mi-servidor-mcp --mode deep --output sarif
# Ver superficie MCP detectada
mcp-scan surface ./mi-servidor-mcp
# Generar fichero de configuración
mcp-scan init
# Generar baseline de hallazgos aceptados
mcp-scan baseline generate ./mi-servidor-mcp
# Escanear con baseline
mcp-scan scan ./mi-servidor-mcp --baseline .mcp-scan-baseline.json
# Fallar CI si hay hallazgos críticos o altos
mcp-scan scan ./mi-servidor-mcp --fail-on high
Arquitectura¶
┌─────────────────────────────────────────────────────────────────────────┐
│ MCP-Scan │
├─────────────────────────────────────────────────────────────────────────┤
│ CLI (scan, init, surface, baseline, version) │
├─────────────────────────────────────────────────────────────────────────┤
│ Motor de Escaneo │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────────────────────────┐ │
│ │Discovery│→ │ Parser │→ │ Surface │→ │ Type Inference │ │
│ │ │ │(tree- │ │Extractor│ │ (Deep mode) │ │
│ │ │ │ sitter) │ │ │ └──────────┬───────────────┘ │
│ └─────────┘ └─────────┘ └─────────┘ │ │
│ ┌───────────▼───────────────┐ │
│ │ Import Resolver │ │
│ │ + Call Graph │ │
│ │ (Deep mode) │ │
│ └───────────┬───────────────┘ │
│ ↓ ↓ ↓ ↓ │
│ ┌────────────────────────────────────────────────────────────────────┐│
│ │ Motor de Taint (type-aware) ││
│ └────────────────────────────────────────────────────────────────────┘│
│ ↓ │
│ ┌────────────────────────────────────────────────────────────────────┐│
│ │ Motor de Patrones ││
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││
│ │ │Reglas AST│ │ Regex │ │ ML │ │ LSP │ │ CodeQL │ ││
│ │ │ (A-N) │ │ Patrones │ │Classifier│ │ Detector │ │ Detector │ ││
│ │ │ │ │(150+ ptn)│ │(29 feat) │ │(Pyright) │ │ (SARIF) │ ││
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ ││
│ │ ││
│ │ ┌──────────────────────────────────────────────────────────────┐ ││
│ │ │ Detector LLM (Ollama) - Análisis local de prompt injection │ ││
│ │ └──────────────────────────────────────────────────────────────┘ ││
│ └────────────────────────────────────────────────────────────────────┘│
│ ↓ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ MSSS │ │Baseline │ │Reporter │ │
│ │ Scorer │ │ Filter │ │JSON/SARIF│ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
Licencia¶
MIT License
Contacto¶
Para reportar bugs o solicitar features, abrir un issue en el repositorio.