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

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를 표준 설치 위치에서 찾으려고 시도합니다. 찾지 못한 경우 다음 환경 변수를 설정할 수 있습니다:

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개 도구)

내보내기

차이 분석

분석

보안

순위

호출 그래프

성능

메타데이터

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만 개 이상의 함수)

매우 큰 프로젝트를 처리할 때 Diaphora MCP는 특정 최적화를 적용합니다:

• 재귀 제한: Python 재귀 제한이 자동으로 100000으로 증가합니다(sys.setrecursionlimit). 큰 호출 그래프 탐색 중 크래시를 방지합니다.
• SQLite 트랜잭션 최적화: diaphora_config.py에서 COMMIT_AFTER_EACH_GUI_UPDATE = False로 설정하면 디스크 쓰기가 줄어 GUI 내보내기 속도가 2~3배 빨라집니다.
• Hex-Rays 마이크로코드: 역컴파일러가 엄격히 필요하지 않은 경우 마이크로코드 내보내기를 비활성화합니다(EXPORTING_USE_MICROCODE = False in Diaphora 설정).

IDA Pro MCP 통합

analyze_diff_results, compare_functions, find_function_match와 같은 도구는 주소와 경로를 포함한 ida_pro_mcp 블록을 반환합니다. 이 정보는 ida-pro-mcp 도구에 직접 전달할 수 있습니다:

┃ # 1. Diaphora가 의심스러운 함수를 찾음
┃ analyze_diff_results(results_path="diff.diaphora")
┃   → addr1="401000", db1="old.sqlite"
 
┃ # 2. IDA Pro MCP가 역컴파일
┃ decompile_function(address="401000")

예시

Diaphora MCP의 실제 작동을 보려면 다음 예시를 확인하십시오:

• Basic Session Transcript: 내보내기부터 함수 비교까지 모든 도구 호출에 대한 정확한 JSON 입/출력이 포함된 실제 MCP 세션 워크스루. 러시아어 버전도 있습니다.

AI 에이전트 지침 (중요)

이 프로토콜을 사용하는 AI 코딩 어시스턴트(예: Claude Code)라면 다음 호환성 규칙을 염두에 두십시오:

1. GUI vs. 헤드리스 내보내기 스키마:

   • 활성 GUI 세션(ida_mcp.py 플러그인)을 통한 내보내기는 calls, strings, structures 테이블을 포함하지만 program 테이블이 없는 사용자 정의 스키마를 생성합니다.
   • 헤드리스 내보내기(idat.exe 사용)는 program 테이블을 포함하는 공식 Diaphora 스키마를 생성합니다.
   • 중요: diff 엔진(diff_diaphora_dbs)은 공식 스키마를 필요로 합니다. 데이터베이스를 비교/차이 분석하려면 항상 헤드리스로 내보내십시오.

2. GUI에서 잠긴 데이터베이스:

   • GUI IDA Pro에서 현재 열려 있는 데이터베이스는 잠겨 있습니다. 헤드리스로 내보내려고 하면 실패합니다.
   • 현재 열려 있는 데이터베이스를 diff해야 하는 경우 사용자에게 GUI에서 닫거나(또는 더미 데이터베이스를 열어) 파일 잠금을 해제한 후 헤드리스 내보내기를 실행하도록 요청하십시오.

3. 데이터베이스 이름 충돌 방지:

   • Diaphora 내보내기 데이터베이스의 기본 이름은 <basename>.diaphora.sqlite입니다.
   • Diaphora 내보내기에 <basename>.sqlite를 사용하지 마십시오. 이는 ida-pro-mcp 감독자가 생성하는 내부 캐시 데이터베이스와 충돌합니다.

검증 상태 및 제한 사항

확인된 IDA Pro 9.3 픽스처는 회귀 테스트 스위트를 통과합니다: 16 passed, 1 xpassed. 두 SQLite3 DLL의 실제 스테이징 내보내기 및 Diaphora diff도 확인되었습니다. 대규모 또는 GUI에서 열린 IDB는 여전히 무료 IDA 잠금, 유효한 DIAPHORA_OUTPUT_ROOT, 충분히 큰 MCP 클라이언트 시간 초과가 필요합니다.

라이선스

MIT