Читать на русском языке

Diaphora MCP

Diaphora MCP는 바이너리 자동 diffing을 위한 MCP(Model Context Protocol) 서버입니다. MCP 프로토콜을 통해 Diaphora(diff 엔진)와 IDA Pro(디스어셈블러)를 연결하여 AI 에이전트(예: Claude Code)가 바이너리 파일 비교, 보안 패치 탐색, 변경 분석을 수행할 수 있게 합니다.

기능

• 내보내기(Export): 분석된 .i64 / .idb 데이터베이스를 Diaphora SQLite 형식으로 변환합니다(idat.exe 헤드리스 모드 사용)
• 차이 분석(Diffing): 내보낸 두 데이터베이스를 비교하고, 일치 유형 및 비율로 결과를 필터링합니다
• 취약점 분석(Vulnerability Analysis): 키워드 매칭과 휴리스틱을 사용하여 보안 관련 변경 사항을 검색합니다
• 패치 감지(Patch Detection): 새로운 경계 검사, null 검사, 오류 처리, 암호화 변경 사항을 자동으로 감지합니다
• 순위(Ranking): CFG, 복잡성 점프, 보안 지표를 기반으로 변경된 함수를 중요도별로 순위를 매깁니다
• 호출 그래프(Call Graph): 호출 경로(BFS, 최대 N 레벨)를 비교하고, 호출 연쇄에서 근본 원인 변경을 감지합니다
• 메타데이터 전송(Metadata Transfer): 데이터베이스 간 이름, 주석, 프로토타입 전송을 준비합니다
• IDA Pro MCP 통합: 모든 도구는 IDA Pro MCP 도구에 직접 전달할 수 있는 주소와 데이터베이스 경로를 반환합니다

설치

1. 종속성

• Python 3.10+
• IDA Pro 8.x / 9.x (헤드리스 내보내기 시 idat.exe 필요)
• Diaphora 플러그인이 IDA에 설치되어 있어야 함
• Claude Code (또는 MCP 호환 클라이언트)

2. 패키지 설치

git clone https://github.com/xTeardx/diaphora-mcp.git
cd diaphora-mcp
pip install -e .

3. 경로 설정

패키지는 자동으로 IDA Pro와 Diaphora를 표준 설치 위치에서 찾으려고 시도합니다. 찾지 못한 경우 다음 환경 변수를 설정할 수 있습니다:

변수	설명	예시
IDAT_PATH	idat.exe의 전체 경로	C:\Program Files\IDA Pro 9.3\idat.exe
DIAPHORA_DIR	diaphora.py가 있는 폴더	C:\Program Files\IDA Pro 9.3\plugins\diaphora-3.4.1
DIAPHORA_OUTPUT_ROOT	새 내보내기 파일이 허용되는 루트 디렉터리	D:\\diaphora-outputs
DIAPHORA_PYTHON	diff에 사용할 Python 인터프리터	/usr/bin/python3 (기본값: sys.executable)

Claude Code의 경우 ~/.claude.json(또는 MCP 클라이언트의 해당 설정 파일)에서 지정할 수 있습니다:

{
  "mcpServers": {
    "diaphora": {
      "command": "python",
      "args": ["path/to/repo/diaphora_mcp_server.py"],
      "env": {
        "IDAT_PATH": "C:\\Program Files\\IDA Pro 9.3\\idat.exe",
        "DIAPHORA_DIR": "C:\\Program Files\\IDA Pro 9.3\\plugins\\diaphora-3.4.1"
      },
      "timeout": 7200
    }
  }
}

참고: 매우 큰 바이너리(>100 MB)의 경우 timeout을 최소 7200(2시간)으로 설정하세요.

3.1. Codex와 헤드리스 IDA MCP

Codex는 일반적으로 두 개의 보완 MCP 서버를 사용합니다:

• diaphora-mcp — 이 프로젝트: 내보내기, Diaphora diff, 결과 분석;
• ida-pro-mcp — 업스트림 IDA 검사 서버: idb_open, 역컴파일, 주소 수준 분석.

idalib-mcp는 ida-pro-mcp의 헤드리스 백엔드이며, 별도의 Diaphora 서버가 아닙니다. 설치 후 Codex를 재시작합니다:

uv run ida-pro-mcp --install codex --transport streamable-http --scope global --ida-rpc http://127.0.0.1:8745/mcp

이 프로젝트의 경우 stdio 설정으로 충분합니다:

[mcp_servers.diaphora-mcp]
command = "python"
args = ["D:\\path\\to\\diaphora-mcp\\diaphora_mcp_server.py"]
startup_timeout_sec = 120

4. diff를 위한 데이터베이스 준비

IDA Pro는 먼저 바이너리를 분석하여 .i64 또는 .idb 파일을 생성해야 합니다. 그 후:

┃ export_idb_to_diaphora(idb_path="old_version.i64")
┃ export_idb_to_diaphora(idb_path="new_version.i64")

또는 한 명령으로 전체 파이프라인 실행:

┃ batch_export_and_diff(idb1="old.i64", idb2="new.i64")

.i64를 결과 도구에 직접 전달하지 마십시오. 이는 IDA 데이터베이스일 뿐 SQLite가 아닙니다. 먼저 내보내십시오.

빠른 시작

┃ # 1. 전체 파이프라인: 두 개의 .i64 내보내기 → diff → 요약 보고서
┃ batch_export_and_diff(idb1="v1.0.i64", idb2="v1.1.i64")
 
┃ # 2. 데이터베이스가 이미 내보내진 경우
┃ diff_diaphora_dbs(db1="v1.0.sqlite", db2="v1.1.sqlite")
 
┃ # 3. diff 결과 보안 분석
┃ analyze_diff_results(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 4. 변경 사항 중요도 순위
┃ rank_changes(results_path="v1.0_vs_v1.1.diaphora", top_n=20)
 
┃ # 5. 근본 원인 변경 찾기
┃ find_patch_root(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 6. 보안 패치 감지
┃ detect_security_patches(results_path="v1.0_vs_v1.1.diaphora")
 
┃ # 7. 전체 보고서 생성
┃ summarize_patch(results_path="v1.0_vs_v1.1.diaphora")

예시 (라이브 세션 기록)

전체 단계별 기록은 **examples/basic-session.md**를 참조하십시오. 두 개의 IDB 데이터베이스 내보내기부터 개별 함수 비교까지의 실제 Diaphora MCP 세션을 보여줍니다. 러시아어 버전도 있습니다.

다음은 서버가 반환하는 내용의 미리보기입니다:

입력 — 두 개의 SQLite3 DLL 비교(2015 vs 2023):

{"idb1_path": "old.i64", "idb2_path": "new.i64", "use_decompiler": false}

출력 — 내보내기 + diff 후 요약:

{
  "best_matches": 60,
  "partial_matches": 993,
  "multimatches": 52,
  "unmatched_primary": 2647
}

세션은 6개의 MCP 도구 호출을 진행하며, 각 단계의 정확한 JSON 입/출력과 에이전트의 추론을 함께 보여줍니다.

단일 데이터베이스 조사

┃ # 데이터베이스 내보내기 정보 가져오기
┃ get_export_info(db_path="app.sqlite")
 
┃ # 함수 검색
┃ search_export_db(db_path="app.sqlite", name_pattern="%crypt%", min_instructions=50)
 
┃ # 의사 코드 검색
┃ get_function_pseudocode(db_path="app.sqlite", address="401000")

프로젝트 구조

diaphora-mcp/
├── diaphora_mcp_server.py          # 메인 진입점
├── diaphora_mcp/
│   ├── diaphora_mcp_server.py      # MCP 도구 등록
│   ├── config.py                   # 경로 설정 및 자동 감지
│   ├── models.py                   # 상수 및 모델
│   ├── core/
│   │   ├── export.py               # 헤드리스 내보내기, 배치 파이프라인
│   │   ├── diff.py                 # Diff 및 .diaphora 결과 리더
│   │   ├── analysis.py             # 함수 검색, 비교, 설명
│   │   ├── security.py             # 키워드 매칭, 패치 감지
│   │   ├── ranking.py              # 중요도 순위
│   │   ├── graph.py                # 호출 그래프, BFS 호출 트리, 근본 원인
│   │   ├── metadata.py             # 메타데이터 준비(이름, 주석)
│   │   └── report.py               # 전체 패치 보고서 생성
│   └── utils/
│       ├── sqlite.py               # SQLite 도우미
│       ├── format.py               # 의사 코드 diff, 특징 벡터 추출
│       └── log.py                  # 내보내기 로깅 유틸리티
├── _diaphora_headless.py           # idat.exe -S 씬 래퍼
└── logs/                           # 자동 내보내기 로그 (동적 생성)

MCP 도구 참조 (21개 도구)

내보내기

도구	설명
export_idb_to_diaphora	.i64/.idb 데이터베이스를 IDA 헤드리스를 사용하여 SQLite 형식으로 내보내기
batch_export_and_diff	전체 파이프라인: 기본 내보내기 → 보조 내보내기 → diff → 요약

차이 분석

도구	설명
diff_diaphora_dbs	두 개의 내보내진 Diaphora SQLite 데이터베이스 diff
get_diff_results	필터링으로 .diaphora diff 파일 읽기
get_diff_summary	일치 통계 반환

분석

도구	설명
analyze_diff_results	보안 키워드 및 필터를 사용하여 결과 검사
compare_functions	두 데이터베이스에서 함수의 나란히 비교
find_function_match	신뢰도 지표와 함께 두 번째 바이너리에서 함수 일치 찾기
explain_similarity	유사성 요소(니모닉, CFG, 상수, 프로토타입, 해시) 분석
detect_behavior_change	함수 로직 변경에 대한 자연어 요약 제공
summarize_patch	포괄적인 업데이트 보고서 생성
search_export_db	이름/명령어/복잡성으로 내보내진 함수 검색
get_function_pseudocode	함수의 의사 코드 및 메타데이터 가져오기
get_export_info	일반 데이터베이스 메타데이터 검색

보안

도구	설명
detect_security_patches	보안 수정 사항 감지(경계 검사, 메모리 안전, 안티디버그 등)

순위

도구	설명
rank_changes	변경된 함수를 중요도별로 순위 지정(0-100 점수)

호출 그래프

도구	설명
get_changed_callgraph	함수의 들어오고 나가는 호출 비교
compare_call_path	함수에서 호출 그래프 탐색(BFS 호출 경로 비교, 최대 N 레벨)
find_patch_root	호출 연쇄를 유발하는 근본 원인 함수 감지

성능

도구	설명
performance_report	집계된 메모리, 캐시 및 연결 통계 반환

메타데이터

도구	설명
transfer_metadata	대량 전송을 위한 이름, 주석, 프로토타입 준비

IDA Pro GUI 통합 (XML-RPC 브리지)

이 프로젝트는 실행 중인 GUI IDA Pro 세션과의 통합을 내장하여, 데이터베이스 잠금 충돌 없이 활성 IDA 창에서 직접 즉시 내보내기가 가능합니다.

1. 자동 시작: diaphora_gui_listener.py를 IDA Pro의 plugins/ 디렉터리에 복사하면, IDA가 시작될 때 백그라운드 XML-RPC 서버가 포트 28652에서 자동 시작됩니다.
2. 스마트 내보내기: export_idb_to_diaphora를 호출하면 MCP 서버가 포트 28652를 확인합니다. 활성 세션이 있으면 GUI에서 직접 내보내기를 실행합니다. 그렇지 않으면 idat.exe를 통한 헤드리스 백그라운드 실행으로 자동 대체됩니다.

브리지 구성에 대한 자세한 지침은 GUI_INSTRUCTIONS.md를 참조하십시오.

대규모 데이터베이스 처리 (10만 개 이상의 함수)