Shodan

Consulte a API do Shodan para reconhecimento de rede, operações de DNS, rastreamento de vulnerabilidades e descoberta de dispositivos.

GitHub
165
Experimente este MCPPatrocinado

Documentação

Servidor MCP Shodan

smithery badge MCP Registry

Um servidor Model Context Protocol (MCP) para consultar a API Shodan e o Shodan CVEDB. Este servidor fornece acesso abrangente aos serviços de inteligência de rede e segurança da Shodan, incluindo reconhecimento de IP, operações de DNS, rastreamento de vulnerabilidades e descoberta de dispositivos. Todas as ferramentas fornecem saída formatada e estruturada para fácil análise e integração.

Início Rápido (Recomendado)

Instalação via Claude Code

claude mcp add --transport stdio --env SHODAN_API_KEY=your-shodan-api-key shodan -- npx -y @burtthecoder/mcp-shodan

Instalação via Codex CLI

codex mcp add shodan --env SHODAN_API_KEY=your-shodan-api-key -- npx -y @burtthecoder/mcp-shodan

Instalação via Gemini CLI

gemini mcp add -e SHODAN_API_KEY=your-shodan-api-key shodan npx -y @burtthecoder/mcp-shodan

Instalação via Smithery

Para instalar o Shodan Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @burtthecoder/mcp-shodan --client claude

Instalação Manual

  1. Instale o servidor globalmente via npm:
npm install -g @burtthecoder/mcp-shodan
  1. Adicione ao seu arquivo de configuração do Claude Desktop:
{
  "mcpServers": {
    "shodan": {
      "command": "mcp-shodan",
      "env": {
        "SHODAN_API_KEY": "your-shodan-api-key"
      }
    }
  }
}

Localização do arquivo de configuração:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  1. Reinicie o Claude Desktop

Configuração Alternativa (A partir do Código Fonte)

Se preferir executar a partir do código fonte ou precisar modificar o código:

  1. Clone e compile:
git clone https://github.com/BurtTheCoder/mcp-shodan.git
cd mcp-shodan
npm install
npm run build
  1. Adicione à sua configuração do Claude Desktop:
{
  "mcpServers": {
    "shodan": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-shodan/build/index.js"],
      "env": {
        "SHODAN_API_KEY": "your-shodan-api-key"
      }
    }
  }
}

Recursos

  • Reconhecimento de Rede: Consulte informações detalhadas sobre endereços IP, incluindo portas abertas, serviços e vulnerabilidades
  • Operações de DNS: Consultas de DNS direto e reverso para domínios e endereços IP
  • Inteligência de Vulnerabilidades: Acesso ao CVEDB da Shodan para informações detalhadas de vulnerabilidades, consultas de CPE e rastreamento de CVEs específicos de produtos
  • Descoberta de Dispositivos: Pesquise o banco de dados da Shodan de dispositivos conectados à internet com filtros avançados

Ferramentas

1. Ferramenta de Consulta de IP

  • Nome: ip_lookup
  • Descrição: Recupere informações abrangentes sobre um endereço IP, incluindo geolocalização, portas abertas, serviços em execução, certificados SSL, nomes de host e detalhes do provedor de nuvem, se disponíveis
  • Parâmetros:
    • ip (obrigatório): Endereço IP para consulta
  • Retorna:
    • Informações do IP (endereço, organização, ISP, ASN)
    • Localização (país, cidade, coordenadas)
    • Serviços (portas, protocolos, banners)
    • Detalhes do Provedor de Nuvem (se disponíveis)
    • Nomes de host e domínios associados
    • Tags

2. Ferramenta de Pesquisa Shodan

  • Nome: shodan_search
  • Descrição: Pesquise o banco de dados da Shodan de dispositivos conectados à internet
  • Parâmetros:
    • query (obrigatório): Consulta de pesquisa Shodan
    • max_results (opcional, padrão: 10): Número de resultados a retornar
  • Retorna:
    • Resumo da pesquisa com total de resultados
    • Estatísticas de distribuição por país
    • Informações detalhadas do dispositivo, incluindo:
      • Informações básicas (IP, organização, ISP)
      • Dados de localização
      • Detalhes do serviço
      • Informações do servidor web
      • Nomes de host e domínios associados

3. Ferramenta de Consulta de CVE

  • Nome: cve_lookup
  • Descrição: Consulte informações detalhadas de vulnerabilidades do CVEDB da Shodan
  • Parâmetros:
    • cve (obrigatório): Identificador CVE no formato CVE-AAAA-NNNNN (ex.: CVE-2021-44228)
  • Retorna:
    • Informações Básicas (ID, data de publicação, resumo)
    • Pontuações de Severidade:
      • CVSS v2 e v3 com níveis de severidade
      • Probabilidade e classificação EPSS
    • Avaliação de Impacto:
      • Status KEV
      • Mitigações propostas
      • Associações com ransomware
    • Produtos afetados (CPEs)
    • Referências

4. Ferramenta de Consulta de DNS

  • Nome: dns_lookup
  • Descrição: Resolva nomes de domínio para endereços IP usando o serviço DNS da Shodan
  • Parâmetros:
    • hostnames (obrigatório): Matriz de nomes de host para resolver
  • Retorna:
    • Resoluções de DNS mapeando nomes de host para IPs
    • Resumo do total de consultas e nomes de host consultados

5. Ferramenta de Consulta de DNS Reversa

  • Nome: reverse_dns_lookup
  • Descrição: Execute consultas de DNS reverso para encontrar nomes de host associados a endereços IP
  • Parâmetros:
    • ips (obrigatório): Matriz de endereços IP para consulta
  • Retorna:
    • Resoluções de DNS reverso mapeando IPs para nomes de host
    • Resumo do total de consultas e resultados

6. Ferramenta de Consulta de CPE

  • Nome: cpe_lookup
  • Descrição: Pesquise entradas de Common Platform Enumeration (CPE) por nome de produto
  • Parâmetros:
    • product (obrigatório): Nome do produto a pesquisar
    • count (opcional, padrão: false): Se verdadeiro, retorna apenas a contagem de CPEs correspondentes
    • skip (opcional, padrão: 0): Número de CPEs a pular (para paginação)
    • limit (opcional, padrão: 1000): Número máximo de CPEs a retornar
  • Retorna:
    • Quando count é verdadeiro: Número total de CPEs correspondentes
    • Quando count é falso: Lista de CPEs com detalhes de paginação

7. Ferramenta de CVEs por Produto

  • Nome: cves_by_product
  • Descrição: Pesquise vulnerabilidades que afetam produtos ou CPEs específicos
  • Parâmetros:
    • cpe23 (opcional): Identificador CPE 2.3 (formato: cpe:2.3:parte:fornecedor:produto:versão)
    • product (opcional): Nome do produto para pesquisar CVEs
    • count (opcional, padrão: false): Se verdadeiro, retorna apenas a contagem de CVEs correspondentes
    • is_kev (opcional, padrão: false): Se verdadeiro, retorna apenas CVEs com o sinalizador KEV definido
    • sort_by_epss (opcional, padrão: false): Se verdadeiro, ordena CVEs pela pontuação EPSS
    • skip (opcional, padrão: 0): Número de CVEs a pular (para paginação)
    • limit (opcional, padrão: 1000): Número máximo de CVEs a retornar
    • start_date (opcional): Data de início para filtrar CVEs (formato: AAAA-MM-DDTHH:MM:SS)
    • end_date (opcional): Data de término para filtrar CVEs (formato: AAAA-MM-DDTHH:MM:SS)
  • Observações:
    • Deve fornecer cpe23 ou produto, mas não ambos
    • A filtragem por data usa o horário de publicação dos CVEs
  • Retorna:
    • Informações da consulta
    • Resumo dos resultados com detalhes de paginação
    • Informações detalhadas de vulnerabilidades, incluindo:
      • Informações básicas
      • Pontuações de severidade
      • Avaliações de impacto
      • Referências

Requisitos

Solução de Problemas

Problemas com a Chave de API

Se você vir erros relacionados à chave de API (ex.: "Request failed with status code 401"):

  1. Verifique sua chave de API:

    • Deve ser uma chave de API Shodan válida das suas configurações de conta
    • Certifique-se de que a chave tenha créditos/permissões suficientes para a operação
    • Verifique se há espaços extras ou aspas ao redor da chave na configuração
    • Verifique se a chave está corretamente definida na variável de ambiente SHODAN_API_KEY

  2. Códigos de Erro Comuns:

    • 401 Não Autorizado: Chave de API inválida ou autenticação ausente
    • 402 Pagamento Necessário: Sem créditos de consulta
    • 429 Muitas Solicitações: Limite de taxa excedido

  3. Etapas de Configuração: a. Obtenha sua chave de API na Conta Shodan b. Adicione-a ao seu arquivo de configuração:

    {
  "mcpServers": {
    "shodan": {
      "command": "mcp-shodan",
      "env": {
        "SHODAN_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

    c. Salve o arquivo de configuração d. Reinicie o Claude Desktop

  4. Testando Sua Chave:

    • Tente uma consulta simples primeiro (ex.: dns_lookup para "google.com")
    • Verifique seu painel da conta Shodan para o status de créditos
    • Verifique se a chave funciona diretamente com curl: 
      curl "https://api.shodan.io/dns/resolve?hostnames=google.com&key=your-api-key"

Problemas de Carregamento de Módulos

Se você vir erros de carregamento de módulos:

  1. Para instalação global: Use a configuração simples mostrada no Início Rápido
  2. Para instalação a partir do código fonte: Certifique-se de estar usando Node.js v18 ou posterior

Desenvolvimento

Compile o projeto:

npm install
npm run build

Teste interativamente com a ferramenta de desenvolvimento integrada do FastMCP:

npx fastmcp dev build/index.js

Tratamento de Erros

O servidor inclui tratamento abrangente de erros para:

  • Chaves de API inválidas
  • Limitação de taxa
  • Erros de rede
  • Parâmetros de entrada inválidos
  • Formatos de CVE inválidos
  • Parâmetros de consulta de CPE inválidos
  • Formatos de data inválidos
  • Validação de parâmetros mutuamente exclusivos

Histórico de Versões

  • v1.0.22: Publicado no Registro MCP oficial — adicionado manifesto server.json, suporte de instalação via CLI para Claude Code, Codex e Gemini CLI
  • v1.1.0: Migrado de @modelcontextprotocol/sdk bruto para FastMCP — arquivos de ferramentas modulares, validação automática de esquema, tratamento de erros simplificado
  • v1.0.12: Adicionada consulta de DNS reverso e melhorada a formatação da saída
  • v1.0.7: Adicionada funcionalidade de pesquisa de CVEs por Produto e renomeada a ferramenta de vulnerabilidades para cve_lookup
  • v1.0.6: Adicionada integração com CVEDB para consultas aprimoradas de CVE e funcionalidade de pesquisa de CPE
  • v1.0.0: Lançamento inicial com funcionalidade principal

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add amazing feature')
  4. Envie para o branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.