Configuracion de MCP-Scan¶

Guia completa de todas las opciones de configuracion disponibles.

Tabla de Contenidos¶

Archivo de Configuracion
Descubrimiento de Archivos
Configuracion del Escaneo
Configuracion de Reglas
Reglas Personalizadas
Allowlists
Configuracion de Salida
Configuracion LLM
Configuracion ML
Configuracion CodeQL
Configuracion LSP
Ejemplos Completos

Archivo de Configuracion¶

Creacion¶

# Crear archivo con valores por defecto
mcp-scan init

# Crear en ubicacion especifica
mcp-scan init --output config/mcp-scan.yaml

Descubrimiento Automatico¶

MCP-Scan busca el archivo de configuracion en este orden:

Ruta especificada con --config
.mcp-scan.yaml en el directorio actual
.mcp-scan.yml en el directorio actual
Busqueda en directorios padre (hasta la raiz)

# Usa .mcp-scan.yaml automaticamente
mcp-scan scan .

# Especificar explicitamente
mcp-scan scan . --config /ruta/a/config.yaml

Estructura General¶

# .mcp-scan.yaml

# Seccion: Descubrimiento de archivos
include: []
exclude: []

# Seccion: Configuracion del escaneo
scan:
  mode: fast
  timeout: 5m
  fail_on: ""

# Seccion: Reglas
rules:
  disabled: []
  severity_overrides: {}
  custom: []

# Seccion: Allowlists
allowlist:
  hosts: []
  url_schemes: []

# Seccion: Salida
output:
  redact_snippets: false

# Seccion: LLM (opcional)
llm:
  enabled: false

# Seccion: ML (opcional)
ml:
  enabled: true

# Seccion: CodeQL (opcional)
codeql:
  enabled: false

# Seccion: LSP (opcional)
lsp:
  enabled: false

Descubrimiento de Archivos¶

include¶

Patrones glob de archivos a incluir en el analisis.

include:
  # Python
  - "**/*.py"

  # TypeScript
  - "**/*.ts"
  - "**/*.tsx"
  - "**/*.mts"
  - "**/*.cts"

  # JavaScript
  - "**/*.js"
  - "**/*.jsx"
  - "**/*.mjs"
  - "**/*.cjs"

  # Go (parsing solamente)
  - "**/*.go"

Patrones glob soportados:

Patron	Descripcion
`*`	Cualquier caracter excepto `/`
`**`	Cualquier numero de directorios
`?`	Un solo caracter
`[abc]`	Caracteres en corchetes
`[!abc]`	Caracteres NO en corchetes

Ejemplos:

include:
  # Solo archivos en src/
  - "src/**/*.py"

  # Solo archivos Python en la raiz
  - "*.py"

  # Archivos que empiezan con server
  - "**/server*.py"

  # Archivos con version en nombre
  - "**/*v[0-9]*.ts"

exclude¶

Patrones glob de archivos a excluir del analisis.

exclude:
  # Dependencias
  - "**/node_modules/**"
  - "**/vendor/**"

  # Entornos virtuales Python
  - "**/venv/**"
  - "**/.venv/**"
  - "**/env/**"

  # Control de versiones
  - "**/.git/**"
  - "**/.svn/**"

  # Builds
  - "**/dist/**"
  - "**/build/**"
  - "**/out/**"

  # Cache
  - "**/__pycache__/**"
  - "**/.pytest_cache/**"
  - "**/.mypy_cache/**"
  - "**/*.pyc"

  # Tests (opcional)
  - "**/tests/**"
  - "**/test/**"
  - "**/*_test.py"
  - "**/*.test.ts"
  - "**/*.spec.ts"

  # Documentacion
  - "**/docs/**"
  - "**/*.md"

  # Configuracion
  - "**/.*"  # Archivos ocultos

Nota: Las exclusiones tienen prioridad sobre las inclusiones.

Configuracion del Escaneo¶

scan.mode¶

Modo de analisis a usar.

Valor	Descripcion	Uso
`fast`	Analisis intra-procedural	CI/CD, desarrollo
`deep`	Analisis inter-procedural	Auditorias, certificacion

scan:
  mode: fast  # o deep

Diferencias:

Caracteristica	Fast	Deep
Velocidad	Rapido	Lento
Flujo de datos	Dentro de funciones	Entre funciones
Call graph	No	Si
Memoria	Baja	Alta
Falsos negativos	Mas	Menos

scan.timeout¶

Tiempo maximo de escaneo.

scan:
  timeout: 5m  # 5 minutos

Formatos validos:

Formato	Ejemplo
Segundos	`30s`
Minutos	`5m`
Horas	`1h`
Combinado	`1h30m`
Cero (sin limite)	`0`

scan:
  timeout: 30s   # 30 segundos (CI rapido)
  timeout: 5m    # 5 minutos (default)
  timeout: 1h    # 1 hora (auditorias)
  timeout: 0     # Sin limite (cuidado!)

scan.fail_on¶

Severidad minima para codigo de salida no cero.

Valor	Falla en
`info`	Cualquier hallazgo
`low`	Low, Medium, High, Critical
`medium`	Medium, High, Critical
`high`	High, Critical
`critical`	Solo Critical
`""`	Nunca (solo reporta)

scan:
  fail_on: high  # Falla en high o critical

Uso en CI/CD:

# Strict (cualquier hallazgo falla)
scan:
  fail_on: info

# Moderado (medium o superior)
scan:
  fail_on: medium

# Relajado (solo criticos)
scan:
  fail_on: critical

# Solo reportar (no falla)
scan:
  fail_on: ""

scan.workers¶

Numero de workers paralelos.

scan:
  workers: 4  # 4 workers
  workers: 0  # Auto-detectar (CPUs)

Configuracion de Reglas¶

rules.disabled¶

Lista de IDs de reglas a desactivar.

rules:
  disabled:
    # Deshabilitar reglas especificas
    - "MCP-E001"  # Secretos hardcodeados
    - "MCP-E002"  # Variables de secretos

    # Deshabilitar clases completas
    - "MCP-N001"  # Lockfile no encontrado
    - "MCP-N002"  # Dependencia no confiable

IDs de reglas disponibles:

Clase	IDs	Descripcion
A	MCP-A003, MCP-A004	RCE
B	MCP-B002	Filesystem
C	MCP-C002	SSRF
D	MCP-D002	SQLi
E	MCP-E001, MCP-E002, MCP-E005	Secrets
F	MCP-F001, MCP-F002, MCP-F003	Auth
G	MCP-G001, MCP-G002, MCP-G003	Poisoning
N	MCP-N001, MCP-N002, MCP-N003	Supply Chain

rules.severity_overrides¶

Sobrescribir la severidad de reglas especificas.

rules:
  severity_overrides:
    # Subir severidad
    MCP-E001: critical  # Secretos siempre criticos

    # Bajar severidad
    MCP-N001: info      # Lockfile no encontrado solo informativo

    # Para tu entorno
    MCP-B002: medium    # Path traversal menos critico internamente

Severidades validas: info, low, medium, high, critical

Reglas Personalizadas¶

Define reglas de deteccion propias basadas en patrones regex.

Estructura de una Regla Custom¶

rules:
  custom:
    - id: "CUSTOM-001"           # ID unico (requerido)
      pattern: "patron_regex"     # Regex a buscar (requerido)
      severity: high              # Severidad (requerido)
      confidence: medium          # Confianza (requerido)
      class: A                    # Clase de vulnerabilidad (requerido)
      description: "Descripcion"  # Descripcion del hallazgo (requerido)
      remediation: "Como arreglar" # Remediacion (opcional)
      languages:                  # Lenguajes donde aplicar (opcional)
        - python
        - javascript

Campos de Regla Custom¶

Campo	Tipo	Requerido	Descripcion
`id`	string	Si	Identificador unico
`pattern`	string	Si	Expresion regular
`severity`	string	Si	info, low, medium, high, critical
`confidence`	string	Si	low, medium, high
`class`	string	Si	Clase A-N
`description`	string	Si	Descripcion del hallazgo
`remediation`	string	No	Como resolver
`languages`	[]string	No	Filtrar por lenguaje

Ejemplos de Reglas Custom¶

rules:
  custom:
    # Detectar uso de pickle (deserializacion insegura)
    - id: "CUSTOM-PICKLE-001"
      pattern: "pickle\\.loads?\\("
      severity: high
      confidence: high
      class: A
      description: "Uso de pickle detectado - deserializacion insegura"
      remediation: "Usar json u otro formato seguro de serializacion"
      languages:
        - python

    # Detectar eval() en JavaScript
    - id: "CUSTOM-EVAL-001"
      pattern: "\\beval\\s*\\("
      severity: critical
      confidence: high
      class: A
      description: "Uso de eval() detectado"
      remediation: "Evitar eval(), usar alternativas seguras"
      languages:
        - javascript
        - typescript

    # Detectar credenciales en URLs
    - id: "CUSTOM-CREDS-URL"
      pattern: "(https?|ftp)://[^:]+:[^@]+@"
      severity: high
      confidence: medium
      class: E
      description: "Credenciales en URL detectadas"
      remediation: "Mover credenciales a variables de entorno"

    # Detectar console.log de objetos de request
    - id: "CUSTOM-LOG-REQUEST"
      pattern: "console\\.log\\([^)]*req(uest)?[^)]*\\)"
      severity: medium
      confidence: low
      class: E
      description: "Posible logging de datos sensibles de request"
      remediation: "Evitar loguear objetos request completos"
      languages:
        - javascript
        - typescript

    # Detectar funciones internas expuestas
    - id: "CUSTOM-INTERNAL-001"
      pattern: "@tool\\s*\\n\\s*def\\s+_"
      severity: medium
      confidence: medium
      class: G
      description: "Funcion interna expuesta como tool MCP"
      remediation: "Las funciones internas (prefijo _) no deben ser tools"
      languages:
        - python

    # Detectar tokens de API de terceros
    - id: "CUSTOM-API-TOKENS"
      pattern: "(sk|pk|api)[-_]?(key|token|secret)\\s*[=:]\\s*['\"][a-zA-Z0-9]{20,}['\"]"
      severity: critical
      confidence: medium
      class: E
      description: "Token de API hardcodeado detectado"
      remediation: "Usar variables de entorno para tokens"

    # Detectar comentarios TODO de seguridad
    - id: "CUSTOM-TODO-SECURITY"
      pattern: "#\\s*TODO.*security|#\\s*FIXME.*vuln"
      severity: info
      confidence: high
      class: "info"
      description: "Comentario de seguridad pendiente"
      remediation: "Revisar y resolver el comentario de seguridad"

Patrones Regex Utiles¶

Proposito	Patron
Funcion especifica	`\\bfunction_name\\s*\\(`
Metodo de clase	`\\.method_name\\s*\\(`
Decorador Python	`@decorator_name`
Import Python	`from\\s+module\\s+import`
Import JS/TS	`import\\s+.*from\\s+['\"]module['\"]`
Variable con valor	`variable\\s=\\s['\"].*['\"]`
Comentario	`#.texto` o `//.texto`

Allowlists¶

allowlist.hosts¶

Hosts permitidos para verificaciones de SSRF.

allowlist:
  hosts:
    # Hosts exactos
    - "api.example.com"
    - "internal.mycompany.net"

    # Wildcards (subdominios)
    - "*.example.com"        # Cualquier subdominio
    - "*.internal.myco.net"  # Subdominios internos

    # IPs (usar con cuidado)
    - "192.168.1.100"
    - "10.0.0.*"

Comportamiento:

Patron	Coincide con
`api.example.com`	Solo `api.example.com`
`*.example.com`	`foo.example.com`, `bar.example.com`, etc.
`..example.com`	`a.b.example.com`, `x.y.example.com`, etc.

# Ejemplo: Empresa con servicios internos
allowlist:
  hosts:
    # APIs de produccion
    - "api.production.mycompany.com"
    - "auth.production.mycompany.com"

    # Servicios internos (todos los subdominios)
    - "*.internal.mycompany.net"

    # APIs de terceros aprobadas
    - "api.stripe.com"
    - "api.twilio.com"
    - "*.amazonaws.com"

allowlist.url_schemes¶

Esquemas de URL permitidos.

allowlist:
  url_schemes:
    - "https"   # Solo HTTPS
    - "wss"     # WebSocket seguro

Esquemas comunes:

Esquema	Descripcion	Riesgo
`https`	HTTP seguro	Bajo
`http`	HTTP plano	Medio (sin cifrado)
`wss`	WebSocket seguro	Bajo
`ws`	WebSocket plano	Medio
`file`	Sistema de archivos	Alto
`ftp`	Transferencia archivos	Alto

# Configuracion estricta (recomendada)
allowlist:
  url_schemes:
    - "https"
    - "wss"

# Configuracion permisiva (desarrollo)
allowlist:
  url_schemes:
    - "https"
    - "http"    # Solo para desarrollo local
    - "wss"
    - "ws"

Configuracion de Salida¶

output.redact_snippets¶

Ocultar codigo en los reportes.

output:
  redact_snippets: false  # Mostrar codigo (default)
  redact_snippets: true   # Ocultar codigo

Cuando usar:

Caso	Valor	Razon
Desarrollo interno	`false`	Ver codigo ayuda a entender
Reportes a terceros	`true`	No exponer codigo fuente
Auditorias externas	`true`	Confidencialidad
CI/CD interno	`false`	Debugging

Configuracion LLM¶

Habilita deteccion basada en LLM usando Ollama.

Opciones LLM¶

llm:
  enabled: false                       # Activar/desactivar
  base_url: "http://localhost:11434"   # URL de Ollama
  model: "llama3.2:3b"                 # Modelo a usar
  threshold: 0.7                       # Umbral de confianza (0.0-1.0)
  max_length: 5000                     # Longitud maxima de texto

Campo	Tipo	Default	Descripcion
`enabled`	bool	`false`	Activar deteccion LLM
`base_url`	string	`http://localhost:11434`	URL de Ollama
`model`	string	`llama3.2:3b`	Modelo de Ollama
`threshold`	float	`0.7`	Confianza minima
`max_length`	int	`5000`	Caracteres max por analisis

Modelos Recomendados¶

Modelo	Tamano	Velocidad	Precision
`llama3.2:3b`	3B	Rapido	Buena
`llama3.2:8b`	8B	Medio	Mejor
`codellama:7b`	7B	Medio	Buena para codigo
`mistral:7b`	7B	Rapido	Buena

Ejemplo de Uso LLM¶

# Configuracion para deteccion de prompt injection
llm:
  enabled: true
  base_url: "http://localhost:11434"
  model: "llama3.2:3b"
  threshold: 0.8    # Umbral alto para menos falsos positivos
  max_length: 3000  # Limitar para velocidad

Requisitos:

Ollama instalado y ejecutandose
Modelo descargado (ollama pull llama3.2:3b)
Puerto 11434 accesible

Configuracion ML¶

Configuracion del clasificador de machine learning integrado.

ml:
  enabled: true                    # Activar/desactivar
  confidence_threshold: 0.7        # Umbral de confianza
  model_path: ""                   # Ruta a modelo custom (opcional)

Campo	Tipo	Default	Descripcion
`enabled`	bool	`true`	Activar clasificador ML
`confidence_threshold`	float	`0.7`	Confianza minima
`model_path`	string	`""`	Modelo personalizado

Clasificador por Defecto¶

El clasificador integrado detecta:

Jailbreak attempts
Identity manipulation
Instruction override
System prompt extraction
Data exfiltration
Delimiter injection
Command injection

# Configuracion recomendada
ml:
  enabled: true
  confidence_threshold: 0.7  # Equilibrio precision/recall

Configuracion CodeQL¶

Habilita confirmacion secundaria con CodeQL.

codeql:
  enabled: false           # Activar/desactivar
  cli_path: ""             # Ruta a codeql CLI (opcional si esta en PATH)
  queries_path: ""         # Ruta a queries personalizadas
  database_path: ""        # Ruta para guardar databases

Campo	Tipo	Default	Descripcion
`enabled`	bool	`false`	Activar CodeQL
`cli_path`	string	`""`	Ruta a `codeql` CLI
`queries_path`	string	`""`	Queries custom
`database_path`	string	`""`	Directorio para DBs

Query Suites por Defecto¶

Lenguaje	Suite
Python	`codeql/python-queries:codeql-suites/python-security-extended.qls`
JavaScript	`codeql/javascript-queries:codeql-suites/javascript-security-extended.qls`
Go	`codeql/go-queries:codeql-suites/go-security-extended.qls`

Ejemplo CodeQL¶

codeql:
  enabled: true
  cli_path: "/usr/local/bin/codeql"
  queries_path: "./queries/custom"
  database_path: "./.mcp-scan/codeql-dbs"

Requisitos:

CodeQL CLI instalado
Packs de queries disponibles

Configuracion LSP¶

Habilita integracion con Language Server Protocol.

lsp:
  enabled: false           # Activar/desactivar
  servers:                 # Configuracion por lenguaje
    python:
      command: "pyright-langserver"
      args: ["--stdio"]
    typescript:
      command: "typescript-language-server"
      args: ["--stdio"]

Campo	Tipo	Default	Descripcion
`enabled`	bool	`false`	Activar LSP
`servers`	map	`{}`	Servidores por lenguaje

Servidores LSP Recomendados¶

Lenguaje	Servidor	Instalacion
Python	Pyright	`npm install -g pyright`
TypeScript	ts-server	`npm install -g typescript-language-server`
JavaScript	ts-server	Mismo que TypeScript

Ejemplos Completos¶

Configuracion para Desarrollo¶

# .mcp-scan.yaml - Desarrollo

include:
  - "**/*.py"
  - "**/*.ts"
  - "**/*.js"

exclude:
  - "**/node_modules/**"
  - "**/venv/**"
  - "**/tests/**"
  - "**/__pycache__/**"

scan:
  mode: fast
  timeout: 2m
  fail_on: ""  # No falla, solo reporta

rules:
  disabled:
    - "MCP-N001"  # Lockfile en desarrollo
  severity_overrides: {}
  custom: []

allowlist:
  hosts:
    - "localhost"
    - "127.0.0.1"
    - "*.local"
  url_schemes:
    - "https"
    - "http"  # OK en desarrollo

output:
  redact_snippets: false

llm:
  enabled: false  # Desactivado en desarrollo

ml:
  enabled: true
  confidence_threshold: 0.6  # Mas hallazgos

Configuracion para CI/CD¶

# .mcp-scan.yaml - CI/CD

include:
  - "src/**/*.py"
  - "src/**/*.ts"
  - "src/**/*.js"

exclude:
  - "**/node_modules/**"
  - "**/venv/**"
  - "**/tests/**"
  - "**/dist/**"

scan:
  mode: fast
  timeout: 5m
  fail_on: high
  workers: 4

rules:
  disabled: []
  severity_overrides:
    MCP-E001: critical  # Secretos siempre criticos
  custom: []

allowlist:
  hosts:
    - "api.production.example.com"
    - "*.internal.example.net"
  url_schemes:
    - "https"
    - "wss"

output:
  redact_snippets: false

llm:
  enabled: false  # Muy lento para CI

ml:
  enabled: true
  confidence_threshold: 0.7

codeql:
  enabled: false  # Opcional, muy lento

Configuracion para Auditoria¶

# .mcp-scan.yaml - Auditoria completa

include:
  - "**/*.py"
  - "**/*.ts"
  - "**/*.tsx"
  - "**/*.js"
  - "**/*.jsx"
  - "**/*.go"

exclude:
  - "**/node_modules/**"
  - "**/vendor/**"

scan:
  mode: deep
  timeout: 1h
  fail_on: medium
  workers: 8

rules:
  disabled: []
  severity_overrides:
    MCP-E001: critical
    MCP-E002: critical
    MCP-E005: critical
  custom:
    - id: "AUDIT-CUSTOM-001"
      pattern: "# TODO.*security"
      severity: info
      confidence: high
      class: "info"
      description: "Pendiente de seguridad detectado"

allowlist:
  hosts:
    - "api.production.example.com"
  url_schemes:
    - "https"

output:
  redact_snippets: true  # Confidencialidad

llm:
  enabled: true
  base_url: "http://localhost:11434"
  model: "llama3.2:8b"  # Modelo mas grande
  threshold: 0.8
  max_length: 5000

ml:
  enabled: true
  confidence_threshold: 0.8

codeql:
  enabled: true
  database_path: "./.audit/codeql"

Configuracion Minima¶

# .mcp-scan.yaml - Minimo

scan:
  mode: fast
  fail_on: critical

exclude:
  - "**/node_modules/**"
  - "**/venv/**"

Anterior: Comandos CLI | Siguiente: Modos de Analisis