Enrichment MCP Server

エンリッチメント MCP サーバー

このプロジェクトは、提供されたオブザーバブルに基づいてエンリッチメントを実行するための Model Context Protocol（MCP）サーバーです。設定されたサービスと提供されたオブザーバブルの組み合わせによって、呼び出すエンリッチメントサービスが決まります。

このツールは、security-cli Python パッケージを利用して、一般的なサービス（VirusTotal、Hybrid Analysis など）を通じたサードパーティーのエンリッチメントと各サービスとの通信を実行する、シンプルな MCP サーバー実装を提供します。

MCP サーバー

この enrichment-mcp MCP サーバー実装は、次のツールを公開します。

• lookup-observable - 指定されたオブザーバブルを調べ、適切なツールに振り分ける汎用エンドポイントです。

サポート対象のサービス

現在、次のサービスとオブザーバブルタイプがサポートされています。

別のサービスを実装してほしい場合や、提案がある場合は、イシューまたはプルリクエストを作成してください！

名前	API キーが必要	IP をサポート	ドメインをサポート	URL をサポート	メールをサポート
VirusTotal	はい	はい	はい	はい	いいえ
HybridAnalysis	はい	はい	はい	はい	いいえ
AlienVault	はい	はい	はい	はい	いいえ
Shodan	はい	はい	はい	はい	いいえ
Urlscan.io	はい	はい	はい	はい	いいえ
AbuseIPDB	はい	はい	いいえ	いいえ	いいえ
HaveIBeenPwned	はい	いいえ	いいえ	いいえ	はい

要件

この MCP サービスは security-cli と独自の config.yaml.example ファイルを使って、オブザーバブルの検索でサポートするサードパーティーのエンリッチメントサービスを決定します。

ローカルの Mac システムで実行する最も簡単な方法は次のとおりです。

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

用意されているテンプレート .env.example を使用し、シークレットを記載した新しい .env ファイルを作成する必要があります。

注意：各種サービスの設定方法については、security-cli のドキュメントを確認してください。 ほとんどのユースケースでは、デフォルト設定で十分です。

環境変数

注意：このサービスを実装する際は、シークレットを環境変数として設定することを強く推奨します。シークレットを保存するのはもうやめましょう。

security-cli パッケージがこれらの変数を検出するには、特定の形式にする必要があります。現在サポートされている変数は次のとおりです。

• 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

エンリッチメントの設定

各エンリッチメントサービスは securiy-cli の設定ファイルで定義します。また、実行可能なエンリッチメントの種類ごとに分けています。つまり、現在の実装では enrich という単一のアクションタイプがありますが、将来的には scans や queries などに拡張できます。

これらの上位アクションの下にオブザーバブルタイプと、そのタイプをサポートするサービスの一覧を記載します。現在サポートされているオブザーバブルタイプは次のとおりです。

• ipaddress - IPv4 アドレス
• domain - ドメインまたはネットロケーション
• url - スキームなどを含む完全修飾 URL
• email - 標準的なメールアドレス

次のタイプもサポートしていますが、現在は実装されていません。

• md5 - ファイルの MD5 ハッシュ
• sha1 - ファイルの SHA1 ハッシュ
• sha256 - ファイルの SHA256 ハッシュ

各サービスには name と template が必要です。apikey フィールドも指定できますが、環境変数の使用を推奨します。

プロンプトテンプレート

各サービスと監視対象の種類には、それぞれ独自の応答テンプレートを設定できます。これらは security-cli の テンプレート ディレクトリにあり、すべてのテンプレートをここに配置する必要があります。

定義されている各サービスには、jinja2 テンプレートを使ったプロンプトテンプレートがあります。必要に応じて変更できますが、ファイル名の形式は変更しないでください。

これらのファイル名は次のパターンに従います。

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

テンプレート自体に応答オブジェクトの正しいフィールドが含まれていることを確認してください。含まれていない場合、エラーが発生します。

以下は、いくつかのエラーを含む Enrich this IP 91.195.240.94 というプロンプトの出力例です。

{
    "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"
}

MCP サーバーの使用方法

ビルド済みサーバーの使用方法については、こちらの手順をご覧ください：https://modelcontextprotocol.io/quickstart/user

• Claude for Desktop をダウンロードします
• uv をインストールします

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

• このリポジトリをダウンロードし、Claude for Desktop の設定に追加します
  • Claude for Desktop > 設定 > 開発者 > 設定を編集

提供されている .desktop_config.example.json ファイルをコピーできます

自分で作成する場合は、Claude Desktop のパスを以下に示します。

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

テキストエディターで設定ファイルを開き、ファイルの内容を次のように置き換えます。

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

4. Claude for Desktop を再起動します

チャットバーに2つのアイコンが表示されます。利用可能なツールを表示するハンマーのアイコンと、定義済みのプロンプトおよび必要な入力を表示する接続アイコンです。

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。