Ghidra 헤드리스 분석기란 무엇이며 언제 사용하는가
Ghidra 헤드리스 분석기는 데스크톱 화면을 열지 않고 분석을 실행하는 명령줄 진입점입니다. 프로젝트를 새로 만들거나 보완하고, 가져온 프로그램 또는 기존 프로그램을 분석하며, 샘플 폴더·펌웨어 트리아지·예약 보고서·관리된 빌드 파이프라인을 위해 GUI 없는 스크립트를 실행할 수 있습니다.
헤드리스 실행은 원격 서버가 아니며 모든 결론을 자동으로 만들어 주는 기능도 아닙니다. 실행 파일은 Ghidra 설치 상태, 프로젝트 위치, 로더, 분석기, 스크립트와 일반 프로젝트 규칙에 계속 의존합니다. 릴리스, 입력 목록, 옵션, 출력 프로젝트와 로그를 기록하고, 권한을 확인한 자료만 분석하세요.
사용 가능한 옵션은 공식 문서와 설치된 릴리스에 포함된 support/analyzeHeadless 실행 파일에서 확인합니다. 이 페이지는 안전한 작업 흐름을 설명하지만 설치된 Ghidra 버전의 도움말을 대신하지 않습니다.
설치, 프로젝트와 입력 파일 준비하기
공식 Ghidra ZIP과 호환되는 64비트 JDK로 시작하세요. 이 사이트가 확인한 버전은 2026년 8월 18일 공개된 Ghidra 12.1.3이며, 압축 파일의 support/ 폴더에 실행 파일이 포함되어 있습니다. 데스크톱 프로그램이 시작되지 않으면 Ghidra 설치 가이드를 먼저 확인하세요. 잘못된 JDK나 불완전한 압축 해제는 헤드리스 실행도 실패하게 합니다.
애플리케이션, 프로젝트, 입력 및 보고서 폴더를 분리하세요. 진단 중에는 배치 작업이 실제 프로젝트를 직접 수정하게 하지 말고, 새 실행을 확인하기 전에 정상으로 확인한 사본을 덮어쓰지 마세요. 스크립트나 분석기 옵션을 시험할 때는 새 프로젝트 이름을 사용합니다.
- 1
실행 파일 확인
Ghidra 설치 경로에서 운영체제에 맞는 실행 파일이 있고 도움말을 출력할 수 있는지 확인합니다. Windows는 배치 파일을, macOS와 Linux는 셸 실행 파일을 사용합니다.
support/analyzeHeadless.bat 또는 support/analyzeHeadless - 2
쓰기 가능한 프로젝트 루트 선택
가져온 프로그램, 데이터베이스, 캐시와 보고서를 저장할 충분한 공간을 확보하세요. 파일 잠금이나 동시 쓰기를 조사하는 동안에는 동기화 폴더를 피합니다.
D:\analysis\projects /srv/ghidra/projects - 3
입력 목록 기록
파일 이름, 해시, 예상 아키텍처와 수집 날짜를 기록합니다. 디렉터리 안의 내용이 기록되지 않은 경로는 재현 가능한 입력이 아닙니다.
samples/firmware-a.bin samples/firmware-b.bin - 4
처리 전에 백업
심볼 이름이나 데이터 형식을 바꾸고, 프로그램을 삭제하거나 변경 사항을 저장하는 스크립트를 실행하기 전에 프로젝트를 복사하세요.
ProjectName.gpr + ProjectName.rep/
-import와 -process 구분하기
헤드리스 분석기에서 가장 중요한 결정은 파일로 프로젝트를 새로 만들거나 보완할지, 아니면 이미 프로젝트에 있는 프로그램을 다시 열어 처리할지입니다. 파일이나 디렉터리를 프로젝트 프로그램으로 만들려면 -import를 사용합니다. 프로그램이 프로젝트에 이미 있으면 -process를 사용합니다.
온라인 예제에 두 옵션이 함께 나온다고 해서 두 모드를 모두 넣지는 마세요. 설명 가능한 작은 작업으로 시작하고, 필요한 경우에만 로더나 프로세서를 지정한 뒤 성공한 명령을 버전 관리되는 스크립트로 저장합니다.
| 작업 | 모드 | 일반 입력 | 확인할 내용 |
|---|---|---|---|
| 바이너리에서 프로젝트 만들기 | -import | 파일 또는 디렉터리 | 로더, 언어, 프로젝트 이름 |
| 기존 프로그램 분석 | -process | 기존 프로젝트 | 프로그램 이름과 프로젝트 사본 |
| 가져오는 동안 스크립트 실행 | -import + -postScript | 새 입력 목록 | 스크립트 경로와 저장된 결과 |
| 프로젝트 프로그램 트리 처리 | -process + -recursive | 기존 프로젝트 트리 | 범위와 실행별 로그 |
cd C:\ghidra_12.1.3_PUBLIC\support
analyzeHeadless.bat D:\analysis\projects HeadlessDemo -import D:\analysis\samples\demo.exe./support/analyzeHeadless /srv/ghidra/projects HeadlessDemo -process demo.exe반복성을 잃지 않고 스크립트 사용하기
헤드리스 작업은 분석 상태를 작고 검토 가능한 결과로 바꾸는 스크립트와 함께 사용할 때 더 유용합니다. 사전 스크립트는 프로젝트 작업을 준비하고, 사후 스크립트는 분석된 프로그램을 검사해 보고서를 작성할 수 있습니다. 함수, 문자열, 임포트 또는 메타데이터 한 항목을 출력하는 좁은 스크립트가 큰 프로젝트를 조용히 이름 변경하는 스크립트보다 테스트하기 쉽습니다.
스크립트는 버전 관리되는 폴더에 두고 -scriptPath로 전달하세요. 역할이 분명하도록 -preScript와 -postScript를 사용하고 지원되는 로그를 저장합니다. Ghidra 밖에서 CPython이 필요하면 PyGhidra 가이드를 확인하세요. 두 자동화 경계는 관련 있지만 같은 런타임이 아닙니다.
- 읽기 전용 또는 보고서 생성 작업과 권한을 확인한 작은 샘플부터 시작합니다.
- 스크립트 리비전을 명령과 Ghidra 릴리스 옆에 기록합니다.
- 스크립트가 프로젝트 데이터를 저장해야 하지 않는다면 보고서는 프로젝트 폴더 밖에 씁니다.
- 빈 결과, 없는 필드, 지원되지 않는 프로그램 유형, 두 번째 실행을 테스트합니다.
- 심볼이나 데이터 형식 변경을 수락하기 전에 백업한 프로젝트와 비교합니다.
배치 디렉터리, 로그와 CI 작업
디렉터리 기반 작업에서는 파일을 하나의 프로젝트에 넣을지, 별도 프로젝트를 사용할지 결정하세요. 하나의 프로젝트는 파일 간 이동에 편리하지만 별도 프로젝트는 자료가 섞이는 사고를 줄입니다. 중첩 폴더가 범위에 포함될 때만 -recursive를 사용하세요. 넓은 경로는 예상보다 많은 데이터를 가져올 수 있습니다.
명령, Ghidra 릴리스, Java 버전, 입력 매니페스트, 스크립트 리비전, 종료 상태, 로그, 프로젝트 경로와 예상 밖 결과 파일을 기록합니다. CI에서는 로그와 보고서를 보관하고 실행 파일이나 사후 스크립트가 오류를 보고하면 작업을 실패 처리합니다. 프로세스가 정상 종료되었다고 해서 예상한 함수나 문자열을 모두 찾았다는 뜻은 아닙니다.
입력 폴더, 프로젝트 프로필, 확장 기능, 스크립트 리비전 또는 Ghidra 릴리스가 바뀌면 같은 명령도 다른 결론을 낼 수 있습니다. 이 경계를 보고서 옆에 기록하세요.
./support/analyzeHeadless /srv/ghidra/projects BatchSet -import /srv/ghidra/samples -recursive -scriptPath /srv/ghidra/scripts -postScript export_summary.pyrelease=12.1.3 input_manifest=sha256.csv script=export_summary.py@abc123 project=BatchSet log=run-2026-09-16.log결과를 읽고 Ghidra에서 검증하기
헤드리스 실행이 끝나면 프로젝트를 열기 전에 종료 상태와 로그를 확인합니다. 로더 메시지, 선택된 언어 또는 컴파일러, 분석 완료 여부, 스크립트 예외, 건너뛴 파일과 쓰기 실패를 살펴보세요. 그런 다음 GUI에서 사본을 열고 Listing, 참조, Decompiler 또는 심볼에서 일부 결과를 확인합니다. Ghidra 검색 가이드와 Decompiler 가이드가 이 확인을 도와줍니다.
보고서는 출력 산출물이지 그 자체로 증거가 아닙니다. 스크립트가 문자열을 찾지 못했다면 언어, 범위와 API 객체를 확인하세요. 입력 매니페스트와 정확한 실행 기록을 저장된 프로젝트 데이터와 함께 보관합니다.
| 증상 | 첫 확인 | 안전한 다음 단계 |
|---|---|---|
| 프로그램이 나타나지 않음 | 가져오기 모드, 경로, 로더 | 새 프로젝트 이름으로 파일 하나를 실행 |
| 스크립트를 찾지 못함 | 스크립트 경로와 파일 이름 | 절대 경로의 스크립트 폴더와 작은 테스트 스크립트 사용 |
| 분석이 완전하지 않음 | 로그, 시간 제한, 메모리, 분석기 메시지 | 샘플 하나를 다시 실행하고 프로젝트 사본과 비교 |
| GUI와 결과가 다름 | 릴리스, 언어, 옵션, 스크립트 단계 | 같은 프로그램과 설정을 양쪽에서 확인 |
헤드리스 분석기, Script Manager와 PyGhidra 비교
헤드리스 분석기는 CLI 작업의 경계입니다. Script Manager는 화면에 보이는 Ghidra 애플리케이션 안에서 스크립트를 실행합니다. PyGhidra는 외부 CPython 프로세스를 Ghidra API에 연결합니다. 한 조사에서 함께 사용할 수 있지만 실행 환경은 서로 다릅니다.
한 프로그램을 시각적으로 확인하려면 GUI, 반복 가능한 가져오기나 프로젝트 작업에는 헤드리스 분석기, 외부 Python 프로세스가 핵심이면 PyGhidra를 사용하세요.
| 도구의 경계 | 적합한 용도 | 주요 주의점 |
|---|---|---|
| 헤드리스 분석기 | CLI 일괄 가져오기와 프로젝트 작업 | 프로젝트, 릴리스, 스크립트와 로그 기록 |
| Script Manager | 화면에 보이는 애플리케이션 내부 스크립트 | 현재 컨텍스트와 프로젝트에 의존 |
| PyGhidra | 외부 CPython 자동화 | Python과 Ghidra 호환성 확인 |
Ghidra 헤드리스 분석기 FAQ
Ghidra의 analyzeHeadless는 어디에 있나요?
Ghidra 설치 경로의 support/ 디렉터리에 있습니다. Windows는 analyzeHeadless.bat를 제공하고 Linux와 macOS는 셸 실행 파일을 사용합니다. 설치한 릴리스에 포함된 실행 파일을 사용하세요.
-import와 -process의 차이는 무엇인가요?
파일이나 디렉터리로 시작해 프로젝트를 만들거나 보완할 때는 -import를 사용합니다. 프로그램이 이미 프로젝트 안에 있고 처리하려는 경우에는 -process를 사용합니다.
GUI 없이 많은 파일을 분석할 수 있나요?
가능합니다. 헤드리스 분석기는 디렉터리를 가져오거나 처리할 수 있으며 -recursive 같은 옵션으로 범위를 넓힐 수 있습니다. 먼저 권한을 확인한 작은 목록으로 시작하고 입력 매니페스트를 기록하세요.
analyzeHeadless에서 스크립트를 실행할 수 있나요?
가능합니다. 설치된 릴리스가 지원하는 스크립트 경로, 사전 스크립트와 사후 스크립트 옵션을 사용하세요. 스크립트를 버전 관리하고 프로젝트 사본에서 테스트하며 로그와 보고서를 명령 기록 옆에 보관합니다.
헤드리스 분석기에 Ghidra 프로젝트가 필요한가요?
실행 파일에는 프로젝트 위치와 프로젝트 이름을 지정합니다. 가져오기 작업은 프로젝트 데이터를 만들거나 보완할 수 있고, 처리 작업은 이미 존재하는 프로그램을 전제로 합니다. 프로젝트 경로는 쓰기 가능하게 하고 애플리케이션 설치 폴더와 분리하세요.
헤드리스 분석기는 PyGhidra와 같은 것인가요?
아닙니다. 헤드리스 분석기는 가져오기, 프로젝트 처리와 Ghidra 스크립트를 위한 CLI 실행 파일입니다. PyGhidra는 외부 CPython 프로세스를 Ghidra API에 연결합니다. 필요한 자동화 경계에 맞는 도구를 선택하세요.