Escáner de servidores MCP

Qué hace el escáner

El escáner MCP de ShieldAgent se conecta a cualquier servidor MCP (HTTP o proceso stdio local), enumera las definiciones de sus herramientas y ejecuta una batería de comprobaciones de seguridad en cuatro categorías: análisis de definición de herramientas, escaneo de CVEs en dependencias, inspección de flujos OAuth y revisión del manifiesto de cadena de suministro.

Los resultados se devuelven como un ScanReport estructurado con hallazgos agrupados por severidad, un resumen de hallazgos, la lista de herramientas enumeradas y un SBOM CycloneDX 1.5 opcional cuando hay metadatos de paquetes disponibles.

Ejecutar un escaneo

CLI

Instala el paquete del escáner y apúntalo a cualquier servidor MCP HTTP o local:

# Install from source
git clone https://github.com/shieldagent-io/shieldagent.git
cd shieldagent && pnpm install
npm install -g ./backend/apps/scanner

# Scan an HTTP MCP server
shieldagent-scan https://my-mcp-server.example.com

# Scan a local stdio server
shieldagent-scan stdio -- node ./dist/server.js

# Output as Markdown report to a file
shieldagent-scan --format markdown --output report.md https://my-mcp-server.example.com

# Output as SARIF (for GitHub Security tab / CI)
shieldagent-scan --format sarif -o results.sarif https://my-mcp-server.example.com

API REST

El escáner incluye un servidor REST Fastify para acceso programático. Inícialo con --serve y llama al endpoint de escaneo:

# Start the REST server on port 4500
shieldagent-scan --serve --port 4500

# Trigger a scan via the API
curl -s -X POST http://localhost:4500/api/v1/scan \
  -H 'Content-Type: application/json' \
  -d '{
    "target": {
      "type": "http",
      "url": "https://my-mcp-server.example.com"
    }
  }' | jq .

Panel de control

Navega a Escáner en la barra lateral del panel de ShieldAgent. Introduce la URL del servidor y haz clic en Ejecutar escaneo. El panel almacena el historial de escaneos y permite comparar resultados entre ejecuciones. Los hallazgos enlazan directamente con la pantalla de gestión de políticas relevante para acelerar la remediación.

Niveles de severidad

Cada hallazgo tiene uno de cinco niveles de severidad. El CLI finaliza con código 1 cuando hay hallazgos Críticos o Altos, y con código 0 en caso contrario.

Análisis de definición de herramientas

El escáner inspecciona cada definición de herramienta devuelta por tools/list en busca de tres clases de riesgo:

Formatos de salida

Integración CI/CD

Añade el escáner a tu flujo de trabajo de GitHub Actions para bloquear despliegues cuando se detecten hallazgos de alta severidad. La salida SARIF se integra con la pestaña de seguridad de GitHub para anotaciones en PRs:

# .github/workflows/mcp-scan.yml
name: MCP Security Scan

on: [push, pull_request]

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

      - name: Install ShieldAgent Scanner from source
        # @shieldagent/scanner not yet on npm — build from source
        run: |
          git clone https://github.com/shieldagent-io/shieldagent.git
          cd shieldagent && npm install -g pnpm
          pnpm install --frozen-lockfile
          npm install -g ./backend/apps/scanner

      - name: Scan MCP server
        run: |
          shieldagent-scan --format sarif -o results.sarif \
            ${{ secrets.MCP_SERVER_URL }}

      - name: Upload SARIF to GitHub Security
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

El código de salida 1 del escáner fallará el paso de CI automáticamente cuando existan hallazgos Críticos o Altos — sin configuración adicional.

Integración con el panel

El panel de ShieldAgent muestra los resultados del escáner junto con los datos de monitorización en tiempo de ejecución:

• Historial de escaneos— cada ejecución se almacena con marca de tiempo, objetivo, resumen de hallazgos e informe completo. Compara resultados antes y después de actualizar un servidor.
• Seguimiento de remediación— los hallazgos pueden reconocerse, asignarse o vincularse a reglas de políticas. Los hallazgos reconocidos se excluyen del recuento activo pero siguen siendo auditables.
• Atajos de política— los hallazgos Altos y Críticos en una herramienta específica enlazan directamente con la pantalla de gestión de políticas, prerrellenada con una regla de denegación para esa herramienta.
• Visor de SBOM— cuando se genera un SBOM CycloneDX, aparece en la vista de detalle del escaneo con una lista de componentes con búsqueda y referencias cruzadas de vulnerabilidades.

Referencia de la API del escáner

Endpoints

Cuerpo de la solicitud — POST /api/v1/scan

{
  "target": {
    "type": "http",
    "url": "https://my-mcp-server.example.com"
  }
}

Nota: los objetivos stdio son rechazados por la API REST por razones de seguridad. Usa el CLI para escanear procesos locales.

Respuesta — ScanReport

{
  "id": "3f2a1c4d-...",
  "target": { "type": "http", "url": "https://..." },
  "scannedAt": "2026-04-24T12:00:00.000Z",
  "durationMs": 843,
  "serverInfo": {
    "name": "my-mcp-server",
    "version": "1.2.0",
    "protocolVersion": "2024-11-05"
  },
  "tools": [...],
  "findings": [
    {
      "id": "a1b2c3d4-...",
      "category": "tool_analysis",
      "severity": "high",
      "title": "High-privilege tool \"execute_shell\" lacks input constraints",
      "description": "Tool execute_shell appears to execute shell commands but defines no input schema constraints.",
      "remediation": "Add a strict JSON Schema with an allowlist of permitted values.",
      "metadata": { "toolName": "execute_shell" }
    }
  ],
  "summary": { "critical": 0, "high": 1, "medium": 0, "low": 0, "info": 0, "total": 1 }
}

Categorías de hallazgos