mcp-shodan

쇼단 MCP 서버

Shodan API 및 Shodan CVEDB 쿼리를 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 IP 정찰, DNS 운영, 취약점 추적, 기기 검색 등 Shodan의 네트워크 인텔리전스 및 보안 서비스에 대한 포괄적인 액세스를 제공합니다. 모든 도구는 손쉬운 분석 및 통합을 위해 구조화되고 형식화된 출력을 제공합니다.

빠른 시작(권장)

Smithery를 통해 설치

Smithery를 통해 Claude Desktop에 Shodan Server를 자동으로 설치하려면:

지엑스피1

수동 설치

1. npm을 통해 서버를 전역으로 설치합니다.

2. Claude Desktop 구성 파일에 다음을 추가합니다.

구성 파일 위치:

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

3. Claude Desktop을 다시 시작하세요

대체 설정(소스에서)

소스에서 실행하거나 코드를 수정해야 하는 경우:

1. 복제 및 빌드:

2. Claude Desktop 구성에 다음을 추가합니다.

특징

• 네트워크 정찰 : 열려 있는 포트, 서비스, 취약점을 포함하여 IP 주소에 대한 자세한 정보를 쿼리합니다.
• DNS 작업 : 도메인 및 IP 주소에 대한 정방향 및 역방향 DNS 조회
• 취약성 인텔리전스 : 자세한 취약성 정보, CPE 조회 및 제품별 CVE 추적을 위한 Shodan의 CVEDB에 액세스
• 장치 검색 : 고급 필터링을 통해 인터넷에 연결된 장치의 Shodan 데이터베이스 검색

도구

1. IP 조회 도구

• 이름: ip_lookup
• 설명: 지리적 위치, 열려 있는 포트, 실행 중인 서비스, SSL 인증서, 호스트 이름 및 클라우드 공급자 세부 정보(사용 가능한 경우)를 포함하여 IP 주소에 대한 포괄적인 정보를 검색합니다.
• 매개변수:
  • ip (필수): 조회할 IP 주소
• 보고:
  • IP 정보(주소, 조직, ISP, ASN)
  • 위치(국가, 도시, 좌표)
  • 서비스(포트, 프로토콜, 배너)
  • 클라우드 공급자 세부 정보(사용 가능한 경우)
  • 연관된 호스트 이름 및 도메인
  • 태그

2. 쇼단 검색 도구

• 이름: shodan_search
• 설명: 인터넷에 연결된 기기의 Shodan 데이터베이스 검색
• 매개변수:
  • query (필수): Shodan 검색 쿼리
  • max_results (선택 사항, 기본값: 10): 반환할 결과 수
• 보고:
  • 전체 결과가 포함된 검색 요약
  • 국가 기반 분포 통계
  • 다음을 포함한 자세한 장치 정보:
    • 기본 정보(IP, 조직, ISP)
    • 위치 데이터
    • 서비스 세부 정보
    • 웹 서버 정보
    • 연관된 호스트 이름 및 도메인

3. CVE 조회 도구

• 이름: cve_lookup
• 설명: Shodan의 CVEDB에서 자세한 취약성 정보를 쿼리합니다.
• 매개변수:
  • cve (필수): CVE-YYYY-NNNNN 형식의 CVE 식별자(예: CVE-2021-44228)
• 보고:
  • 기본 정보(ID, 게시일, 요약)
  • 심각도 점수:
    • 심각도 수준이 있는 CVSS v2 및 v3
    • EPSS 확률 및 순위
  • 영향 평가:
    • KEV 상태
    • 제안된 완화책
    • 랜섬웨어 협회
  • 영향을 받는 제품(CPE)
  • 참고문헌

4. DNS 조회 도구

• 이름: dns_lookup
• 설명: Shodan의 DNS 서비스를 사용하여 도메인 이름을 IP 주소로 변환합니다.
• 매개변수:
  • hostnames (필수): 확인할 호스트 이름 배열
• 보고:
  • 호스트 이름을 IP에 매핑하는 DNS 확인
  • 총 조회 및 쿼리된 호스트 이름 요약

5. 역방향 DNS 조회 도구

• 이름: reverse_dns_lookup
• 설명: IP 주소와 연결된 호스트 이름을 찾기 위해 역방향 DNS 조회를 수행합니다.
• 매개변수:
  • ips (필수): 조회할 IP 주소 배열
• 보고:
  • IP를 호스트 이름에 매핑하는 역방향 DNS 확인
  • 전체 조회 및 결과 요약

6. CPE 조회 도구

• 이름: cpe_lookup
• 설명: 제품 이름으로 CPE(Common Platform Enumeration) 항목을 검색합니다.
• 매개변수:
  • product (필수): 검색할 제품의 이름
  • count (선택 사항, 기본값: false): true인 경우 일치하는 CPE의 개수만 반환합니다.
  • skip (선택 사항, 기본값: 0): 건너뛸 CPE 수(페이지 매김용)
  • limit (선택 사항, 기본값: 1000): 반환할 CPE의 최대 수
• 보고:
  • count가 참인 경우: 일치하는 CPE의 총 수
  • count가 false인 경우: 페이지 번호 세부 정보가 포함된 CPE 목록

7. 제품별 CVE 도구

• 이름: cves_by_product
• 설명: 특정 제품 또는 CPE에 영향을 미치는 취약점 검색
• 매개변수:
  • cpe23 (선택 사항): CPE 2.3 식별자(형식: cpe:2.3:part:vendor:product:version)
  • product (선택 사항): CVE를 검색할 제품 이름
  • count (선택 사항, 기본값: false): true인 경우 일치하는 CVE의 개수만 반환합니다.
  • is_kev (선택 사항, 기본값: false): true인 경우 KEV 플래그가 설정된 CVE만 반환합니다.
  • sort_by_epss (선택 사항, 기본값: false): true인 경우 CVE를 EPSS 점수별로 정렬합니다.
  • skip (선택 사항, 기본값: 0): 건너뛸 CVE 수(페이지 매김용)
  • limit (선택 사항, 기본값: 1000): 반환할 CVE의 최대 수
  • start_date (선택 사항): CVE 필터링 시작 날짜(형식: YYYY-MM-DDTHH:MM:SS)
  • end_date (선택 사항): CVE 필터링 종료 날짜(형식: YYYY-MM-DDTHH:MM:SS)
• 참고사항:
  • cpe23 또는 제품 중 하나만 제공해야 하며 둘 다 제공하면 안 됩니다.
  • 날짜 필터링은 CVE의 게시된 시간을 사용합니다.
• 보고:
  • 쿼리 정보
  • 페이지 번호 세부 정보가 포함된 결과 요약
  • 다음을 포함한 자세한 취약성 정보:
    • 기본 정보
    • 심각도 점수
    • 영향 평가
    • 참고문헌

요구 사항

• Node.js(v18 이상)
• 유효한 Shodan API 키

문제 해결

API 키 문제

API 키 관련 오류(예: "요청이 상태 코드 401로 실패했습니다")가 표시되는 경우:

1. API 키를 확인하세요:
   • 계정 설정 에서 유효한 Shodan API 키여야 합니다.
   • 키에 작업에 필요한 충분한 크레딧/권한이 있는지 확인하세요.
   • 구성에서 키 주위에 추가 공백이나 따옴표가 있는지 확인하세요.
   • SHODAN_API_KEY 환경 변수에 키가 올바르게 설정되었는지 확인하세요.
2. 일반적인 오류 코드:
   • 401 인증되지 않음: 잘못된 API 키 또는 인증 누락
   • 402 지불 필요: 쿼리 크레딧 없음
   • 429 요청이 너무 많음: 속도 제한을 초과했습니다.
3. 구성 단계: a. Shodan 계정 에서 API 키를 가져옵니다. b. 구성 파일에 추가합니다.
   { "mcpServers": { "shodan": { "command": "mcp-shodan", "env": { "SHODAN_API_KEY": "your-actual-api-key-here" } } } }
   c. 구성 파일을 저장합니다. d. Claude Desktop을 다시 시작합니다.
4. 키 테스트:
   • 먼저 간단한 쿼리를 시도해 보세요(예: "google.com"에 대한 dns_lookup).
   • Shodan 계정 대시보드에서 신용 상태를 확인하세요.
   • curl에서 키가 직접 작동하는지 확인하세요.
     curl "https://api.shodan.io/dns/resolve?hostnames=google.com&key=your-api-key"

모듈 로딩 문제

모듈 로딩 오류가 표시되는 경우:

1. 글로벌 설치의 경우: 빠른 시작에 표시된 간단한 구성을 사용하세요.
2. 소스 설치의 경우: Node.js v18 이상을 사용하고 있는지 확인하세요.

개발

핫 리로딩을 사용하여 개발 모드에서 실행하려면:

오류 처리

서버에는 다음에 대한 포괄적인 오류 처리 기능이 포함되어 있습니다.

• 잘못된 API 키
• 속도 제한
• 네트워크 오류
• 잘못된 입력 매개변수
• 잘못된 CVE 형식
• 잘못된 CPE 조회 매개변수
• 잘못된 날짜 형식
• 상호 배타적 매개변수 검증

버전 기록

• v1.0.12: 역방향 DNS 조회 추가 및 출력 형식 개선
• v1.0.7: 제품 검색 기능을 통해 CVE를 추가하고 취약성 도구 이름을 cve_lookup으로 변경했습니다.
• v1.0.6: 향상된 CVE 조회 및 CPE 검색 기능을 위한 CVEDB 통합 추가
• v1.0.0: 핵심 기능이 포함된 초기 릴리스

기여하다

1. 저장소를 포크하세요
2. 기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
3. 변경 사항을 커밋하세요( git commit -m 'Add amazing feature' )
4. 브랜치에 푸시( git push origin feature/amazing-feature )
5. 풀 리퀘스트 열기

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.