ZoomEye MCP 서버

쿼리 조건에 따라 네트워크 자산 정보를 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 통해 대규모 언어 모델(LLM)은 dork 및 기타 검색 매개변수를 사용하여 ZoomEye에 쿼리를 보내 네트워크 자산 정보를 얻을 수 있습니다.

이 MCP 서버는 Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed와 같은 AI 어시스턴트 및 개발 환경과 통합되어 자연어 상호 작용을 통해 인터넷에 연결된 장치, 서비스 및 취약점을 검색하고 분석할 수 있습니다.

특징

dork를 사용하여 ZoomEye에서 네트워크 자산 정보 쿼리
성능 향상 및 API 호출 감소를 위한 캐싱 메커니즘
실패한 API 요청에 대한 자동 재시도 메커니즘
포괄적인 오류 처리 및 로깅

사용 가능한 도구

zoomeye_search - 쿼리 조건에 따라 네트워크 자산 정보를 가져옵니다.
- 필수 매개변수:
  - qbase64 (문자열): ZoomEye 검색을 위한 Base64 인코딩된 쿼리 문자열
- 선택 매개변수:
  - page (정수): 자산 페이지 번호 보기, 기본값은 1입니다.
  - pagesize (정수): 페이지당 레코드 수, 기본값은 10, 최대값은 1000입니다.
  - fields (문자열): 쉼표로 구분된 반환할 필드
  - sub_type (문자열): 데이터 유형이며 v4, v6 및 웹을 지원합니다. 기본값은 v4입니다.
  - facets (문자열): 통계 항목(여러 개가 있는 경우 쉼표로 구분)
  - ignore_cache (부울): 캐시를 무시할지 여부

사용 가이드

기본 사용법

서버가 실행되면 AI 어시스턴트나 개발 환경을 통해 서버와 상호 작용할 수 있습니다. 사용 방법은 다음과 같습니다.

위의 설치 방법 중 하나를 사용하여 서버를 시작하세요.
AI 어시스턴트(Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed 등)를 구성하여 서버를 사용하세요.
자연어를 사용하여 네트워크 정보 쿼리

검색 구문 가이드

검색 범위에는 장치(IPv4, IPv6)와 웹사이트(도메인)가 포함됩니다.
검색어를 입력하면 시스템은 HTTP, SSH, FTP 등 다양한 프로토콜의 콘텐츠(예: HTTP/HTTPS 프로토콜 헤더, 본문, SSL, 제목 및 기타 프로토콜 배너)를 포함하여 "글로벌" 모드로 키워드를 일치시킵니다.
검색 문자열은 대소문자를 구분하지 않으며, 일치 여부를 확인하기 위해 분할됩니다(검색 결과 페이지에 "분할" 테스트 기능이 제공됩니다). 검색에 ==를 사용하면 엄격한 구문을 사용하여 대소문자를 정확하게 구분하여 일치시킵니다.
검색 문자열에는 따옴표를 사용해 주세요(예: "Cisco System" 또는 'Cisco System'). 검색 문자열에 따옴표가 포함된 경우 이스케이프 문자를 사용하세요(예: "a"b"). 검색 문자열에 괄호가 포함된 경우 이스케이프 문자를 사용하세요(예: portinfo()).

prompts.py 에서 더 자세한 검색 구문 규칙을 볼 수 있습니다.

ZoomEye 검색 API에 대한 자세한 내용은 ZoomEye API v2 설명서를 참조하세요.

시작하기

필수 조건

ZoomEye API 키
- ZoomEye 에 계정을 등록하세요
- 계정 설정에서 API 키를 받으세요
- API 키는 ZoomEye API에 대한 요청을 인증하는 데 사용됩니다.
파이썬 환경
- Python 3.10 이상이 필요합니다
- 또는 Python을 설치하지 않고도 Docker를 사용하여 서버를 실행할 수 있습니다.

설치

PIP 사용

또는 pip를 통해 mcp-server-zoomeye 설치할 수 있습니다.

지엑스피1

설치 후 다음 명령을 사용하여 스크립트로 실행할 수 있습니다.

python -m mcp_server_zoomeye

Docker 사용

Docker를 사용하여 ZoomEye MCP 서버를 실행할 수도 있습니다.

Docker Hub에서 가져오기

# Pull the latest image
docker pull zoomeyeteam/mcp-server-zoomeye:latest

# Run the container with your API key
docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:latest

참고 : linux/amd64 및 linux/arm64 플랫폼을 지원하고 Intel/AMD 및 ARM(예: Apple Silicon) 프로세서에서 실행할 수 있는 다중 아키텍처 Docker 이미지를 제공합니다.

소스에서 빌드

또는 소스에서 Docker 이미지를 빌드할 수 있습니다.

# Clone the repository
git clone https://github.com/zoomeye-ai/mcp_zoomeye.git
cd mcp_zoomeye

# Build the Docker image
docker build -t zoomeyeteam/mcp-server-zoomeye:local .

# Run the container
docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:local

uv를 사용하여

uv 는 Rust로 작성된 빠른 Python 패키지 설치 및 해결 프로그램입니다. pip의 현대적인 대안으로, 상당한 성능 향상을 제공합니다.

uv 설치

# Install uv using curl (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using PowerShell (Windows)
irm https://astral.sh/uv/install.ps1 | iex

# Or using Homebrew (macOS)
brew install uv

uvx를 사용하여 mcp-server-zoomeye 실행

uvx 사용하면 특별한 설치가 필요하지 않으므로 Python 패키지를 직접 실행할 수 있습니다.

uv로 설치하기

또는 uv를 사용하여 패키지를 설치할 수 있습니다.

# Install in the current environment
uv pip install mcp-server-zoomeye

# Or create and install in a new virtual environment
uv venv
uv pip install mcp-server-zoomeye

구성

환경 변수

ZoomEye MCP 서버에는 다음 환경 변수가 필요합니다.

ZOOMEYE_API_KEY : 인증을 위한 ZoomEye API 키

이 환경 변수는 여러 가지 방법으로 설정할 수 있습니다.

셸 세션에서 내보내기 :
export ZOOMEYE_API_KEY="your_api_key_here"
컨테이너를 실행할 때 직접 전달합니다 (Docker의 경우):
docker run -i --rm -e ZOOMEYE_API_KEY=your_api_key_here zoomeyeteam/mcp-server-zoomeye:latest

Claude.app 구성

Claude 설정에 다음을 추가합니다.

"mcpServers": {
  "zoomeye": {
    "command": "uvx",
    "args": ["mcp-server-zoomeye"],
    "env": {
        "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
}

"mcpServers": {
  "zoomeye": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "-e", "ZOOMEYE_API_KEY=your_api_key_here", "zoomeyeteam/mcp-server-zoomeye:latest"],
    "env": {
      "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
}

"mcpServers": {
  "zoomeye": {
    "command": "python",
    "args": ["-m", "mcp_server_zoomeye"],
    "env": {
        "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
}

Zed 구성

Zed의 settings.json에 다음을 추가하세요.

"context_servers": [
  "mcp-server-zoomeye": {
    "command": "uvx",
    "args": ["mcp-server-zoomeye"],
    "env": {
        "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
],

"context_servers": {
  "mcp-server-zoomeye": {
    "command": "python",
    "args": ["-m", "mcp_server_zoomeye"],
    "env": {
        "ZOOMEYE_API_KEY": "your_api_key_here"
    }
  }
},

예시 상호작용

예제 1: 글로벌 Apache Tomcat 자산 검색

{
  "name": "zoomeye_search",
  "arguments": {
    "qbase64": "app=\"Apache Tomcat\""
  }
}

응답:

{
  "code": 60000,
  "message": "success",
  "total": 163139107,
  "query": "title=\"cisco vpn\"",
  "data": [
    {
      "url": "https://1.1.1.1:443",
      "ssl.jarm": "29d29d15d29d29d00029d29d29d29dea0f89a2e5fb09e4d8e099befed92cfa",
      "ssl.ja3s": "45094d08156d110d8ee97b204143db14",
      "iconhash_md5": "f3418a443e7d841097c714d69ec4bcb8",
      "robots_md5": "0b5ce08db7fb8fffe4e14d05588d49d9",
      "security_md5": "0b5ce08db7fb8fffe4e14d05588d49d9",
      "ip": "1.1.1.1",
      "domain": "www.google.com",
      "hostname": "SPACEX",
      "os": "windows",
      "port": 443,
      "service": "https",
      "title": ["GoogleGoogle appsGoogle Search"],
      "version": "1.1.0",
      "device": "webcam",
      "rdns": "c01031-001.cust.wallcloud.ch",
      "product": "OpenSSD",
      "header": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
      "header_hash": "27f9973fe57298c3b63919259877a84d",
      "body": "HTTP/1.1 302 Found Location: https://www.google.com/?gws_rd=ssl Cache-Control: private...",
      "body_hash": "84a18166fde3ee7e7c974b8d1e7e21b4",
      "banner": "SSH-2.0-OpenSSH_7.6p1 Ubuntu-4ubuntu0.3",
      "update_time": "2024-07-03T14:34:10",
      "header.server.name": "nginx",
      "header.server.version": "1.8.1",
      "continent.name": "Europe",
      "country.name": "Germany",
      "province.name": "Hesse",
      "city.name": "Frankfurt",
      "lon": "118.753262",
      "lat": "32.064838",
      "isp.name": "aviel.ru",
      "organization.name": "SERVISFIRST BANK",
      "zipcode": "210003",
      "idc": 0,
      "honeypot": 0,
      "asn": 4837,
      "protocol": "tcp",
      "ssl": "SSL Certificate Version: TLS 1.2 CipherSuit: TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256...",
      "primary_industry": "Finance",
      "sub_industry": "bank",
      "rank": 60
    }
  ]
}

디버깅 및 문제 해결

MCP Inspector 사용

모델 컨텍스트 프로토콜 검사기는 클라이언트 상호작용을 시뮬레이션하여 MCP 서버 디버깅을 지원하는 도구입니다. ZoomEye MCP 서버를 테스트하는 데 사용할 수 있습니다.

# For uvx installation
npx @modelcontextprotocol/inspector uvx mcp-server-zoomeye

# If developing locally
cd path/to/servers/src/mcp_server_zoomeye
npx @modelcontextprotocol/inspector uv run mcp-server-zoomeye

일반적인 문제

인증 오류
- ZoomEye API 키가 올바르고 환경 변수로 올바르게 설정되었는지 확인하세요.
- API 키가 만료되거나 취소되지 않았는지 확인하세요.
연결 문제
- 인터넷 연결을 확인하세요
- ZoomEye API가 다운타임을 겪고 있는지 확인하세요
결과 없음
- 귀하의 쿼리가 너무 구체적이거나 구문 오류가 포함되어 있을 수 있습니다.
- 쿼리를 단순화하거나 다른 검색어를 사용해 보세요.
속도 제한
- ZoomEye API에는 계정 유형에 따라 요금 제한이 있습니다.
- 요청 범위를 넓히거나 계정을 업그레이드하여 더 높은 한도를 얻으세요.

고급 사용법

캐싱

ZoomEye MCP 서버는 성능을 개선하고 API 호출을 줄이기 위해 캐싱을 구현합니다.

응답은 쿼리 매개변수를 기반으로 캐시됩니다.
캐시 기간은 구성 가능합니다(기본값: 1시간)
쿼리에서 ignore_cache``true 로 설정하여 캐시를 우회할 수 있습니다.

사용자 정의 필드

fields 매개변수를 사용하여 쿼리 결과에서 특정 필드를 요청할 수 있습니다.

{
  "name": "zoomeye_search",
  "arguments": {
    "qbase64": "app=\"Apache\"",
    "fields": "ip,port,domain,service,os,country,city"
  }
}

쪽수 매기기

많은 결과를 반환하는 쿼리의 경우, 결과를 페이지별로 살펴볼 수 있습니다.

{
  "name": "zoomeye_search",
  "arguments": {
    "qbase64": "app=\"Apache\"",
    "page": 2,
    "pagesize": 20
  }
}

기여하다

mcp-server-zoomeye의 기능을 확장하고 개선하는 데 도움이 되도록 기여해 주시기 바랍니다. 새로운 관련 도구를 추가하거나, 기존 기능을 강화하거나, 문서를 개선하는 등 여러분의 의견은 소중합니다.

다른 MCP 서버 및 구현 패턴의 예는 https://github.com/modelcontextprotocol/servers를 참조하세요.

풀 리퀘스트를 환영합니다! mcp-server-zoomeye를 더욱 강력하고 실용적으로 만들기 위한 새로운 아이디어, 버그 수정, 개선 사항을 자유롭게 공유해 주세요.

특허

mcp-server-zoomeye는 MIT 라이선스에 따라 라이선스가 부여됩니다. 즉, MIT 라이선스의 조건에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.

ZoomEye MCP Server

Integrations