mcp-shodan

Servidor MCP de Shodan

Un servidor de Protocolo de Contexto de Modelo (MCP) para consultar la API y la CVEDB de Shodan . Este servidor proporciona acceso completo a los servicios de inteligencia y seguridad de red de Shodan, incluyendo reconocimiento de IP, operaciones DNS, rastreo de vulnerabilidades y descubrimiento de dispositivos. Todas las herramientas proporcionan resultados estructurados y formateados para facilitar el análisis y la integración.

Inicio rápido (recomendado)

Instalación mediante herrería

Para instalar Shodan Server para Claude Desktop automáticamente a través de Smithery :

Instalación manual

1. Instalar el servidor globalmente a través de npm:

2. Agregue a su archivo de configuración de Claude Desktop:

Ubicación del archivo de configuración:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Ventanas: %APPDATA%\Claude\claude_desktop_config.json

3. Reiniciar Claude Desktop

Configuración alternativa (de la fuente)

Si prefiere ejecutar desde la fuente o necesita modificar el código:

1. Clonar y construir:

2. Añade a tu configuración de Claude Desktop:

Características

• Reconocimiento de red : consulta información detallada sobre direcciones IP, incluidos puertos abiertos, servicios y vulnerabilidades
• Operaciones de DNS : búsquedas DNS directas e inversas para dominios y direcciones IP
• Inteligencia de vulnerabilidades : acceso a la CVEDB de Shodan para obtener información detallada sobre vulnerabilidades, búsquedas de CPE y seguimiento de CVE específicos del producto.
• Descubrimiento de dispositivos : busque en la base de datos de Shodan de dispositivos conectados a Internet con filtrado avanzado

Herramientas

1. Herramienta de búsqueda de IP

• Nombre: ip_lookup
• Descripción: Recupere información completa sobre una dirección IP, incluida la geolocalización, los puertos abiertos, los servicios en ejecución, los certificados SSL, los nombres de host y los detalles del proveedor de la nube si están disponibles.
• Parámetros:
  • ip (obligatorio): dirección IP a buscar
• Devoluciones:
  • Información IP (dirección, organización, ISP, ASN)
  • Ubicación (país, ciudad, coordenadas)
  • Servicios (puertos, protocolos, banners)
  • Detalles del proveedor de la nube (si están disponibles)
  • Nombres de host y dominios asociados
  • Etiquetas

2. Herramienta de búsqueda Shodan

• Nombre: shodan_search
• Descripción: Busca en la base de datos de dispositivos conectados a Internet de Shodan
• Parámetros:
  • query (obligatoria): consulta de búsqueda de Shodan
  • max_results (opcional, predeterminado: 10): Número de resultados a devolver
• Devoluciones:
  • Resumen de búsqueda con resultados totales
  • Estadísticas de distribución por país
  • Información detallada del dispositivo que incluye:
    • Información básica (IP, organización, ISP)
    • Datos de ubicación
    • Detalles del servicio
    • Información del servidor web
    • Nombres de host y dominios asociados

3. Herramienta de búsqueda de CVE

• Nombre: cve_lookup
• Descripción: Consulta información detallada sobre vulnerabilidades de la CVEDB de Shodan
• Parámetros:
  • cve (obligatorio): identificador CVE en formato CVE-AAAA-NNNNN (p. ej., CVE-2021-44228)
• Devoluciones:
  • Información básica (ID, fecha de publicación, resumen)
  • Puntuaciones de gravedad:
    • CVSS v2 y v3 con niveles de gravedad
    • Probabilidad y clasificación EPSS
  • Evaluación de impacto:
    • Estado de KEV
    • Mitigaciones propuestas
    • Asociaciones de ransomware
  • Productos afectados (CPE)
  • Referencias

4. Herramienta de búsqueda de DNS

• Nombre: dns_lookup
• Descripción: Resolver nombres de dominio a direcciones IP utilizando el servicio DNS de Shodan
• Parámetros:
  • hostnames (obligatorio): Matriz de nombres de host para resolver
• Devoluciones:
  • Resoluciones DNS que asignan nombres de host a IP
  • Resumen de búsquedas totales y nombres de host consultados

5. Herramienta de búsqueda inversa de DNS

• Nombre: reverse_dns_lookup
• Descripción: Realizar búsquedas DNS inversas para encontrar nombres de host asociados con direcciones IP
• Parámetros:
  • ips (obligatorio): Matriz de direcciones IP para buscar
• Devoluciones:
  • Resoluciones DNS inversas que asignan IP a nombres de host
  • Resumen de búsquedas totales y resultados

6. Herramienta de búsqueda de CPE

• Nombre: cpe_lookup
• Descripción: Busque entradas de Enumeración de plataforma común (CPE) por nombre de producto
• Parámetros:
  • product (obligatorio): Nombre del producto a buscar
  • count (opcional, predeterminado: falso): si es verdadero, devuelve solo el recuento de CPE coincidentes
  • skip (opcional, predeterminado: 0): Número de CPE a omitir (para paginación)
  • limit (opcional, predeterminado: 1000): número máximo de CPE a devolver
• Devoluciones:
  • Cuando el recuento es verdadero: Número total de CPE coincidentes
  • Cuando el recuento es falso: Lista de CPE con detalles de paginación

7. Herramienta de CVEs por producto

• Nombre: cves_by_product
• Descripción: Búsqueda de vulnerabilidades que afecten a productos o CPE específicos
• Parámetros:
  • cpe23 (opcional): identificador CPE 2.3 (formato: cpe:2.3:parte:proveedor:producto:versión)
  • product (opcional): Nombre del producto en el que se buscarán CVE
  • count (opcional, valor predeterminado: falso): si es verdadero, devuelve solo el recuento de CVE coincidentes
  • is_kev (opcional, valor predeterminado: falso): si es verdadero, devuelve solo CVE con el indicador KEV establecido
  • sort_by_epss (opcional, predeterminado: falso): si es verdadero, ordena los CVE por puntuación EPSS
  • skip (opcional, predeterminado: 0): Número de CVE a omitir (para paginación)
  • limit (opcional, predeterminado: 1000): número máximo de CVE a devolver
  • start_date (opcional): Fecha de inicio para filtrar CVE (formato: AAAA-MM-DDTHH:MM:SS)
  • end_date (opcional): Fecha de finalización para filtrar CVE (formato: AAAA-MM-DDTHH:MM:SS)
• Notas:
  • Debe proporcionar cpe23 o producto, pero no ambos
  • El filtrado de fechas utiliza la hora de publicación de los CVE
• Devoluciones:
  • Información de la consulta
  • Resumen de resultados con detalles de paginación
  • Información detallada sobre vulnerabilidades que incluye:
    • Información básica
    • Puntuaciones de gravedad
    • Evaluaciones de impacto
    • Referencias

Requisitos

• Node.js (v18 o posterior)
• Una clave API de Shodan válida

Solución de problemas

Problemas con la clave API

Si ve errores relacionados con la clave API (por ejemplo, "La solicitud falló con el código de estado 401"):

1. Verifique su clave API:
   • Debe ser una clave API de Shodan válida desde la configuración de su cuenta
   • Asegúrese de que la clave tenga suficientes créditos/permisos para la operación
   • Compruebe si hay espacios adicionales o comillas alrededor de la clave en la configuración
   • Verifique que la clave esté configurada correctamente en la variable de entorno SHODAN_API_KEY
2. Códigos de error comunes:
   • 401 No autorizado: Clave API no válida o autenticación faltante
   • 402 Pago requerido: créditos fuera de consulta
   • 429 Demasiadas solicitudes: Límite de velocidad excedido
3. Pasos de configuración: a. Obtén tu clave API de la cuenta de Shodan. b. Añádela a tu archivo de configuración.
   { "mcpServers": { "shodan": { "command": "mcp-shodan", "env": { "SHODAN_API_KEY": "your-actual-api-key-here" } } } }
   c. Guarde el archivo de configuración. d. Reinicie Claude Desktop.
4. Probando su clave:
   • Pruebe primero una consulta sencilla (por ejemplo, dns_lookup para "google.com")
   • Consulta el panel de tu cuenta de Shodan para conocer el estado del crédito
   • Verifique que la clave funcione directamente con curl:
     curl "https://api.shodan.io/dns/resolve?hostnames=google.com&key=your-api-key"

Problemas de carga del módulo

Si ve errores de carga del módulo:

1. Para la instalación global: utilice la configuración simple que se muestra en Inicio rápido
2. Para la instalación de origen: asegúrese de estar utilizando Node.js v18 o posterior

Desarrollo

Para ejecutar en modo de desarrollo con recarga en caliente:

Manejo de errores

El servidor incluye un manejo integral de errores para:

• Claves API no válidas
• Limitación de velocidad
• Errores de red
• Parámetros de entrada no válidos
• Formatos CVE no válidos
• Parámetros de búsqueda de CPE no válidos
• Formatos de fecha no válidos
• Validación de parámetros mutuamente excluyentes

Historial de versiones

• v1.0.12: Se agregó búsqueda DNS inversa y se mejoró el formato de salida
• v1.0.7: Se agregó la funcionalidad de búsqueda de CVE por producto y se cambió el nombre de la herramienta de vulnerabilidades a cve_lookup
• v1.0.6: Se agregó integración con CVEDB para mejorar las búsquedas de CVE y la funcionalidad de búsqueda de CPE
• v1.0.0: Versión inicial con funcionalidad principal

Contribuyendo

1. Bifurcar el repositorio
2. Crear una rama de características ( git checkout -b feature/amazing-feature )
3. Confirme sus cambios ( git commit -m 'Add amazing feature' )
4. Empujar a la rama ( git push origin feature/amazing-feature )
5. Abrir una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.