
idalib 기반의 AI 지원 바이너리 분석을 위한 헤드리스 IDA Pro MCP 서버
macOS 및 Linux에서 바이너리 분석을 위한 헤드리스 IDA CLI 및 스킬 우선 툴킷입니다. ida-cli는 런타임 백엔드를 자동 선택하고, 필요할 때 로컬 서버를 자동 시작하며, 플랫 CLI, stdio MCP 전송, Streamable HTTP MCP 전송과 동일한 표면을 노출합니다.
ida-cli 바이너리 (클라이언트 + 서비스를 하나의 실행 파일로 제공)ida-cli 스킬 (skill/SKILL.md)기반이 되는 워커 / 라우터 서비스 계층은 CLI가 자동으로 시작하고 종료합니다. 장기 실행되며 외부에서 접근 가능한 서비스가 실제로 필요할 때만 serve / serve-http를 명시적으로 실행하면 됩니다.
런타임 요구 사항: IDA 9.4/9.5 및 Python >=3.11. 모든 데이터베이스 작업은 전용으로 고정된 Nexus 0.13.4 / Domain 0.5.1 환경을 사용합니다. 누락된 의존성이나 패치 불일치는 명시적으로 실패합니다. Rust 빌드에는 IDA SDK가 필요하지 않습니다.
지원되는 IDA 9.x 런타임에서 ida-cli는 다음을 수행할 수 있습니다:
.i64 데이터베이스를 재사용read_* 및 convert_number 헬퍼 적용run_script를 통한 IDAPython 스니펫 실행모든 도구는 명시적 기능 오류와 함께 Nexus를 사용합니다. 생성된 도구 목록은 docs/TOOLS.md를 참조하세요.
기본 진입점은 수동 CLI 설치가 아니라 ida-cli 스킬입니다.
# list the skill exposed by this repository
npx -y skills add https://github.com/cpkt9762/ida-cli --list
# install the ida-cli skill for Codex
npx -y skills add https://github.com/cpkt9762/ida-cli --skill ida-cli --agent codex --yes --global
설치 후, 스킬은 자체 부트스트랩 래퍼를 함께 제공합니다:
~/.agents/skills/ida-cli/scripts/ida-cli.sh --help
~/.agents/skills/ida-cli/scripts/ida-cli.sh probe-runtime
~/.agents/skills/ida-cli/scripts/ida-cli.sh --path /path/to/binary list-functions --limit 20
ida-cli가 없으면 래퍼가 명령을 전달하기 전에 저장소 설치 프로그램을 통해 이를 설치합니다.
스킬을 거치지 않고 독립 실행형 CLI를 사용하려는 경우에만 사용하세요.
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --add-path
유용한 변형:
# install a specific release
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --tag v0.9.3 --add-path
# build directly from a branch or ref
curl -fsSL https://raw.githubusercontent.com/cpkt9762/ida-cli/master/scripts/install.sh | bash -s -- --ref master --build-from-source --add-path
참고:
~/.local/bin/ida-cli에 배치합니다.--add-path는 해당 bin 디렉터리를 셸 rc 파일에 추가합니다./Applications 또는 ~/Applications 아래에서 가장 최신 숫자 버전의 .app을 선택하고, 선택된 후보와 다른 후보들을 출력합니다. 9.10은 9.9보다 최신입니다. 끝의 0 구성 요소는 동일하게 취급되며, 동점일 경우 정규 경로 순서로 결정됩니다. 명시적 IDADIR이 우선합니다. 호환되지 않는 선택된 wheel/런타임은 명시적으로 실패합니다. 후보를 찾지 못하면 설치가 실패하며 IDADIR을 설정하라는 안내가 표시됩니다.IDADIR이 이를 재정의하며, .app, Contents, 런타임 경로가 허용됩니다. 버전 비교 및 런타임 검사를 참조하세요.git clone https://github.com/cpkt9762/ida-cli.git
cd ida-cli
export IDADIR="/Applications/IDA Professional 9.5.app/Contents/MacOS" # or a Linux install
cargo build --bin ida-cli
./target/debug/ida-cli --help
ida-cli는 클라이언트 우선 방식입니다. 모든 클라이언트 하위 명령은 무작위 포트에 바인딩된 로컬
Streamable-HTTP 서버를 자동으로 시작하고 검색을 위해
/tmp/ida-cli.socket을 기록합니다:
./target/debug/ida-cli --path /path/to/sample.bin list-functions --limit 20
./target/debug/ida-cli --path /path/to/sample.bin decompile --addr 0x140001000
./target/debug/ida-cli --path /path/to/sample.bin raw '{"method":"get_xrefs_to","params":{"address":"0x140001000"}}'
데몬이 현재 열어 두고 있는 데이터베이스와 이를 보유한 클라이언트를 확인하려면 list-idbs를 실행한다(MCP 도구: list_idbs). 예를 들어 idat으로 .i64를 다시 빌드하거나 교체하기 전에 이를 실행한다. 여전히 목록에 있는 데이터베이스는 데몬이 열어 두고 있는 것이며, idat은 다른 곳에서 열려 있는 데이터베이스에서 실패한다. 응답은 {"count": N, "idbs": [...]}이며, 각 항목에는 db_handle, 입력 경로와 .i64 경로, 이를 연 클라이언트의 불투명 ID, 열린 시각, 워커 프로세스, 활성 데이터베이스 여부, 그리고 여전히 참조를 보유한 클라이언트가 포함된다. 닫기 토큰은 절대 반환되지 않는다.
./target/debug/ida-cli list-idbs --json
각 의사코드 줄 뒤의 주소를 얻으려면 decompile에 --line-addresses를 추가하세요 (MCP 및 RPC: decompile_function에서 line_addresses: true). 응답은 {"code": ..., "lines": [...]} 형태가 됩니다. code는 일반적인 텍스트이고, 각 lines 항목은 {"line", "text", "addresses"}입니다. line은 1부터 시작하며, text는 code의 해당 줄이고, addresses는 Hex-Rays가 해당 줄에 앵커링한 ctree 항목의 IDA 주소(16진수 문자열, 오름차순, 중복 없음)입니다. 한 줄이 여러 개의 비연속 주소에 매핑될 수 있으며, 이 목록은 해당 문장의 모든 명령어를 포함하지는 않습니다. 함수 시그니처와 지역 변수 선언에는 주소가 없습니다. {, }, else 및 빈 줄은 해당 줄을 소유한 블록이나 if의 주소를 가질 수 있습니다 (가장 바깥쪽 중괄호의 경우 함수 진입점). 이 모드에서는 sub_ 이름 변경 힌트가 추가되지 않습니다. Hex-Rays는 매우 큰 함수를 호출할 때마다 다르게 출력할 수 있으므로, 동일한 응답의 code와 lines만 함께 사용하세요. Nexus는 이 모드를 지원합니다. CLI 소켓을 통해서는 큰 응답이 다른 경우와 마찬가지로 응답 캐시에 저장됩니다 (IDA_MCP_MAX_INLINE_BYTES).
{"line": 6, "text": " while ( a1 != 1 )", "addresses": ["0x10000033c", "0x100000340"]}
첫 번째 인자가 서비스 하위 명령(serve, serve-http, serve-worker, probe-runtime)인 명령은 대신 서비스 모드로 진입합니다:
./target/debug/ida-cli serve # stdio MCP transport
./target/debug/ida-cli serve-http --bind 127.0.0.1:8765
./target/debug/ida-cli probe-runtime
probe-runtime은 Nexus 의존성, 패치 및 프로토콜 준비 상태를 확인하며, 불일치가 있으면 0이 아닌 값으로 종료합니다.
전체 CLI 표면은 skill/references/cli-tool-reference.md를 참조하십시오.
IDADIR을 통한 IDA 설치 (런타임 지원은 IDA 9.4부터 시작)런처는 전용 Python 환경을 찾으며, 소스 빌드에서는 IDA_NEXUS_PYTHON을 설정할 수 있습니다. 오프라인 sBPF/DSC 준비는 여전히 sbx/idat을 사용하고, 일반 쿼리, 편집 및 데이터베이스 세션은 Nexus를 사용합니다. 롤백은 고정된 N0 실행 파일과 별도의 복구 디렉터리에 있는 폐쇄된 마이그레이션 전 백업을 사용합니다. 실제 환경을 설치하거나 전환하려면 명시적인 승인이 필요합니다.
~/.ida/idb/~/.ida/logs/server.log~/.ida/server.sock~/.ida/server.pid/tmp/ida-cli.socket/tmp/ida-cli-out/GitHub Actions는 호스팅 러너에서 오픈소스 HexRaysSA/ida-sdk를 대상으로 트리를 컴파일하고 테스트하므로, CI는 어떤 사설 머신 레이아웃에도 의존하지 않습니다.
현재 워크플로 동작:
master에 대한 푸시 및 풀 리퀘스트는 검증을 실행v0.9.3과 같은 태그 푸시는 Linux 및 macOS용 릴리스 아카이브를 빌드install.sh와 플랫폼 아카이브가 첨부됨릴리스 바이너리는 IDA 링크가 없습니다. 설치 프로그램은 고정된 4개 패치 Nexus Python 환경을 생성하고 직접 찾습니다.
MIT
제거된 구성은 CLI 데몬 검색 또는 서버 시작 전에 오류로 처리됩니다(빈 값이라도 마찬가지): IDA_CLI_NEXUS_DEV, IDA_CLI_WORKER_BACKEND, IDA_CLI_SDK_VERSION, IDA_CLI_MAX_WORKERS, IDA_CLI_MAX_WORKERS_PER_TENANT, IDA_CLI_MAX_PENDING_PER_WORKER, IDA_CLI_MAX_CONCURRENT_SPAWNS. 이 변수들을 제거하십시오. Nexus 제한에는 해당하는 IDA_CLI_MAX_PENDING_PER_TENANT, IDA_CLI_NEXUS_RETENTION_CAPACITY 또는 IDA_CLI_HELPER_CAPACITY를 사용하십시오. 이들은 독립적인 제한이며 워커 수를 직접 대체하는 것이 아닙니다.