Enrichment MCP Server

Enrichment MCP Server

Este projeto é um servidor Model Context Protocol (MCP) para realizar enriquecimento dado um observável fornecido. A combinação de serviços configurados e o(s) observável(eis) fornecido(s) determinará quais serviços de enriquecimento serão chamados.

Esta ferramenta fornece uma implementação simples de servidor MCP para realizar enriquecimento de terceiros usando serviços comuns (ex.: VirusTotal, Hybrid Analysis, etc.) utilizando o pacote Python security-cli para realizar enriquecimento/comunicação com diferentes serviços.

Servidor MCP

Esta implementação do enrichment-mcp servidor MCP expõe as seguintes ferramentas.

• lookup-observable - Um endpoint genérico que examina e roteia o observável fornecido para a ferramenta correta.

Serviços Suportados

Os seguintes serviços e tipos de observáveis são atualmente suportados:

Se você tiver alguma sugestão ou acreditar que outro serviço deve ser implementado, por favor crie uma issue ou pull request!

Nome	Requer Chave de API	Suporta IP	Suporta Domínio	Suporta URL	Suporta Email
VirusTotal	Sim	Sim	Sim	Sim	Não
HybridAnalysis	Sim	Sim	Sim	Sim	Não
AlienVault	Sim	Sim	Sim	Sim	Não
Shodan	Sim	Sim	Sim	Sim	Não
Urlscan.io	Sim	Sim	Sim	Sim	Não
AbuseIPDB	Sim	Sim	Não	Não	Não
HaveIBeenPwned	Sim	Não	Não	Não	Sim

Requisitos

Este serviço MCP usa security-cli e um arquivo personalizado config.yaml.example para determinar quais serviços de enriquecimento de terceiros são suportados para consultas de observáveis.

A maneira mais fácil de executar isso em um mac/sistema local é:

uv run --env-file .env server.py

Isso requer que você use o modelo fornecido .env.example e crie um novo arquivo .env com seus segredos.

NOTA: Por favor, revise a documentação do security-cli para informações sobre como configurar diferentes serviços. O padrão será suficiente para a maioria dos casos de uso.

Variáveis de Ambiente

NOTA: É altamente recomendável definir segredos como variáveis de ambiente ao implementar este serviço. Pare de armazenar segredos, seu bobo.

Para que o pacote security-cli descubra essas variáveis, elas devem estar em um formato específico. Abaixo está a lista de variáveis atualmente suportadas:

• ENRICHMENT_MCP_VIRUSTOTAL_KEY
• ENRICHMENT_MCP_HYBRIDANALYSIS_KEY
• ENRICHMENT_MCP_ALIENVAULT_KEY
• ENRICHMENT_MCP_SHODAN_KEY
• ENRICHMENT_MCP_URLSCAN_KEY
• ENRICHMENT_MCP_ABUSEIPDB_KEY
• ENRICHMENT_MCP_HIBP_KEY

Configuração de Enriquecimentos

Cada serviço de enriquecimento é definido no arquivo de configuração securiy-cli. Além disso, eu separei os diferentes tipos de enriquecimento que podem ser realizados. Isso significa que, na implementação atual, temos um único tipo de ação chamado enrich, mas no futuro isso pode ser expandido para coisas como scans ou queries, etc.

Abaixo dessas ações de alto nível, listamos o tipo de observável seguido por uma lista de serviços que suportam esse tipo. Os tipos de observáveis atualmente suportados são:

• ipaddress - endereços ipv4
• domain - Um domínio ou netloc
• url - Uma URL totalmente qualificada com esquema, etc.
• email - Um endereço de email padrão

Também suportamos esses tipos, mas eles não estão implementados atualmente:

• md5 - Um hash MD5 de arquivo
• sha1 - Um hash SHA1 de arquivo
• sha256 - Um hash SHA256 de arquivo

Cada serviço deve ter um name e um template. O campo apikey pode ser fornecido, mas recomendamos usar variáveis de ambiente.

Modelos de Prompt

Cada serviço e tipo de observável pode ter seu próprio modelo de resposta. Eles residem no diretório security-cli templates e espera-se que todos os modelos existam aqui.

Cada serviço definido tem um modelo de prompt usando modelos jinja2. Você pode modificá-los conforme necessário, mas o formato do nome do arquivo deve permanecer o mesmo.

Esses arquivos têm o seguinte padrão de nome de arquivo.

{service.name}.{enrichment.type}.jinja2

Garanta que o objeto de resposta tenha os campos corretos no próprio modelo, caso contrário você receberá um erro.

Abaixo está um exemplo de saída para um prompt de Enrich this IP 91.195.240.94 com alguns erros misturados:

{
    "virustotal": "error occurred looking up ip 91.195.240.94 in virustotal",
    "alienvault": "Service: alienvault\nIPAddress: \nReputation Score: 0\nTotal Votes: ",
    "shodan": "Service: shodan\nIPAddress: 91.195.240.94\nLast Analysis Results: 2025-04-25T21:02:52.644602\n\nTags\n\n\nAdditional information includes:\n\n* Latitude: 48.13743\n* Longitude: 11.57549\n* ASN: AS47846\n* Domains: ["servervps.net"]",
    "hybridanalysis": "error occurred looking up ip 91.195.240.94 in hybridanalysis",
    "urlscan": "Service: urlscan\nResult: https://urlscan.io/api/v1/result/01966efe-c8fa-74a4-bfc0-1ed479838e85/\n\nStats\n\n* uniqIPs - 6\n\n* uniqCountries - 2\n\n* dataLength - 432561\n\n* encodedDataLength - 218606\n\n* requests - 14\n\n\nPage\n* country - DE\n* server - Parking/1.0\n* ip - 91.195.240.94\n* mimeType - text/html\n* title - wearab.org\xa0-\xa0Informationen zum Thema wearab.\n* url - https://login.wearab.org/\n* tlsValidDays - 364\n* tlsAgeDays - 0\n* tlsValidFrom - 2025-04-25T00:00:00.000Z\n* domain - login.wearab.org\n* apexDomain - wearab.org\n* asnname - SEDO-AS SEDO GmbH, DE\n* asn - AS47846\n* tlsIssuer - Encryption Everywhere DV TLS CA - G2\n* status - 200\n",
    "abuseipdb": "Service: abuseripdb\nIPAddress: 91.195.240.94\nLast Analysis Result: 2025-03-30T14:04:45+00:00\nScore: 7\nUsage: Data Center/Web Hosting/Transit\nIs Tor: False\nIs Whitelisted: False\nISP: Sedo Domain Parking"
}

Uso do Servidor MCP

Para usar um servidor pré-construído, instruções daqui: https://modelcontextprotocol.io/quickstart/user

• Baixe o Claude for Desktop
• Instale o uv

curl -LsSf https://astral.sh/uv/install.sh | sh

• Baixe este repositório e adicione à configuração do Claude for Desktop
  • Claude for Desktop > Settings > Developer > Edit Config

Você pode copiar o arquivo fornecido .desktop_config.example.json

Se quiser criar você mesmo, estes são os caminhos para o Claude Desktop.

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

Abra o arquivo de configuração em qualquer editor de texto. Substitua o conteúdo do arquivo por isto:

{
	"mcpServers": {
		"enrichment-mcp": {
			"command": "/ABSOLUTE/PATH/TO/PARENT/FOLDER/uv",
			"args": [
				"--directory",
				"/ABSOLUTE/PATH/TO/CLONED/REPOSITORY/enrichment-mcp",
				"run",
				"server.py"
			]
		}
    }
}

4. Reinicie o Claude for Desktop

Você agora deve ver dois ícones na barra de chat, um martelo que mostra as ferramentas disponíveis e um ícone de conexão que mostra o prompt definido e a entrada necessária.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar pull requests.