PyGhidra란
PyGhidra는 네이티브 CPython 3에서 Ghidra API를 사용하는 공식 라이브러리입니다. 프로젝트, 프로그램, 심볼과 분석 기능을 재현 가능한 Python 작업에 연결합니다.
Ghidra의 프로젝트와 프로그램을 직접 다루는 API이므로 설치 경로와 Python 환경을 고정하고, 실행 결과를 재현할 수 있도록 버전을 기록하세요.
요구 사항과 버전
현재 버전은 2026년 5월 14일 공개된 PyGhidra 3.1.0입니다. Python 3.9 이상, Ghidra 12.0 이상, JDK 21이 필요합니다.
여러 Ghidra를 함께 설치했다면 PyGhidra가 실제로 연결하는 Ghidra 루트와 JDK를 명시적으로 확인해야 합니다.
설치 방법
전용 가상 환경을 만들고 PyPI 또는 공식 Ghidra 배포본의 오프라인 패키지로 설치합니다. 제3자 EXE는 필요하지 않습니다.
온라인 설치와 오프라인 설치 중 하나를 선택하고, 가상 환경의 python과 pip가 같은 인터프리터를 가리키는지 확인하세요.
- 1
가상 환경
의존성을 분리합니다.
python -m venv .venv - 2
설치
활성화한 인터프리터로 설치합니다.
python -m pip install --upgrade pyghidra==3.1.0 - 3
오프라인 설치
공식 배포본의 번들 패키지를 사용합니다.
python -m pip install --no-index -f <GhidraInstallDir>/Ghidra/Features/PyGhidra/pypkg/dist pyghidra
Ghidra 연결
GHIDRA_INSTALL_DIR를 압축 해제한 Ghidra 루트로 설정하거나 pyghidra.start()에 install_dir를 전달합니다.
여러 Ghidra 버전이 있으면 경로를 고정하고, 시작 전에 해당 디렉터리에 Ghidra와 Features 폴더가 있는지 확인합니다.
GHIDRA_INSTALL_DIR=<path-to-ghidra-root>
첫 자동 분석
프로세스당 한 번 시작하고 분석 권한이 있는 샘플을 컨텍스트에서 열며 결과는 설치 폴더 밖에 저장합니다.
open_program 같은 컨텍스트 관리자를 사용해 리소스를 닫고, 원본 샘플과 생성된 프로젝트를 분리해 보관하세요.
from pathlib import Path
import pyghidra
with pyghidra.open_program(Path('sample.exe')) as api:
print(api.getCurrentProgram().getName())
자주 발생하는 문제
Python 실행 파일, java -version, Ghidra 루트와 호환성을 확인합니다. 외부 바이너리와 스크립트는 신뢰하지 않는 입력으로 처리합니다.
오류를 재현할 때 Python 버전, 패키지 버전, JDK와 GHIDRA_INSTALL_DIR 값을 함께 기록하면 환경 문제와 API 호환성 문제를 구분하기 쉽습니다.
| 증상 | 원인 | 확인 |
|---|---|---|
| 가져오기 오류 | 잘못된 환경 | python -m pip show pyghidra |
| Java 오류 | 잘못된 JDK | java -version |
| 경로 오류 | 잘못된 루트 | GHIDRA_INSTALL_DIR |
| API 불일치 | 버전 경계 | PyGhidra 3.x + Ghidra 12.0+ |
PyGhidra FAQ
PyGhidra는 Ghidra에 포함되어 있나요?
PyGhidra는 네이티브 CPython 3에서 Ghidra API를 사용하게 하는 공식 라이브러리이며, 공식 배포본의 번들이나 PyPI에서 설치할 수 있습니다.
어떤 Python 버전이 필요한가요?
Python 3.9 이상이 필요합니다.
Ghidra를 찾지 못하는 이유는 무엇인가요?
GHIDRA_INSTALL_DIR를 압축 해제한 Ghidra 루트로 설정하거나 pyghidra.start()에 install_dir를 전달하세요.
analyzeHeadless를 대체하나요?
아니요. PyGhidra는 Python에서 API를 조작하는 방식이고 analyzeHeadless는 명령줄 분석 작업에 적합하므로 파이프라인에 맞춰 선택하세요.
PyGhidra MCP와 같은 프로젝트인가요?
아니요. MCP 도구는 별도의 프로젝트이며 PyGhidra의 공식 패키지와 동일하지 않습니다.