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 조회.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: 외부 위치 매핑 제거.function.basic_blocks: 페이지 매김으로 함수 내 기본 블록 목록 조회.function.callers: 함수의 호출자.function.callees: 함수의 피호출자.function.variables: 함수 변수 목록 조회.function.var_refs: MLIL/HLIL에서 변수 참조 목록 조회.function.var_refs_from: 주소에서 시작하는 변수 참조 목록 조회.function.ssa_var_def_use: SSA 변수 정의 및 사용 조회.function.ssa_memory_def_use: 메모리 버전별 SSA 메모리 정의 및 사용 조회.function.metadata_store: 키로 함수 메타데이터 저장.function.metadata_query: 키로 함수 메타데이터 조회.function.metadata_remove: 키로 함수 메타데이터 제거.health.ping: 상태 확인.il.function: IL 함수 목록.il.instruction_by_addr: 소스 주소로 IL 명령어 조회.il.address_to_index: 주소를 IL 인덱스(들)로 매핑.il.index_to_address: IL 인덱스를 소스 주소로 매핑.il.rewrite.capabilities: 하나의 함수 및 IL 수준에 대한 IL 재작성 지원 목록 조회.il.rewrite.noop_replace: 널 연산 IL 표현식 대체 수행.il.rewrite.translate_identity: 동일 매핑 콜백으로 IL 변환.loader.rebase: BinaryView 재배치.loader.load_settings_types: 로더 설정 타입 이름 목록 조회.loader.load_settings_get: 로더 설정 값 조회.loader.load_settings_set: 하나의 로더 설정 값 설정.memory.read: 뷰에서 바이트 읽기(length <= 65536).memory.write: 바이트(16진수)를 뷰에 쓰기.memory.insert: 바이트(16진수)를 뷰에 삽입.memory.remove: 뷰에서 바이트 제거.memory.reader_read: BinaryReader를 통해 정수 값 읽기.memory.writer_write: BinaryWriter를 통해 정수 값 쓰기.mcp.response_format: 도구 결과 필드 설명(structuredContent 전체 페이로드, content[0].text 요약).metadata.store: 키로 메타데이터 저장.metadata.query: 키로 메타데이터 조회.metadata.remove: 키로 메타데이터 제거.patch.assemble: 주소에서 명령어 바이트 어셈블 및 패치.patch.status: 주소에서 패치 가능 여부 검사.patch.convert_to_nop: 지원되는 경우 명령어를 NOP으로 패치.patch.always_branch: 지원되는 경우 조건부 분기를 항상 분기로 패치.patch.never_branch: 지원되는 경우 조건부 분기를 절대 분기하지 않음으로 패치.patch.invert_branch: 지원되는 경우 조건부 분기를 반전시켜 패치.patch.skip_and_return_value: 지원되는 경우 명령어를 건너뛰고 값을 반환하도록 패치.plugin.valid_commands: 컨텍스트에 유효한 플러그인 명령어 목록 조회.plugin.execute: 컨텍스트에 유효한 플러그인 명령어 실행.plugin_repo.status: 플러그인 리포지토리 및 플러그인 상태 목록 조회.plugin_repo.check_updates: 플러그인 리포지토리 업데이트 확인.plugin_repo.plugin_action: 리포지토리 플러그인에 설치/제거/활성화/비활성화 작업 실행.project.create: 프로젝트 생성.project.open: 프로젝트 열기.project.close: 추적 중인 프로젝트 닫기.project.list: 프로젝트 폴더/파일 목록 조회.project.create_folder: 프로젝트 폴더 생성.project.create_file: base64 데이터에서 프로젝트 파일 생성.project.metadata_store: 프로젝트 메타데이터 저장.project.metadata_query: 프로젝트 메타데이터 조회.project.metadata_remove: 프로젝트 메타데이터 제거.search.data: 원시 바이트 패턴(16진수 문자열) 검색.search.next_text: 다음 텍스트 일치 항목 찾기.search.all_text: 범위 내 모든 텍스트 일치 항목 찾기(정규식 선택 사항).search.next_data: 다음 데이터/바이트 패턴 일치 항목 찾기.search.all_data: 범위 내 모든 데이터/바이트 패턴 일치 항목 찾기.search.next_constant: 다음 상수 발생 찾기.search.all_constant: 범위 내 모든 상수 발생 찾기.section.add_user: 사용자 섹션 추가.section.remove_user: 사용자 섹션 제거.segment.add_user: 사용자 세그먼트 추가.segment.remove_user: 사용자 세그먼트 제거.session.open: 바이너리를 열고 세션 생성.session.open_bytes: base64로 인코딩된 바이트로 바이너리 세션 열기.session.open_existing: 기존 세션의 파일에서 다른 세션 열기.session.close: 열려 있는 세션 하나 닫기.session.list: 열려 있는 세션 목록 조회.session.mode: 세션 안전/결정론 모드 조회.session.set_mode: 세션 안전/결정론 모드 업데이트.task.analysis_update: 비동기 분석 업데이트 작업 시작.task.search_text: 비동기 검색 작업 시작.task.status: 작업 상태 조회.task.result: 작업 결과 조회.task.cancel: 작업 취소(최선 노력).transform.inspect: 변환 추출 파이프라인 검사/처리.type.parse_string: 단일 타입 문자열 파싱.type.parse_declarations: C 선언문에서 타입/변수/함수 파싱.type.define_user: 타입 소스에서 사용자 타입 정의.type.rename: 타입 이름 변경.type.undefine_user: 사용자 타입 해제.type.import_library_type: 타입 라이브러리에서 타입 가져오기.type.import_library_object: 타입 라이브러리에서 객체 타입 가져오기.type.export_to_library: 타입을 타입 라이브러리로 내보내기.type_archive.create: 타입 아카이브 생성 및 선택적으로 연결.type_archive.open: 타입 아카이브 열기 및 선택적으로 연결.type_archive.list: 연결된 타입 아카이브 목록 조회.type_archive.get: 추적 중인 하나의 타입 아카이브 조회.type_archive.pull: 타입 아카이브에서 타입 가져오기.type_archive.push: 타입 아카이브로 타입 내보내기.type_archive.references: 하나의 타입에 대한 아카이브의 내부/외부 참조 조회.type_library.create: 타입 라이브러리 생성 및 선택적으로 연결.type_library.load: 타입 라이브러리 로드 및 선택적으로 연결.type_library.list: 뷰에 연결된 타입 라이브러리 목록 조회.type_library.get: 추적 중인 하나의 타입 라이브러리 조회.uidf.parse_possible_value: 사용자 정보 가능 값 집합 문자열 파싱.uidf.set_user_var_value: 함수 사용자 변수 값 설정.uidf.clear_user_var_value: 함수 사용자 변수 값 지우기.uidf.list_user_var_values: 함수에 대한 모든 사용자 변수 값 목록 조회.undo.begin: 실행 취소 트랜잭션 시작.undo.commit: 실행 취소 트랜잭션 커밋.undo.revert: 실행 취소 트랜잭션 되돌리기.undo.undo: 실행 취소 수행.undo.redo: 다시 실행 수행.value.reg: 주소 이후/에서 레지스터 값 조회.value.stack: 주소 이후/에서 스택 내용 조회.value.possible: 주소에서 IL 가능 값 집합 조회.value.flags_at: 주소에서 리프트된 IL 플래그 읽기/쓰기 상태 조회.workflow.list: 등록된 워크플로 목록 조회.workflow.describe: 워크플로 토폴로지 및 설정 설명.workflow.clone: 워크플로 복제.workflow.insert: 활동 앞에 활동 삽입.workflow.insert_after: 활동 뒤에 활동 삽입.workflow.remove: 워크플로 활동 제거.workflow.graph: 워크플로 그래프 요약.workflow.machine.status: 워크플로 머신 상태 조회.workflow.machine.control: 워크플로 머신 런타임 제어.xref.code_refs_to: 주소에 대한 코드 참조.xref.code_refs_from: 주소로부터의 코드 참조.xref.data_refs_to: 주소에 대한 데이터 참조.xref.data_refs_from: 주소로부터의 데이터 참조.더 많은 정보를 원하시면 Tim Blazytko(@mr_phrazer)에게 문의하십시오.
binary.functions_at: 주소에 있는 함수 목록 조회.binary.basic_blocks_at: 페이지 매김으로 주소에 있는 기본 블록 목록 조회.