Detectores Avanzados¶

mcp-scan incluye cuatro sistemas de deteccion avanzados que proporcionan analisis de seguridad profundo mas alla del reconocimiento de patrones:

LLM Multi-Proveedor - Analisis semantico usando modelos de IA
CodeQL - Analisis semantico profundo con consultas personalizadas
LSP - Analisis con reconocimiento de tipos via Language Server Protocol
ML - Clasificacion basada en aprendizaje automatico

Deteccion LLM Multi-Proveedor¶

El detector LLM utiliza modelos de lenguaje grandes para analizar semanticamente texto en busca de intentos de inyeccion de prompts. Soporta multiples proveedores:

Proveedor	Tipo	Clave API	Modelo Por Defecto
Ollama	Local	No requerida	llama3.2:3b
Claude	Nube (Anthropic)	`ANTHROPIC_API_KEY`	claude-3-haiku-20240307
OpenAI	Nube	`OPENAI_API_KEY`	gpt-4o-mini

Configuracion¶

Usando Ollama (Local)¶

# Iniciar Ollama
ollama serve

# Descargar un modelo
ollama pull llama3.2:3b

# Ejecutar escaneo con deteccion LLM
mcp-scan scan ./mi-servidor-mcp --llm --llm-provider ollama

Usando Claude (Anthropic)¶

# Establecer clave API
export ANTHROPIC_API_KEY=sk-ant-...

# Ejecutar escaneo
mcp-scan scan ./mi-servidor-mcp --llm --llm-provider claude

Usando OpenAI¶

# Establecer clave API
export OPENAI_API_KEY=sk-...

# Ejecutar escaneo
mcp-scan scan ./mi-servidor-mcp --llm --llm-provider openai

Auto-deteccion¶

Si no se especifica proveedor, mcp-scan auto-detectara los proveedores disponibles en este orden: 1. Ollama (si esta ejecutandose localmente) 2. Claude (si ANTHROPIC_API_KEY esta configurada) 3. OpenAI (si OPENAI_API_KEY esta configurada)

# Auto-detectar proveedor
mcp-scan scan ./mi-servidor-mcp --llm

Flags de CLI¶

Flag	Descripcion	Por Defecto
`--llm`	Habilitar deteccion LLM	false
`--no-llm`	Deshabilitar deteccion LLM	-
`--llm-provider`	Proveedor: ollama, claude, openai	auto-detectar
`--llm-url`	URL de Ollama	http://localhost:11434
`--llm-model`	Nombre del modelo	Especifico del proveedor
`--llm-threshold`	Umbral de confianza (0-1)	0.7
`--llm-timeout`	Tiempo limite de solicitud	60s

Configuracion YAML¶

llm:
  enabled: true
  provider: "ollama"      # ollama, claude, openai
  url: "http://localhost:11434"
  model: "llama3.2:3b"
  threshold: 0.7
  timeout: "60s"
  max_length: 5000

Deteccion CodeQL¶

CodeQL proporciona analisis semantico profundo usando el lenguaje de consultas de GitHub. Puede detectar vulnerabilidades complejas como flujos de taint a traves de limites de funciones.

Prerequisitos¶

Instalar CodeQL CLI:

# macOS
brew install codeql

# Linux
CODEQL_VERSION=2.16.0
curl -L -o codeql.tar.gz \
  "https://github.com/github/codeql-cli-binaries/releases/download/v${CODEQL_VERSION}/codeql-linux64.tar.gz"
tar xzf codeql.tar.gz
sudo mv codeql /opt/codeql
export PATH="/opt/codeql:$PATH"

# Verificar instalacion
codeql version

Uso¶

# Escaneo basico con CodeQL
mcp-scan scan ./mi-servidor-mcp --codeql

# Con consultas personalizadas
mcp-scan scan ./mi-servidor-mcp --codeql --codeql-queries-dir ./mis-consultas

# Con filtro de severidad minima
mcp-scan scan ./mi-servidor-mcp --codeql --codeql-min-severity 5.0

Flags de CLI¶

Flag	Descripcion	Por Defecto
`--codeql`	Habilitar deteccion CodeQL	false
`--no-codeql`	Deshabilitar deteccion CodeQL	-
`--codeql-path`	Ruta al binario codeql	auto-detectar
`--codeql-timeout`	Tiempo limite de analisis	30m
`--codeql-queries-dir`	Directorio de consultas personalizadas	-
`--codeql-min-severity`	Puntuacion CVSS minima	0.0

Configuracion YAML¶

codeql:
  enabled: true
  path: ""  # Auto-detectar en PATH
  timeout: "30m"
  queries_dir: "./codeql-queries/mcp"
  languages: ["python", "javascript"]
  min_severity: 5.0

Consultas Especificas para MCP¶

mcp-scan incluye consultas CodeQL personalizadas para vulnerabilidades MCP:

PromptInjection.ql - Detecta patrones de inyeccion de prompts en descripciones de tools
UnsafeExec.ql - Detecta inyeccion de comandos desde entradas de tools
PathTraversal.ql - Detecta vulnerabilidades de path traversal

Deteccion LSP¶

El detector LSP utiliza el Language Server Protocol para realizar analisis con reconocimiento de tipos.

Prerequisitos¶

Instalar servidores de lenguaje:

# Python (Pyright)
npm install -g pyright

# TypeScript/JavaScript
npm install -g typescript typescript-language-server

# Go
go install golang.org/x/tools/gopls@latest

# Verificar
./scripts/check-lsp.sh

Uso¶

mcp-scan scan ./mi-servidor-mcp --lsp

Flags de CLI¶

Flag	Descripcion	Por Defecto
`--lsp`	Habilitar deteccion LSP	false
`--no-lsp`	Deshabilitar deteccion LSP	-

Configuracion YAML¶

lsp:
  enabled: true
  languages: ["python", "typescript", "go"]

Deteccion ML¶

El detector ML utiliza aprendizaje automatico para clasificar texto como potencial inyeccion de prompts. mcp-scan proporciona dos enfoques de ML:

Modelo	Tipo	Precision	Velocidad	Caso de Uso
Regresion Logistica	Basado en caracteristicas	~91%	Rapido (~1ms)	CI/CD, tiempo real
DeBERTa	Transformer	~95%+	Medio (~10ms)	Necesidades de alta precision

Documentacion Detallada: Guia de Deteccion ML

Rendimiento del Modelo¶

El modelo de Regresion Logistica entrenado logra:

Metrica	Valor
ROC-AUC	0.9471
F1 (Inyeccion)	0.85
Precision	0.82
Recall	0.88
Exactitud	91%

Inicio Rapido¶

# Instalar dependencias
pip install datasets scikit-learn numpy

# Entrenar el modelo
python scripts/train_ml.py ml_weights.json

# Ejecutar escaneo con deteccion ML
mcp-scan scan ./mi-servidor-mcp --ml --ml-model ml_weights.json

Entrenar DeBERTa (Mayor Precision)¶

Para entornos que requieren mayor precision:

# Instalar dependencias de transformers
pip install transformers datasets torch onnx onnxruntime accelerate

# Entrenar modelo DeBERTa
python scripts/train_deberta.py --output-dir ./models/deberta

# Usar modelo ONNX para inferencia
# (Ver deteccion-ml.md para detalles de integracion)

Flags de CLI¶

Flag	Descripcion	Por Defecto
`--ml`	Habilitar deteccion ML	false
`--no-ml`	Deshabilitar deteccion ML	-
`--ml-model`	Ruta a pesos entrenados (JSON)	-
`--ml-threshold`	Umbral de clasificacion (0-1)	0.3

Configuracion YAML¶

ml:
  enabled: true
  threshold: 0.3
  model_path: "./ml_weights.json"

Ajuste de Umbral¶

Caso de Uso	Umbral	Comportamiento
Alto Recall (capturar todo)	0.3	Mas falsos positivos
Balanceado (por defecto)	0.5	F1 optimo
Alta Precision	0.7	Menos falsos positivos
Optimo (entrenado)	0.578	Mejor F1 en conjunto de prueba

Categorias de Deteccion¶

El clasificador ML identifica estos tipos de inyeccion:

instruction_override - "Ignora las instrucciones anteriores"
jailbreak - Intentos DAN, modo desarrollador
identity_manipulation - "Actua como un hacker"
system_prompt_extraction - "Cuales son tus instrucciones?"
data_exfiltration - "Incluye la clave API en la respuesta"
delimiter_injection - Marcadores <|system|>
command_injection - "Ejecuta comando de shell"

Detalles Tecnicos: Arquitectura ML | Proceso de Desarrollo

Combinando Detectores¶

Para maxima cobertura, combina multiples detectores:

# Todos los detectores habilitados
mcp-scan scan ./mi-servidor-mcp --llm --codeql --lsp --ml

# Con configuracion
mcp-scan scan ./mi-servidor-mcp \
  --llm --llm-provider claude \
  --codeql --codeql-min-severity 5.0 \
  --lsp \
  --ml --ml-model ml_weights.json

Configuracion YAML Completa¶

version: "1"

mode: deep
timeout: 30m
fail_on: high

llm:
  enabled: true
  provider: "claude"
  model: "claude-3-haiku-20240307"
  threshold: 0.7
  timeout: "60s"

codeql:
  enabled: true
  timeout: "30m"
  queries_dir: "./codeql-queries/mcp"
  min_severity: 5.0

lsp:
  enabled: true
  languages: ["python", "typescript"]

ml:
  enabled: true
  threshold: 0.3
  model_path: "./ml_weights.json"

Variables de Entorno¶

Variable	Descripcion
`ANTHROPIC_API_KEY`	Clave API para Claude
`OPENAI_API_KEY`	Clave API para OpenAI
`MCP_SCAN_LLM_PROVIDER`	Proveedor LLM por defecto
`MCP_SCAN_LLM_URL`	URL de Ollama
`MCP_SCAN_CODEQL_PATH`	Ruta al binario CodeQL

Consideraciones de Rendimiento¶

Detector	Velocidad	Uso de Recursos	Mejor Para
Pattern	Rapido	Bajo	CI/CD, escaneos rapidos
ML	Rapido	Bajo	Procesamiento por lotes
LLM (Ollama)	Medio	Alto	Analisis local
LLM (Nube)	Medio	Bajo	Produccion
LSP	Medio	Medio	Analisis con tipos
CodeQL	Lento	Alto	Analisis profundo, certificacion

Configuraciones Recomendadas¶

Pipeline CI/CD (rapido):

mcp-scan scan . --mode fast --ml

Revision de Pull Request:

mcp-scan scan . --llm --ml

Auditoria de Seguridad (exhaustiva):

mcp-scan scan . --mode deep --llm --codeql --lsp --ml

Certificacion:

mcp-scan scan . --mode deep --llm --llm-provider claude --codeql --lsp --ml --output sarif