Velociraptor MCP 서버

제작자: mgreen27/mcp-velociraptor 추가 기여자: Snoe Findley

Velociraptor MCP(Model Context Protocol) 서버는 디지털 포렌식 및 사고 대응(DFIR)을 위해 설계된 통합 인터페이스입니다. 이 서버를 통해 LLM 프레임워크(Claude, Gemini, Open WebUI, n8n 등)가 Velociraptor 엔드포인트 모니터링 엔진과 프로그래밍 방식으로 상호 작용할 수 있습니다.

개요

이 MCP 서버는 표준 Velociraptor 기능을 AI 에이전트에 노출하여 다음 작업을 수행할 수 있게 합니다:

• YARA를 사용한 파일 및 메모리 스캔 수행.

• 네트워크 격리 및 프로세스 종료를 포함한 수정 작업 실행.

• Windows, macOS 및 Linux 전반에 걸친 아티팩트 수집(예: MFT 파싱, 이벤트 로그 추출, USN 저널 분석 및 프로세스 메모리 검사).

보안 참고 사항: 이 서버는 토큰 오버플로를 완화하고 VQL 인젝션을 방지하기 위해 데이터 제한 및 VQL 문자열 정제 기능을 적용합니다. 임의의 명령줄 스크립트를 실행하는 대신, 엔드포인트 안정성을 보장하기 위해 표준 내장 Velociraptor 아티팩트를 사용합니다.

Related MCP server: Velociraptor MCP Server

1. 사전 요구 사항

실행 중인 Velociraptor 서버와 해당 API 구성 파일이 필요합니다. 추가로 다음이 필요합니다:

• 로컬(stdio) 배포의 경우: Python 3.10+가 설치되어 있어야 합니다.

• 네트워크(SSE) 배포의 경우: Docker 및 Docker Compose가 설치되어 있어야 합니다.

1. Velociraptor 서버에 전용 API 사용자를 생성합니다:

   velociraptor --config /etc/velociraptor/server.config.yaml config api_client --name mcp_agent --role administrator,api api_client.yaml

2. api_client.yaml을 이 프로젝트의 루트 디렉토리로 복사합니다.

3. .env.example의 이름을 .env로 변경하고 구성 환경 변수를 매핑합니다:

   VELOCIRAPTOR_API_CONFIG=api_client.yaml

2. 로컬 배포 (stdio)

표준 입출력(stdio)을 통한 배포는 Claude Desktop, Claude Code 또는 Gemini CLI와 같은 로컬 데스크톱 클라이언트에 권장되는 구성입니다.

설정

1. Python 3.10+가 설치되어 있는지 확인합니다.

2. 가상 환경을 초기화하고 활성화합니다:

   python -m venv .venv
   # Windows
   .venv\Scripts\activate 
   # Mac/Linux
   source .venv/bin/activate

3. 종속성을 설치합니다:

   pip install -r requirements.txt

클라이언트 연결

stdio 전송을 사용하여 MCP 클라이언트의 구성 파일에 연결을 추가합니다. 가상 환경의 파이썬 실행 파일을 직접 가리키도록 설정하십시오:

{
  "mcpServers": {
    "velociraptor-dfir": {
      "command": "/path/to/repo/.venv/bin/python",
      "args": ["/path/to/repo/mcp_velociraptor_bridge.py"]
    }
  }
}

3. 네트워크 배포 (Docker / SSE)

Open WebUI 또는 n8n과 같은 서버 기반 플랫폼의 경우, 포함된 Docker Compose 구성을 통해 서버 전송 이벤트(SSE)를 사용하여 로컬 네트워크를 통해 MCP 서버를 노출할 수 있습니다.

설정

이 저장소는 FastMCP HTTP 서버를 활용하여 SSE REST 엔드포인트를 제공합니다.

1. api_client.yaml과 .env가 루트 디렉토리에 있는지 확인합니다.

2. Docker 컨테이너를 빌드하고 시작합니다:

   docker compose up -d

3. 서버는 http://<your-host-ip>:8088/sse에서 SSE를 통해 액세스할 수 있습니다.

⚠️ 보안 및 강화 요구 사항

**[!CAUTION] 이 MCP 서버는 Velociraptor 내에서 관리자(Administrator) 권한으로 작동합니다. 프로세스를 종료하고, 파일을 검색하며, 배포 전반에 걸쳐 민감한 엔드포인트 데이터에 액세스할 수 있는 기능을 갖추고 있습니다.

Docker를 통해 네트워크상에 서버를 노출할 때:

• 기본 인증 없음: 내장된 SSE 서버는 강력한 HTTP 인증 메커니즘을 제공하지 않습니다.

• 노출 최소화: 포트 8088을 공용 인터넷이나 신뢰할 수 없는 네트워크에 노출하지 마십시오.

• 네트워크 프록시: 컨테이너 앞에 리버스 프록시(예: Nginx, Traefik)를 배포하여 상호 TLS(mTLS), 엄격한 IP 허용 목록 또는 이에 상응하는 네트워크 수준의 인증을 강제해야 합니다. 트래픽은 승인된 LLM 소비 노드로 명시적으로 제한되어야 합니다.

문서

지원되는 macOS, Linux 및 Windows 포렌식 도구, 구성 세부 정보 및 아키텍처 다이어그램에 대한 전체 목록은 종합 문서를 참조하십시오.