Headless Binary Ninja MCP 서버 — AI 에이전트에게 180개의 도구를 통해 심층 리버스 엔지니어링 기능을 제공합니다.
헤드리스 Binary Ninja 서버로, MCP(Model Context Protocol)를 사용하여 AI 에이전트에 GUI 없이 디스어셈블리, IL, 패치, 타입, 크로스 레퍼런스 등 심층 리버스 엔지니어링 워크플로에 대한 전체 액세스를 제공합니다.
에이전트 런타임과 동일한 Docker 컨테이너에서 실행되도록 설계되었습니다. 사이드카나 추가 서비스가 필요 없습니다.
이 전체 프로젝트(코드, 테스트, 문서)는 100% 바이브 코딩되었습니다.
기존 Binary Ninja MCP 서버는 GUI에 종속되거나 제한된 도구 표면을 노출합니다. 이 서버는 헤드리스 전용이며 샌드박스 VM/컨테이너 환경에서 에이전트 기반 워크플로를 위해 설계되었습니다. 에이전트가 분석 시스템을 완전히 제어하여 리버스 엔지니어링의 많은 부분을 자동화하고, 사용자는 대화형으로 프로세스를 논의하고 조정할 수 있습니다.
목표는 에이전트가 시간이 지남에 따라 분석을 검사, 개선 및 확장할 수 있는 인터페이스입니다. 즉, 타입, 심볼 및 메타데이터 업데이트, 분석 데이터베이스를 점진적으로 개선, 실행 취소/다시 실행으로 안전하게 패치 적용 및 반복, 그리고 특정 워크플로가 필요한 경우 사용자 정의 스크립트를 실행할 수 있습니다.
binja.eval 및 binja.call을 통해 도구 카탈로그가 포함하지 않는 모든 기능 사용 가능.3.11+binaryninja Python 모듈을 실행 환경에서 가져올 수 있어야 함, 실제 분석용)git clone https://github.com/mrphrazer/binary-ninja-headless-mcp.git
cd binary-ninja-headless-mcp
pip install .
또는 복제 없이 리포지토리 루트에서 직접 설치:
pip install git+https://github.com/mrphrazer/binary-ninja-headless-mcp.git
Stdio 전송(기본값):
python3 binary_ninja_headless_mcp.py
TCP 전송:
python3 binary_ninja_headless_mcp.py --transport tcp --host 127.0.0.1 --port 8765
가짜 백엔드 모드(Binary Ninja 필요 없음):
python3 binary_ninja_headless_mcp.py --fake-backend
이 서버는 표준 MCP를 stdio(기본값) 또는 tcp를 통해 사용하므로, MCP를 지원하는 모든 에이전트 호스트에서 사용할 수 있습니다.
claude mcp add binary_ninja_headless_mcp -- python3 /path/to/binary-ninja-headless-mcp/binary_ninja_headless_mcp.py
또는 프로젝트의 .mcp.json에 추가:
{
"mcpServers": {
"binary_ninja_headless_mcp": {
"command": "python3",
"args": ["binary_ninja_headless_mcp.py"],
"cwd": "/path/to/binary-ninja-headless-mcp"
}
}
}
codex mcp add binary_ninja_headless_mcp -- python3 binary_ninja_headless_mcp.py
binary_ninja_headless_mcp라는 이름의 서버를 등록합니다.cwd가 리포지토리 루트인 경우 명령어 python3에 인수 ["binary_ninja_headless_mcp.py"]를 사용하거나 args에 절대 스크립트 경로를 사용합니다.samples/ls와 같은 상대 경로가 올바르게 확인되도록 cwd를 리포지토리 경로로 설정합니다.--fake-backend를 추가합니다.health.ping을 호출한 다음 session.open을 호출하여 연결을 확인합니다.권장 배포 모델: 에이전트 프로세스와 이 MCP 서버를 동일한 컨테이너 이미지에서 실행합니다.
기본 예:
FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN python -m pip install --upgrade pip && pip install ruff pytest
CMD ["python3", "binary_ninja_headless_mcp.py"]
컨테이너 내에서 실제 Binary Ninja 분석이 필요한 경우, 이 이미지에 Binary Ninja 런타임 및 라이선스 설정을 추가하고 이 MCP 서버가 구성된 에이전트를 시작합니다.
initializepingtools/listtools/callshutdowntools/list 동작:
offset 또는 limit이 제공되면 페이지 매김 출력을 사용합니다(페이지 모드에서 기본값 offset=0, limit=50).prefix(예: binary.)query(도구 이름/설명에 대한 부분 문자열 일치)offset, limit, total, has_more.has_more=true) next_offset 및 notice 힌트를 포함합니다.도구 호출 응답 동작:
structuredContent가 정식 전체 페이로드입니다.content[0].text는 간결한 요약 문자열입니다(전체 JSON 중복이 아닙니다).이 리포지토리는 잘 테스트되었으며 품질 게이트가 적용됩니다.
pytest --collect-only -q를 실행하여 현재 수집된 테스트 수를 확인합니다.ruff format --check .ruff check .pytestBINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1을 사용하므로 Binary Ninja 설치 없이 검사가 실행됩니다.read_only=true).binary.basic_blocks_at 및 function.basic_blocks는 페이지가 매겨집니다(offset/limit).memory.read는 하드 응답 제한이 있습니다: length <= 65536.stdio/tcp)은 기본적으로 인증되지 않습니다.binja.eval을 통해 임의 스크립팅을 노출하고 binja.call을 통해 광범위한 API 액세스를 노출합니다.ruff format --check .
ruff check .
BINARY_NINJA_HEADLESS_MCP_FAKE_BACKEND=1 pytest -q
내장 MCP 기능 퍼저를 사용하여 samples/ls에 대해 광범위한 도구 표면을 테스트합니다.
실제 Binary Ninja 백엔드:
python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --iterations 120 --seed 1337
가짜 백엔드 스모크 실행:
python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --fake-backend --iterations 20
JSON 커버리지 보고서 작성:
python3 -m binary_ninja_headless_mcp.fuzzer --binary samples/ls --report-json /tmp/mcp-fuzzer-report.json
유용한 플래그:
--min-success-tools N: 성공한 도구가 N개 미만이면 종료 코드 0이 아닌 값으로 종료합니다.--verbose: 퍼징하는 동안 각 도구 호출을 출력합니다.--update-analysis: update_analysis=true로 시드 세션을 엽니다.서버는 현재 36개의 기능 그룹에 걸쳐 181개의 도구를 노출합니다.
analysis.status: 분석 상태 조회.analysis.progress: 분석 진행 스냅샷 조회.analysis.update: 비동기 분석 업데이트 트리거.analysis.update_and_wait: 분석 업데이트 실행 후 완료 대기.analysis.abort: 분석 중단.analysis.set_hold: 분석 큐 보류/해제.annotation.rename_function: 함수 이름 변경.annotation.rename_symbol: 주소에 있는 심볼 이름 변경.annotation.undefine_symbol: 주소에 있는 사용자 심볼 해제.annotation.define_symbol: 주소에 심볼 정의.annotation.rename_data_var: 데이터 변수 이름 변경.annotation.define_data_var: 데이터 변수 정의.annotation.undefine_data_var: 데이터 변수 해제.annotation.set_comment: 주소에 주석 설정.annotation.get_comment: 주소에 있는 주석 조회.annotation.add_tag: 주소에 사용자 데이터 태그 추가.annotation.get_tags: 주소에 있는 태그 조회.arch.info: 아키텍처 및 플랫폼 메타데이터 조회.arch.disasm_bytes: 선택한 아키텍처로 바이트 디스어셈블.arch.assemble: 선택한 아키텍처로 명령어 텍스트 어셈블.baseaddr.detect: 기준 주소 탐지 실행.baseaddr.reasons: 기준 주소 탐지 이유 조회.baseaddr.abort: 기준 주소 탐지 중단.binary.summary: 바이너리/세션 요약 조회.binary.save: 현재 바이너리 뷰를 파일 경로에 저장.binary.functions: 페이지 매김으로 함수 목록 조회.binary.strings: 페이지 매김으로 발견된 문자열 목록 조회.binary.search_text: 세션에서 원시 텍스트/바이트 검색.binary.sections: 페이지 매김으로 섹션 목록 조회.binary.segments: 페이지 매김으로 세그먼트 목록 조회.binary.symbols: 페이지 매김으로 심볼 목록 조회.binary.data_vars: 페이지 매김으로 데이터 변수 목록 조회.binary.get_function_at: 주소로 함수 찾기.binary.get_function_disassembly_at: 주소를 포함하는 함수의 전체 디스어셈블리 조회.binary.get_function_il_at: 주소를 포함하는 함수의 전체 IL 조회.binary.functions_at: 주소에 있는 함수 목록 조회.binary.basic_blocks_at: 페이지 매김으로 주소에 있는 기본 블록 목록 조회.binja.info: Binary Ninja 버전/설치 정보 반환.binja.call: 일반 API 브리지: bn.* 또는 bv.* 대상 경로 호출.binja.eval: bn, sessions, 선택적 bv로 Python 코드 평가.data.typed_at: 주소에 있는 타입이 지정된 데이터 변수 조회.database.create_bndb: 세션에서 .bndb 생성.database.save_auto_snapshot: 자동 스냅샷 저장.database.info: 세션의 데이터베이스 상태 조회.database.snapshots: 데이터베이스 스냅샷 목록 조회.database.read_global: 데이터베이스 전역 문자열 키 읽기.database.write_global: 데이터베이스 전역 문자열 키 쓰기.debug.parsers: 이 뷰에 유효한 디버그 정보 파서 목록 조회.debug.parse_and_apply: 디버그 정보를 파싱하여 뷰에 적용.disasm.linear: 선형 디스어셈블리 라인 조회.disasm.function: 주소를 포함하는 함수의 전체 디스어셈블리 조회.disasm.range: 주소 범위 디스어셈블리 라인.external.library_add: 외부 라이브러리 추가.external.library_list: 외부 라이브러리 목록 조회.external.library_remove: 외부 라이브러리 제거.external.location_add: 외부 위치 매핑 추가.external.location_get: 외부 위치 매핑 조회.external.location_remove: 외부 위치 매핑 제거.