pentestMCP: MCP를 통한 AI 기반 침투 테스트

pentestMCP는 MCP(Model Context Protocol)를 통해 대규모 언어 모델(LLM)과 실용적인 침투 테스트 도구 간의 강력한 브리지를 제공합니다. 이 프로젝트는 MCP 서버로 작동하여 20개 이상의 표준 보안 평가 유틸리티(Nmap, Nuclei, ZAP, SQLMap 등)를 호출 가능한 '도구'로 노출합니다. 이를 통해 MCP 호환 클라이언트(Claude Desktop 또는 특정 VS Code 설정 등) 내의 AI 에이전트가 이러한 유틸리티를 활용하여 자동화되고 대화형인 보안 분석 작업을 수행할 수 있습니다.

목표는 복잡한 보안 워크플로우를 자연어로 제어할 수 있게 하여 침투 테스트 기능에 대한 접근성을 높이고 AI 중심 환경에 통합하는 것입니다. 이 작업은 Laurie Kirk의 GhidraMCP에서 영감을 받았습니다.

목차

• 핵심 개념 및 아키텍처

• 주요 기능

• 사전 요구 사항

• 설치 및 설정

  • 사전 빌드된 Docker 이미지 사용 (권장)

  • 로컬에서 Docker 이미지 빌드

• 클라이언트 호스트 통합

  • Claude Desktop 통합

  • VS Code Copilot Chat 통합

• 도구 참조

• 보안 고려 사항

• 기여

• 라이선스

• 고지 사항

• 감사의 말

Related MCP server: redteam-mcp

비디오 데모

https://github.com/user-attachments/assets/930c879a-5cb4-478a-b033-f30df0e770a6

핵심 개념 및 아키텍처

pentestMCP는 MCP 사양을 엄격히 준수하며 MCP 서버로만 작동합니다. 특정 LLM을 내장하거나 직접 통신하지 않습니다. 상호 작용 흐름은 MCP 클라이언트 호스트 애플리케이션에 의해 중재됩니다:

1. 클라이언트 호스트 애플리케이션 (예: Claude Desktop, 사용자 지정 에이전트): pentestMCP에 연결하고(일반적으로 Docker를 통해 중개되는 stdio를 통해), 사용자 상호 작용을 관리하며, 선택된 LLM과 인터페이스합니다.

2. LLM: 사용자 프롬프트와 도구 정의(클라이언트 호스트를 통해 pentestMCP에서 가져온)를 수신합니다. 컨텍스트에 따라 호출할 도구를 결정합니다.

3. pentestMCP 서버 (이 프로젝트): Docker 컨테이너 내에서 실행됩니다. 클라이언트 호스트의 tools/call 요청을 수신하고, 해당하는 기본 도구(예: nmap)를 실행하고 결과를 반환합니다.

4. 외부 도구: Docker 이미지 내에 캡슐화된 실제 명령줄 유틸리티입니다.

서버는 Python MCP SDK(mcp.server.fastmcp.FastMCP)를 사용하여 구축되었으며 다음을 갖추고 있습니다:

• 도구 검색: 자동 MCP 도구 스키마 생성에 Python 타입 힌트와 독스트링을 활용합니다.

• 동시성 제어: threading.Semaphore는 리소스 집약적인 스캔의 동시 실행을 제한합니다.

• 비동기 스캔 패턴: MCP 연결이 차단되는 것을 방지하기 위해 장기 실행 작업(Nmap, Nuclei, SQLMap, Gobuster)에 대해 시작/가져오기(launch/fetch) 메서드를 구현합니다.

sequenceDiagram
    participant User
    participant ClientHost as Client Host (Claude, VS Code)
    participant LLM
    participant PentestMCP as pentestMCP Server (Docker via stdio)
    participant ExtTool as External Tool (e.g., Nmap)

    User->>ClientHost: "Perform Nmap service scan on scanme.nmap.org"
    ClientHost->>PentestMCP: tools/list Request
    PentestMCP-->>ClientHost: List of Tools (including 'run_nmap_scan')
    ClientHost->>LLM: User Prompt + Available Tools Description
    LLM-->>ClientHost: Decision: Use 'run_nmap_scan', target='scanme.nmap.org', args='-sV'
    ClientHost->>PentestMCP: tools/call (name='run_nmap_scan', args={...})
    Note over PentestMCP, ExtTool: pentestMCP executes 'nmap -sV scanme.nmap.org' internally
    PentestMCP-->>ClientHost: tools/call Result (pid, output_path for async or direct output)
    ClientHost->>LLM: Tool Execution Result
    LLM-->>ClientHost: Formulate Final Response
    ClientHost-->>User: "Nmap scan launched/completed. Results..."

주요 기능

• 포괄적인 도구 세트: MCP를 통해 20개 이상의 필수 침투 테스트 도구를 통합합니다.

• 표준화된 액세스: stdio 서버 실행을 지원하는 모든 MCP 클라이언트가 복잡한 침투 테스트 워크플로우를 활용할 수 있도록 합니다.

• 비차단 스캔: 상호 작용 흐름을 막지 않으면서 장기 실행 스캔을 효율적으로 처리합니다.

• 리소스 관리: 스캔에 대한 기본적인 동시성 제한을 구현합니다.

• 이식 가능 및 재현 가능: Docker화된 환경은 모든 종속성과 도구가 플랫폼(Windows, macOS, Linux) 전반에 걸쳐 일관되게 사용 가능하도록 보장합니다.

• 웹 스캐너 통합: OWASP ZAP 활성 스캔 및 AJAX 스파이더 기능을 직접 제어할 수 있습니다.

사전 요구 사항

• Docker: Docker Desktop(Windows/macOS) 또는 Docker Engine(Linux)이 설치 및 실행 중이어야 합니다. Docker 데몬이 활성화되어 있는지 확인하세요.

• Git: 로컬에서 이미지를 빌드하는 경우에만 필요합니다(git clone 단계).

• (선택 사항이지만 권장) OWASP ZAP 인스턴스: ZAP 관련 도구(run_zap_*, run_active__scan_*, run_ajax_*)를 사용하려면 필요합니다. 이 ZAP 인스턴스는 실행 중이고 pentestMCP Docker 컨테이너 내부에서 네트워크로 접근 가능해야 합니다(구성은 클라이언트 호스트 통합 섹션 참조).

설치 및 설정

가장 빠르고 안정적인 설정을 위해 사전 빌드된 Docker 이미지를 사용하는 것이 좋습니다.

🐳 사전 빌드된 Docker 이미지 사용 (권장)

사전 빌드된 이미지를 사용하면 로컬 빌드 시간을 피하고 gofang, nmap, nuclei와 같은 모든 도구가 종속성 문제 없이 올바르게 설치되도록 할 수 있습니다.

1. Docker Hub에서 이미지 풀:

   docker pull ramgameer/pentest-mcp:latest

   ℹ️ 참고: 환경에 따라 Docker 데몬이 실행 중인지 인증하거나 확인해야 할 수 있습니다.

🛠️ 로컬에서 Docker 이미지 빌드

⚠️ 중요: 현재 로컬 빌드는 Linux 환경에서 가장 효율적이고 지원됩니다.

서버 코드를 수정하거나, 최신 버전을 사용하거나, 사전 빌드된 이미지를 사용할 수 없는 경우 Docker 이미지를 로컬에서 빌드할 수 있습니다.

1. 저장소 클론:

   git clone https://github.com/ramkansal/pentestMCP.git
   cd pentestMCP

2. Docker 이미지 빌드:

   docker build -t pentest-mcp-server:custom .

3. SecLists 설치 (선택 사항이지만 적극 권장):

   💡 팁: 여러 도구(Gobuster, 퍼징 유틸리티 등)는 대용량 워드리스트에 의존합니다. 특정 스캔이 효과적으로 작동하려면 SecLists 저장소를 클론해야 합니다. GXP5

클라이언트 호스트 통합

pentestMCP는 Docker 내에서 실행되며 stdio를 통해 클라이언트 호스트와 통신합니다. 호스트(예: Claude Desktop, VS Code)를 구성하여 docker run -i ...를 사용해 서버를 실행하도록 해야 합니다.

Claude Desktop 통합

1. 구성 파일 찾기/만들기:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 구성 편집: mcpServers 섹션을 추가/업데이트합니다. 올바른 이미지 이름(ramgameer/pentest-mcp:latest 또는 사용자 지정 태그)을 사용하세요.

   {
     "mcpServers": {
       "pentestMCP": {
         "command": "docker",
         "args": [
           "run",
           "--rm",
           "-i",
           "ramgameer/pentest-mcp:latest"
         ]
       }
     }
   }

3. Claude Desktop을 완전히 다시 시작합니다.

4. 확인: 아이콘을 찾습니다. 클릭하면 침투 테스트 도구 목록이 표시됩니다.

5. 상호 작용: Claude에게 도구 사용을 요청합니다(초안의 예시 참조).

VS Code Copilot Chat 통합

통합하려면 MCP를 지원하는 Copilot Chat 에이전트에 대한 MCP 서버를 정의하도록 VS Code 설정을 구성해야 합니다.

1. 사전 요구 사항 설치: Github Copilot 확장 및 관련 GitHub Copilot 확장이 설치되어 있는지 확인합니다.

2. VS Code 설정 구성: 사용자 또는 작업 영역 settings.json 파일을 엽니다(명령 팔레트: "기본 설정: 설정 열기(JSON)"). 적절한 경로에 MCP 서버 구성을 추가합니다(이 경로는 특정 Copilot Chat 에이전트 구현에 따라 다를 수 있으므로 해당 문서를 확인하세요):

   "pentest-mcp": {
       "type": "stdio",
       "command": "docker",
       "args": [
           "run",
           "-i",
           "--rm",
           "ramgameer/pentest-mcp:latest"
       ]
   }

3. VS Code / 에이전트 다시 로드: VS Code를 다시 시작하거나 관련 명령을 사용하여 Copilot 에이전트의 구성을 다시 로드하여 변경 사항을 적용합니다. 자세한 내용은 특정 Copilot 에이전트의 설명서를 참조하십시오.

4. 상호 작용: Copilot Chat 인터페이스를 사용하여, 에이전트가 지원하는 경우 멘션을 통해 도구를 호출하거나 프롬프트에 따라 에이전트가 도구를 호출하도록 합니다.

도구 참조

서버는 기능에 따라 분류된 다양한 도구를 노출합니다:

• 정찰 및 열거:

  • run_subfinder: ProjectDiscovery의 Subfinder를 사용하여 하위 도메인을 검색합니다.

  • launch_nmap_scan / fetch_nmap_results: Nmap 네트워크 스캔을 실행하고 비동기적으로 결과를 검색합니다.

  • run_gobuster_scan / check_gobuster_status: Gobuster로 디렉터리/파일/DNS 무차별 대입을 비동기적으로 수행합니다.

  • launch_gofang_scan / fetch_gofang_results: 강력한 추출 기능을 갖춘 올인원 웹 크롤러인 gofang을 실행합니다.

  • run_harvester / check_harvester_status: OSINT 수집(이메일, 호스트, IP)을 위해 theHarvester를 비동기적으로 실행합니다.

  • run_dig_tool: DNS dig 쿼리를 실행합니다.

  • fetch_whois_data: 도메인에 대한 WHOIS 정보를 검색합니다.

  • run_curl_tool: HTTP 상호 작용을 위해 cURL 명령을 실행합니다.

• 취약점 스캔:

  • launch_nuclei_scan / fetch_nuclei_results: ProjectDiscovery의 Nuclei로 템플릿 기반 취약점 스캔을 비동기적으로 실행합니다.

• 웹 애플리케이션 분석:

  • launch_arjun_scan / fetch_arjun_results: Arjun을 사용하여 숨겨진 HTTP 매개변수를 찾습니다.

• 익스플로잇 지원:

  • run_searchsploit: Searchsploit을 사용하여 로컬 Exploit-DB 데이터베이스를 검색합니다.

  • run_sqlmap_tool / check_sqlmap_status: SQL 주입 테스트를 위해 SQLmap을 비동기적으로 실행합니다.

• Active Directory 분석 (ad_* 도구):

  • 열거: ad_user_enum, ad_shares_enum, ad_smb_signing_check, ad_certipy_enum, ad_ldap_dump, ad_bloodhound_collect

  • 공격/강제: ad_asreproast, ad_kerberoast, ad_password_spray, ad_coerce_petitpotam, ad_coerce_printerbug, ad_responder_poison, ad_relay_setup

  • 자격 증명/도메인 작업: ad_check_credentials, ad_secrets_dump, ad_dcsync

보안 고려 사항

• 실행 권한: 도구는 Docker 내에서 appuser로 실행되지만 Docker 자체는 호스트 권한으로 실행됩니다. 파일을 수정하거나 상위 시스템 액세스가 필요한 도구를 사용할 때는 주의하십시오.

• 대상 권한: 중요: 이러한 도구는 명시적이고 사전 서면 승인을 받은 시스템에 대해서만 사용하십시오. 승인되지 않은 스캔은 불법이며 비윤리적입니다.

• 네트워크 노출: ZAP의 포트(-p 8888:8888)를 매핑하는 경우, 호스트가 신뢰할 수 없는 네트워크에 있는 경우 호스트 방화벽이 액세스를 제한하는지 확인하십시오. 구성된 ZAP API 키는 인스턴스에 대한 제어를 제공합니다.

• 입력 검증: MCP는 구조화된 입력을 제공하지만, 기본 도구는 Python 래퍼 함수 내에서 강력하게 처리되지 않으면 조작된 인자에 여전히 취약할 수 있습니다.

기여

기여는 언제나 환영합니다! 저장소를 포크하고, 기능 브랜치를 만들고, 풀 리퀘스트를 제출하세요. 모든 기여에는 윤리적 테스트 지침을 준수해야 합니다. 버그 신고 및 기능 제안은 GitHub 이슈를 통해 환영합니다.

라이선스

이 프로젝트는 MIT 라이선스의 조건에 따라 배포됩니다.

고지 사항

이 소프트웨어는 오직 교육 목적과 승인된 윤리적 보안 테스트를 위해서만 사용됩니다. 명시적 허가 없이 시스템에 사용하는 것은 엄격히 금지되며 불법입니다. 저자와 기여자는 이 프로그램으로 인한 오용이나 손해에 대해 어떠한 책임도 지지 않습니다. 사용에 따른 책임은 본인에게 있으며 모든 관련 법률 및 계약을 준수해야 합니다.

감사의 말

이 프로젝트는 Laurie Kirk의 혁신적인 GhidraMCP 작업에서 깊은 영감을 받았습니다.