Guia de Despliegue en Produccion¶

Esta guia cubre el despliegue de mcp-scan en entornos de produccion con requisitos de alta disponibilidad y seguridad.

Vista General de la Arquitectura¶

┌─────────────────────────────────────────────────────────────┐
│                    Stack de Produccion                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │  mcp-scan    │    │   Ollama     │    │   CodeQL     │  │
│  │  (escaner)   │───▶│   (local)    │    │   (binario)  │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
│         │                                       │           │
│         │            ┌──────────────┐           │           │
│         └───────────▶│  Servidores  │◀──────────┘           │
│                      │  LSP         │                       │
│                      │  (pyright,   │                       │
│                      │   gopls)     │                       │
│                      └──────────────┘                       │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                  APIs Externas                        │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐           │   │
│  │  │ Claude   │  │ OpenAI   │  │ LLM      │           │   │
│  │  │ API      │  │ API      │  │ Custom   │           │   │
│  │  └──────────┘  └──────────┘  └──────────┘           │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Requisitos del Sistema¶

Requisitos Minimos¶

Componente	Requisito
CPU	4 nucleos
RAM	8 GB
Disco	20 GB SSD
SO	Linux (Ubuntu 22.04+, RHEL 8+)

Instalacion¶

1. Instalar mcp-scan¶

# Desde codigo fuente
git clone https://github.com/mcphub/mcp-scan.git
cd mcp-scan
make build
sudo mv bin/mcp-scan /usr/local/bin/

# O mediante go install
go install github.com/mcphub/mcp-scan/cmd/mcp-scan@latest

2. Instalar CodeQL¶

# Descargar CodeQL CLI
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"

# Instalar
sudo tar xzf codeql.tar.gz -C /opt/
sudo ln -sf /opt/codeql/codeql /usr/local/bin/codeql

# Descargar paquetes de lenguaje
codeql pack download codeql/python-queries
codeql pack download codeql/javascript-queries
codeql pack download codeql/go-queries

# Verificar
codeql version
codeql resolve languages

3. Instalar Servidores de Lenguaje¶

# Servidores de lenguaje Node.js
npm install -g pyright typescript typescript-language-server

# Servidor de lenguaje Python (alternativa)
pip3 install python-lsp-server[all]

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

# Verificar
./scripts/check-lsp.sh

4. Instalar Ollama (Opcional)¶

# Instalar Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Configurar servicio systemd
sudo systemctl enable ollama
sudo systemctl start ollama

# Descargar modelos
ollama pull llama3.2:3b

# Verificar
curl http://localhost:11434/api/tags

Configuracion¶

Configuracion del Sistema¶

Crear /etc/mcp-scan/config.yaml:

version: "1"

# Configuracion de analisis
mode: deep
timeout: 30m
workers: 0  # Auto-detectar
fail_on: high

# Patrones de archivos
include:
  - "**/*.py"
  - "**/*.ts"
  - "**/*.js"
  - "**/*.go"

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

# Configuracion LLM
llm:
  enabled: true
  provider: ""  # Auto-detectar
  url: "http://localhost:11434"
  threshold: 0.7
  timeout: "60s"
  max_length: 5000

# Configuracion CodeQL
codeql:
  enabled: true
  path: "/usr/local/bin/codeql"
  timeout: "30m"
  queries_dir: "/opt/mcp-scan/codeql-queries/mcp"
  min_severity: 5.0
  languages:
    - python
    - javascript
    - go

# Configuracion LSP
lsp:
  enabled: true
  languages:
    - python
    - typescript
    - go

# Configuracion ML
ml:
  enabled: true
  threshold: 0.3
  model_path: "/opt/mcp-scan/ml_weights.json"

# Configuracion de salida
output:
  format: sarif
  include_trace: true
  redact_snippets: false

Variables de Entorno¶

Crear /etc/mcp-scan/env:

# Claves API de LLM
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

# Sobreescribir valores por defecto
MCP_SCAN_LLM_PROVIDER=claude
MCP_SCAN_CODEQL_TIMEOUT=1h

Servicio Systemd¶

Crear /etc/systemd/system/mcp-scan.service:

[Unit]
Description=MCP-SCAN Escaner de Seguridad
After=network.target ollama.service

[Service]
Type=oneshot
EnvironmentFile=/etc/mcp-scan/env
ExecStart=/usr/local/bin/mcp-scan scan /var/lib/mcp-scan/workspace --config /etc/mcp-scan/config.yaml
WorkingDirectory=/var/lib/mcp-scan
User=mcp-scan
Group=mcp-scan

# Hardening de seguridad
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/mcp-scan
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Hardening de Seguridad¶

Gestion de Claves API¶

# Usar administrador de secretos
export ANTHROPIC_API_KEY=$(aws secretsmanager get-secret-value \
  --secret-id mcp-scan/anthropic-key \
  --query SecretString --output text)

# O usar HashiCorp Vault
export ANTHROPIC_API_KEY=$(vault kv get -field=api_key secret/mcp-scan/anthropic)

Seguridad de Red¶

# Restringir Ollama a localhost
# En /etc/ollama/config
OLLAMA_HOST=127.0.0.1:11434

# Reglas de firewall
sudo ufw allow from 127.0.0.1 to any port 11434
sudo ufw deny 11434

Permisos de Archivos¶

# Crear usuario de servicio
sudo useradd -r -s /bin/false mcp-scan

# Establecer propiedad
sudo chown -R mcp-scan:mcp-scan /var/lib/mcp-scan
sudo chown -R mcp-scan:mcp-scan /opt/mcp-scan

# Restringir archivo de configuracion
sudo chmod 600 /etc/mcp-scan/env
sudo chown root:mcp-scan /etc/mcp-scan/env

Alta Disponibilidad¶

Balanceo de Carga¶

Para escaneo a escala, desplegar multiples instancias detras de un balanceador de carga:

# docker-compose.ha.yml
version: '3.8'

services:
  scanner-1:
    image: mcp-scan:latest
    environment:
      - ANTHROPIC_API_KEY
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '4'
          memory: 8G

  ollama:
    image: ollama/ollama:latest
    deploy:
      replicas: 2
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

Cache¶

Habilitar cache de resultados para mejorar el rendimiento:

# En config.yaml
cache:
  enabled: true
  directory: /var/cache/mcp-scan
  ttl: 24h

Monitoreo¶

Metricas Prometheus¶

# prometheus.yml
scrape_configs:
  - job_name: 'mcp-scan'
    static_configs:
      - targets: ['localhost:9090']
    metrics_path: /metrics

Dashboard Grafana¶

Metricas clave a monitorear:

mcp_scan_duration_seconds - Duracion del escaneo
mcp_scan_findings_total - Total de hallazgos
mcp_scan_llm_requests_total - Llamadas a API de LLM
mcp_scan_llm_latency_seconds - Tiempo de respuesta del LLM
mcp_scan_errors_total - Cantidad de errores

Alertas¶

# alertmanager.yml
groups:
  - name: mcp-scan
    rules:
      - alert: HallazgoSeveridadAlta
        expr: mcp_scan_findings_total{severity="critical"} > 0
        labels:
          severity: critical
        annotations:
          summary: Vulnerabilidad critica detectada

      - alert: LatenciaLLMAlta
        expr: mcp_scan_llm_latency_seconds > 30
        labels:
          severity: warning
        annotations:
          summary: El tiempo de respuesta del LLM es alto

Respaldo y Recuperacion¶

Estrategia de Respaldo¶

# Respaldar modelo ML y configuracion
tar czf mcp-scan-backup.tar.gz \
  /etc/mcp-scan/ \
  /opt/mcp-scan/ml_weights.json \
  /opt/mcp-scan/codeql-queries/

# Almacenar en S3
aws s3 cp mcp-scan-backup.tar.gz s3://backups/mcp-scan/

Recuperacion¶

# Restaurar desde respaldo
aws s3 cp s3://backups/mcp-scan/mcp-scan-backup.tar.gz .
tar xzf mcp-scan-backup.tar.gz -C /

# Reiniciar servicios
sudo systemctl restart mcp-scan ollama

Solucion de Problemas¶

Problemas Comunes¶

Sin Memoria¶

# Aumentar limites de memoria
# En /etc/systemd/system/mcp-scan.service
MemoryMax=16G

Escaneos Lentos¶

# Reducir timeout de CodeQL
mcp-scan scan . --codeql-timeout 10m

# Limitar lenguajes
mcp-scan scan . --codeql-languages python

# Aumentar paralelismo
mcp-scan scan . --workers 8

Limitacion de Tasa del LLM¶

# Reducir umbral para evitar llamadas innecesarias
mcp-scan scan . --llm-threshold 0.9

# Usar Ollama local en lugar de la nube
mcp-scan scan . --llm-provider ollama

Modo Debug¶

# Habilitar logging verboso
mcp-scan scan . --verbose 2>&1 | tee scan.log

# Verificar componente especifico
MCP_SCAN_DEBUG=llm mcp-scan scan .
MCP_SCAN_DEBUG=codeql mcp-scan scan .

Mantenimiento¶

Tareas Regulares¶

Tarea	Frecuencia	Comando
Actualizar mcp-scan	Semanal	`go install github.com/mcphub/mcp-scan/cmd/mcp-scan@latest`
Actualizar CodeQL	Mensual	`codeql pack upgrade`
Re-entrenar modelo ML	Mensual	`python scripts/train_ml.py`
Limpiar cache	Semanal	`rm -rf /var/cache/mcp-scan/*`
Actualizar modelos Ollama	Mensual	`ollama pull llama3.2:3b`

Rotacion de Logs¶

# /etc/logrotate.d/mcp-scan
/var/log/mcp-scan/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
}

Componente	Requisito
CPU	8+ nucleos
RAM	32 GB
Disco	100 GB NVMe SSD
GPU	GPU NVIDIA (para Ollama local)
SO	Linux (Ubuntu 22.04 LTS)