강화 MCP 서버

제공된 관찰 가능 항목을 기반으로 강화(enrichment)를 수행하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 구성된 서비스와 제공된 관찰 가능 항목의 조합에 따라 활용할 강화 서비스가 결정됩니다.

이 도구는 일반적인 서비스(예: VirusTotal, Hybrid Analysis 등)를 사용하여 타사 강화를 수행하는 간단한 구현을 제공합니다.

이 프로젝트는 어떠한 프로덕션 환경에서도 사용되지 않았습니다.

특징

이 enrichment-mcp MCP 서버 구현은 다음 도구를 제공합니다.

observable-lookup - 주어진 관찰 가능 항목을 조사하여 올바른 도구로 라우팅하는 일반적인 엔드포인트입니다.
lookup-ipaddress - 주어진 IPv4 주소에 대한 보강을 수행합니다.
lookup-domain - 주어진 도메인 이름에 대한 보강을 수행합니다.
lookup-url - 주어진 URL(그리고 어떤 경우에는 도메인 이름)에 대한 보강 작업을 수행합니다.
lookup-email - 주어진 이메일 주소에 대한 보강 작업을 수행합니다.

확인된 관찰 가능 유형에 문제가 발생하면 문제를 생성해 주시거나 현재 구현된 정규식 패턴을 업데이트해 드리겠습니다.

지원 서비스

현재 지원되는 서비스와 관찰 가능한 유형은 다음과 같습니다.

제안할 사항이 있거나 다른 서비스를 구현해야 한다고 생각하시는 경우, 이슈를 생성하거나 풀 리퀘스트를 제출해 주세요!

이름	API 키가 필요합니다	IP 지원	도메인 지원	URL 지원	이메일 지원
바이러스토탈	예	예	예	예	아니요
하이브리드 분석	예	예	예	예	아니요
에일리언볼트	예	예	예	예	아니요
쇼단	예	예	예	예	아니요
Urlscan.io	예	예	예	예	아니요
IPDB 남용	예	예	아니요	아니요	아니요
HaveIBeenPwned	예	아니요	아니요	아니요	예

요구 사항

이 MCP 서비스는 관찰 가능한 조회에 대해 어떤 타사 강화 서비스를 사용해야 하는지 결정하는 데 사용되는 사용자 지정 구성 파일을 구현합니다.

현재로서는 개발/테스트용으로만 사용하기 때문에 로컬 Mac/시스템에서 실행하는 가장 쉬운 방법은 다음과 같습니다.

지엑스피1

이렇게 하려면 제공된 템플릿 .env.example 을 사용하고 비밀을 포함하는 새 .env 파일을 만들어야 합니다.

config.yaml

이 프로젝트는 사용자 정의 구성 파일을 제공하며 이해하기 매우 쉽다고 생각합니다.

먼저, 제공된 config.yaml.example 구성을 복사하고 이 서비스를 사용하기 전에 .example 확장자를 제거하세요.

이 구성 파일에는 두 가지 주요 데이터 섹션( server 및 enrichments) 이 있습니다.

기본적으로 지원되는 모든 서비스는 현재 구현된 보강 작업 유형에 매핑됩니다. 현재 유일한 보강 작업 유형은 lookups , 향후 다른 보강 작업 유형이 구현될 수 있습니다.

lookups 에서 다양한 지원 강화 유형을 확인할 수 있습니다.

즉, 각 개별 서비스는 apikey 라는 키와 해당 서비스의 API 키 값을 가질 수 있지만 그렇게 하지 않는 것이 좋습니다.

config.yaml.example 에서 이 키 값을 직접 설정할 수 있지만 .env 를 사용하는 것이 더 좋습니다.

참고: 이 서비스를 구현할 때는 비밀을 환경 변수로 설정하는 것이 좋습니다. 비밀을 저장하는 건 이제 그만하세요.

이 서비스가 이러한 변수를 검색하려면 변수가 특정 형식이어야 합니다. 현재 지원되는 변수 목록은 다음과 같습니다.

강화_MCP_바이러스_전체_키
강화_MCP_하이브리드_분석_키
강화_MCP_외계인_보관_키
강화_MCP_쇼단_키
강화_MCP_URLSCAN_키
강화_MCP_남용_IPDB_키
강화_MCP_HIBP_키

서버 구성

여기에는 주로 샌드박싱과 테스트를 위한 최소한의 설정이 있지만, 이 서비스가 작동하려면 일반적으로 이러한 설정을 변경하거나 수정할 필요가 없습니다.

server:
  host: 0.0.0.0 # the host address
  port: 8000 # the port
  debug: false # whether to enable debug logging
  log_level: INFO # the default logging level

강화 구성

설정 파일의 각 강화 기능은 enrichments 키 아래에 있습니다. 또한, 수행 가능한 다양한 강화 기능 유형을 구분했습니다. 즉, 현재 구현에서는 lookups 라는 단일 작업 유형만 있지만, 향후 scans 이나 queries 등으로 확장될 수 있습니다.

이러한 상위 수준 작업 아래에는 관찰 가능 유형과 해당 유형을 지원하는 서비스 목록이 나열되어 있습니다. 현재 지원되는 관찰 가능 유형은 다음과 같습니다.

ipaddress - IPv4 주소
도메인 - 도메인 또는 netloc
url - 스키마 등을 포함한 완전한 URL
이메일 - 표준 이메일 주소

다음 유형도 지원하지만 현재 구현되지 않았습니다.

md5 - 파일 MD5 해시
sha1 - 파일 SHA1 해시
sha256 - 파일 SHA256 해시

각 서비스에는 name 과 template 있어야 합니다. apikey 필드를 제공할 수 있지만 환경 변수를 사용하는 것이 좋습니다.

프롬프트 템플릿

각 서비스와 Observable 유형은 자체 템플릿을 가질 수 있습니다. 템플릿은 templates 디렉터리에 있으며, 모든 템플릿은 여기에 있어야 합니다.

정의된 각 서비스에는 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"
}

용법

미리 구축된 서버를 사용하려면 다음 지침을 따르세요: https://modelcontextprotocol.io/quickstart/user

데스크톱용 Claude 다운로드
uv 설치

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

이 리포를 다운로드하고 Claude for Desktop 구성에 추가하세요.
- 데스크톱용 Claude > 설정 > 개발자 > 구성 편집

이렇게 하면 다음 위치에 구성 파일이 생성됩니다.

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

데스크톱용 Claude 다시 시작

이제 채팅 창에 두 개의 아이콘이 표시됩니다. 도구를 표시하는 망치와 정의된 프롬프트와 필요한 입력을 표시하는 연결 아이콘입니다.

설계

이 서버를 만들면서 Astral UV 와 MCP를 배우고 있었습니다. 좀 오버 엔지니어링한 건 사실이지만 재밌었습니다. 이 코드 중 일부는 나중에도 활용할 수 있을 것 같아서 그 부분도 염두에 두고 디자인했습니다 (자세한 내용은 추후에 알려드리겠습니다).

또한, 반환된 프롬프트/결과를 보다 효율적으로 관리할 수 있고 향후 사용 사례도 개선할 수 있기 때문에 Jinja2 템플릿으로 특별히 전환했습니다.

피드백, 개선 사항, 기능 요청 사항이 있으시면 알려주시기 바랍니다. 모두 기쁘게 듣겠습니다.

기여하다

기여를 환영합니다! 풀 리퀘스트도 자유롭게 제출해 주세요.

부인 성명

이 도구는 교육 및 공인 테스트 목적으로만 사용됩니다.

Enrichment MCP Server