Guia de Despliegue¶

Esta guia cubre el despliegue de mcp-scan con todos los detectores avanzados habilitados.

Inicio Rapido¶

1. Verificar Dependencias¶

./scripts/check-lsp.sh

2. Instalar Dependencias Faltantes¶

# Servidores de lenguaje
npm install -g pyright typescript typescript-language-server
go install golang.org/x/tools/gopls@latest

# CodeQL (macOS)
brew install codeql

# Dependencias de entrenamiento ML
pip install datasets scikit-learn numpy

3. Configurar Proveedor LLM¶

Elige una opcion:

# Opcion A: Ollama (local)
ollama serve &
ollama pull llama3.2:3b

# Opcion B: Claude
export ANTHROPIC_API_KEY=sk-ant-...

# Opcion C: OpenAI
export OPENAI_API_KEY=sk-...

4. Entrenar Modelo ML (Opcional)¶

python scripts/train_ml.py ml_weights.json

5. Ejecutar Escaneo¶

mcp-scan scan ./my-mcp-server --llm --ml --ml-model ml_weights.json

Despliegue con Docker¶

Usando Docker Compose¶

Crear docker-compose.yml:

version: '3.8'

services:
  mcp-scan:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - ./:/workspace
      - mcp-scan-cache:/root/.cache/mcp-scan
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - MCP_SCAN_LLM_URL=http://ollama:11434
    depends_on:
      - ollama

  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  lsp-servers:
    build:
      context: ./docker
      dockerfile: lsp.Dockerfile
    volumes:
      - ./:/workspace

volumes:
  ollama-data:
  mcp-scan-cache:

Construir y Ejecutar¶

# Construir imagenes
docker-compose build

# Iniciar servicios
docker-compose up -d

# Ejecutar escaneo
docker-compose exec mcp-scan mcp-scan scan /workspace --llm

Integracion CI/CD¶

GitHub Actions¶

name: Escaneo de Seguridad MCP

on:
  push:
    branches: [main]
  pull_request:

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configurar Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.22'

      - name: Instalar mcp-scan
        run: go install github.com/mcphub/mcp-scan/cmd/mcp-scan@latest

      - name: Ejecutar escaneo
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          mcp-scan scan . \
            --llm --llm-provider claude \
            --ml \
            --output sarif \
            --fail-on high \
            > results.sarif

      - name: Subir SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

GitLab CI¶

mcp-scan:
  image: golang:1.22
  stage: test
  script:
    - go install github.com/mcphub/mcp-scan/cmd/mcp-scan@latest
    - mcp-scan scan . --llm --ml --fail-on high
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Configuracion de Produccion¶

Configuracion Recomendada¶

Crear .mcp-scan.yaml:

version: "1"

mode: deep
timeout: 30m
fail_on: high
workers: 0  # Auto-detectar cantidad de CPUs

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

exclude:
  - "node_modules/**"
  - "venv/**"
  - ".venv/**"
  - "vendor/**"
  - "dist/**"
  - "build/**"
  - "**/*.test.*"
  - "**/*_test.*"

llm:
  enabled: true
  provider: "claude"  # O usar auto-deteccion
  model: "claude-3-haiku-20240307"
  threshold: 0.7
  timeout: "60s"
  max_length: 5000

codeql:
  enabled: true
  timeout: "30m"
  queries_dir: "./codeql-queries/mcp"
  min_severity: 5.0
  languages: ["python", "javascript", "go"]

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

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

output:
  format: sarif
  include_trace: true
  redact_snippets: false

Variables de Entorno¶

# Requerido para Claude
export ANTHROPIC_API_KEY=sk-ant-...

# Requerido para OpenAI
export OPENAI_API_KEY=sk-...

# Sobreescrituras opcionales
export MCP_SCAN_LLM_PROVIDER=claude
export MCP_SCAN_LLM_THRESHOLD=0.8
export MCP_SCAN_CODEQL_TIMEOUT=1h

Monitoreo y Observabilidad¶

Logging¶

mcp-scan genera logs estructurados:

# Logs JSON
mcp-scan scan . --llm 2>&1 | jq .

# Filtrar por nivel
mcp-scan scan . --llm 2>&1 | jq 'select(.level == "error")'

Metricas¶

Seguimiento de metricas de escaneo:

Metrica	Descripcion
`scan_duration_seconds`	Tiempo total de escaneo
`files_scanned`	Numero de archivos analizados
`findings_count`	Total de vulnerabilidades encontradas
`findings_by_severity`	Desglose por severidad
`llm_requests`	Llamadas a la API del LLM
`llm_latency_ms`	Tiempo de respuesta del LLM

Verificacion de Estado¶

# Verificar dependencias
./scripts/check-lsp.sh

# Verificar conectividad con LLM
curl -s http://localhost:11434/api/tags | jq .

# Prueba de escaneo
mcp-scan scan ./testdata/fixtures --llm --output json | jq '.summary'

Solucion de Problemas¶

LLM No Disponible¶

Error: LLM detector not enabled

Solucion:
1. Verificar que el proveedor esta ejecutandose: curl http://localhost:11434/api/tags
2. Verificar que la API key esta configurada: echo $ANTHROPIC_API_KEY
3. Verificar conectividad de red

Timeout de CodeQL¶

Error: CodeQL analysis timed out

Solucion:
1. Aumentar timeout: --codeql-timeout 1h
2. Limitar lenguajes: --codeql-languages python
3. Usar un codebase mas pequeno

Servidor LSP No Encontrado¶

Error: pyright-langserver not found

Solucion:
1. Instalar: npm install -g pyright
2. Verificar PATH: which pyright-langserver
3. Usar imagen Docker con servidores pre-instalados

Modelo ML No Encontrado¶

Error: failed to read model file

Solucion:
1. Entrenar modelo: python scripts/train_ml.py ml_weights.json
2. Verificar ruta: ls -la ml_weights.json
3. Usar ruta absoluta: --ml-model /path/to/ml_weights.json