ida-cli

macOS 및 Linux에서 바이너리 분석을 위한 헤드리스 IDA CLI 및 스킬 우선(skill-first) 툴킷. ida-cli는 런타임 백엔드를 자동 선택하고, 필요 시 로컬 서버를 자동 시작하며, 플랫 CLI, stdio MCP 전송(transport), Streamable HTTP MCP 전송(transport)으로 동일한 표면(surface)을 노출합니다.

中文说明

두 가지 사용자용 진입점

• 로컬 ida-cli 바이너리(단일 실행 파일에 클라이언트 + 서비스 포함)
• 에이전트 환경용으로 설치 가능한 ida-cli 스킬(skill/SKILL.md)

기본 워커 / 라우터 서비스 계층은 CLI에 의해 자동으로 시작되고 종료됩니다. 실제로 장기 실행되는 외부 접근 가능 서비스가 필요할 때만 serve / serve-http를 명시적으로 실행하면 됩니다.

지원 매트릭스

호스트 플랫폼

• 지원: macOS, Linux
• 미지원: Windows

IDA 런타임 정책

백엔드 선택은 probe-runtime에 의해 런타임에 이루어집니다. 번들된 네이티브 계층이 SDK에 링크되어 있으므로 빌드에는 여전히 IDA SDK가 필요합니다. 런타임 시 CLI는 IDADIR 또는 정규화된(normalized) 일반 설치 경로에서 IDA 자체를 엽니다.

현재 기능

지원되는 IDA 9.x 런타임에서 ida-cli는 다음을 수행할 수 있습니다:

• 원시(raw) PE / ELF / Mach-O 바이너리를 열고 캐시된 .i64 데이터베이스를 재사용합니다
• 함수를 나열하고 확인하며, 주소 또는 이름으로 디스어셈블하고, Hex-Rays를 통해 디컴파일합니다
• 세그먼트, 문자열, 임포트, 익스포트, 엔트리 포인트, 전역 심볼을 조회합니다
• 주소 ↔ 세그먼트 / 함수 / 심볼 컨텍스트를 확인합니다
• 바이트 / 문자열 / 정수를 읽고 read_* 및 convert_number 헬퍼를 적용합니다
• 주소에 대한/로부터의 xref(교차 참조)를 조회합니다(문자열 및 구조체 필드에 대한 xref 포함)
• 콜그래프(callgraph), 기본 블록, 제어 흐름 경로를 구축합니다
• 텍스트, 즉치값(immediate), 바이트, 명령어, 피연산자, 의사 코드(pseudocode)를 검색합니다
• 타입을 선언/적용하고, 심볼과 로컬 변수의 이름을 변경하며, 주석을 설정합니다
• run_script를 통해 IDAPython 스니펫을 실행합니다

미해결 항목: 일부 쓰기 중심(write-heavy) 및 고급 타입 편집 작업은 idat-compat에서 아직 부분적으로만 지원됩니다. 생성된 도구 목록은 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 설치(선택 사항)

스킬을 거치지 않고 독립 실행형 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 파일에 추가합니다.
• IDASDKDIR 또는 IDALIB_SDK가 설정되지 않았고 로컬 빌드가 필요한 경우, 설치 프로그램은 오픈소스 HexRaysSA/ida-sdk를 자동으로 클론합니다.
• IDA 설치가 여러 개 있는 경우, ida-cli를 설치하거나 실행하기 전에 IDADIR을 명시적으로 export하세요.

소스에서 빌드

git clone https://github.com/cpkt9762/ida-cli.git
cd ida-cli

export IDADIR="/Applications/IDA Professional 9.4.app/Contents/MacOS"   # or a Linux install
export IDASDKDIR="/path/to/ida-sdk"                                     # root or ida-sdk/src

cargo build --bin ida-cli
./target/debug/ida-cli --help

CLI 사용

ida-cli는 클라이언트 우선(client-first)입니다. 모든 클라이언트 하위 명령은 임의의 포트에 바인딩된 로컬 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"}}'

첫 번째 인수가 서비스 하위 명령(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

백엔드 프로브 출력 예시:

{"runtime":{"major":9,"minor":1,"build":250226},"backend":"idat-compat","supported":true,"reason":null}

{"runtime":{"major":9,"minor":4,"build":260610},"backend":"native-linked","supported":true,"reason":null}

전체 CLI 표면은 skill/references/cli-tool-reference.md를 참조하세요.

빌드 요구 사항

• Rust 1.87+
• LLVM / Clang
• macOS 또는 Linux 호스트
• IDADIR를 통한 IDA 설치(런타임 지원은 IDA 9.0부터)
• IDASDKDIR 또는 IDALIB_SDK를 통한 IDA SDK

SDK 경로는 다음 레이아웃 중 하나를 가리킬 수 있습니다:

• /path/to/ida-sdk
• /path/to/ida-sdk/src

런타임 참고 사항

idat-compat

IDA 9.0–9.2 호환성 백엔드입니다. idat를 외부 프로세스로 실행(shell out)하여 짧은 IDAPython 스크립트를 실행하고 구조화된 JSON을 CLI 런타임으로 반환합니다.

native-linked

IDA 9.3+ 백엔드입니다. 번들된 idalib 라인에 링크하고 데이터베이스를 프로세스 내(in-process)에서 엽니다.

캐시 및 로컬 런타임 경로

• 데이터베이스 캐시: ~/.ida/idb/
• 로그: ~/.ida/logs/server.log
• 서버 Unix 소켓: ~/.ida/server.sock
• 서버 PID 파일: ~/.ida/server.pid
• CLI 검색 파일(플랫 CLI를 활성 소켓에 매핑): /tmp/ida-cli.socket
• 대용량 JSON 응답 캐시: /tmp/ida-cli-out/

CI 및 릴리스

GitHub Actions는 오픈소스 HexRaysSA/ida-sdk를 대상으로 호스팅 러너에서 트리를 컴파일하고 테스트하므로 CI는 어떤 개인 머신 레이아웃에도 의존하지 않습니다.

현재 워크플로 동작:

• master에 대한 푸시 및 풀 리퀘스트는 검증을 실행합니다
• v0.9.3 같은 태그가 지정된 푸시는 Linux 및 macOS용 릴리스 아카이브를 빌드합니다
• 릴리스는 install.sh와 플랫폼 아카이브를 첨부합니다

릴리스 바이너리는 SDK 스텁을 대상으로 빌드됩니다. 설치 시 install.sh가 생성한 런처는 ida-cli를 호출하기 전에 IDADIR 또는 정규화된 일반 설치 경로 집합을 통해 로컬 IDA 런타임을 확인합니다.

문서

• docs/BUILDING.md — 소스에서 빌드
• docs/ARCHITECTURE.md — 라우터, 백엔드, 페더레이션
• docs/TRANSPORTS.md — stdio, 스트리머블 HTTP, 멀티 IDB
• docs/TOOLS.md — 생성된 도구 카탈로그
• docs/TESTING.md — 통합 및 단위 테스트
• skill/SKILL.md — 스킬 부트스트랩 및 사용 정책
• skill/references/cli-tool-reference.md — 전체 CLI 표면

라이선스

MIT