범용 Windows 추출 도구로, 알 수 없는 파일을 감지하여 적절한 번들 추출기로 전달합니다.
Magic Extractor는 여러 탐지기로 파일을 식별하고 이를 적절한 번들 추출기로 연결하는 Windows용 범용 추출 도구입니다. 주류 압축 형식, 오늘날 실제로 볼 수 있는 설치 프로그램, 그리고 흔하지 않은 다양한 아카이버를 지원하는 것을 목표로 합니다.
80개 이상의 형식 — 아카이브, 설치 프로그램, 디스크 이미지, 포렌식
이미지(EWF/AFF/AD1), 광 디스크 이미지, 메일 저장소, 최신 코덱을 자동 탐지합니다.
전체 목록은 formats.md를 참조하세요.
최신 릴리스를 다운로드하여 압축을 풀고 실행하세요:
magic-extractor.exe extract mystery.bin
identify, list, carve, --recursive, --bruteforce는
예제를 참조하세요.
cli: 소스 코드.
bin: 번들로 제공되는 탐지기 및 추출기 바이너리.
detectors: DIE, Magika, binwalk (TrID 정의는 data/signatures.json으로 변환됨).extractors: 7z, unrar, unace, unshield, lessmsi, dark(WiX) 등.data: 런타임 구성. 동적으로 로드됨(아래 참조).formats: 형식 패밀리당 핸들러 모듈 하나.gui: CLI를 감싸는 선택적 tkinter 프런트엔드(GUI 참조).test: 형식별 샘플 파일(추출/탐지 테스트용 픽스처).tools: 개발자 도구(generate_data.py — 핸들러에서 데이터 파일 생성).컴파일된 빌드는 bin/, data/, config.ini를 exe 외부에 유지하므로 파일
교체만으로 업데이트할 수 있습니다. main.py의 경로 해석기는 실행 파일
옆(프로즌 상태) 또는 cli/ 아래(개발 모드)에서 이 파일들을 찾습니다.
일반적인 추출에서는 조기 종료(early-exit) 방식으로 탐지기가 다음 순서로 실행됩니다 — 알려진 핸들러를 찾는 첫 번째 탐지기가 승리합니다(가장 저렴한 것부터 시작하므로 ML 모델은 보통 건너뜁니다):
data/signatures.json의 매직 바이트 패턴. 외부 프로세스 없이 엔진들이 놓치는 아카이버(bcm, dgca, kgb, uharc, alzip, freearc, ...)를 식별.각 탐지기는 고유한 역할을 합니다(중복이 아니라 상호 보완적). 시그니처 DB는 엔진들이 놓치는 아카이버를 식별하고, DIE는 설치 프로그램/PE를 처리하며, binwalk는 다른 탐지기가 놓치는 몇 가지 유형을 잡아내고, puremagic/Magika는 MIME을 담당합니다.
PureMagic 2.x는 전체 파일을 받으면 콘텐츠 인식 심층 스캔도 제공합니다. 전체
파일 분석이 기본값이며, 선택적 --fast-check 수정자는 심층 검사보다 시작
속도가 중요할 때 처음 64 KiB만 전달합니다.
각 핸들러는 detection_mimes() / detection_names() / detection_signatures()를
통해 자체 지표를 선언합니다. tools/generate_data.py는 이를
data/handlers.json과 data/signatures.json으로 컴파일합니다(선택적으로
data/extra_detections.json을 위에 병합). TrID는 사용되지 않습니다.
참고: puremagic의
magic_data.json에 시그니처가 없는 형식(또는 puremagic이 일반적인application/octet-stream으로만 보고하는 형식)은 핸들러에 사용자 정의detection_signatures()항목을 선언해야 합니다. 그렇지 않으면 콘텐츠로 탐지되지 않습니다.
--bruteforce는 조기 종료를 비활성화합니다. 모든 탐지기가 실행되고 탐지된
각 핸들러를 차례로 시도합니다(첫 번째 추측이 틀렸을 때 유용).carve 하위 명령은 추가로 binwalk의 오프셋 맵을 사용하여 임의의 오프셋에
임베디드된 아카이브(예: 펌웨어 이미지 내부)를 추출합니다.탐지 → 핸들러 라우팅 맵은 data/handlers.json에 있습니다(수동 관리, 런타임에
로드). 일반 토큰 블랙리스트는 data/detection_blacklist.json에 있습니다.
전체 형식 목록과 해당 핸들러는 formats.md를 참조하세요.
새 형식 지원을 추가하려면 docs/adding-a-handler.md를 참조하세요 — 핸들러 클래스, 탐지 선언, DIE/TrID 조회, 매직 시그니처, 라우팅 데이터 재생성, 도구 번들링, 테스트를 다루는 종합 가이드입니다.
대부분의 사용자는 릴리스를 다운로드하면 됩니다(빠른 시작 참조). 소스에서 실행하려면 Python 3.12 이상이 필요합니다.
git clone <repo-url>
cd magic-extractor
pip install -r cli/requirements.txt
Magic Extractor는 하위 명령을 사용합니다:
python cli/main.py extract <path> [output_dir] [options] # detect and extract
python cli/main.py identify <path> # report type + candidate handlers
python cli/main.py list <path> # list archive contents
python cli/main.py carve <path> [output_dir] [options] # carve embedded archives (binwalk offsets)
하위 명령 없이 경로만 지정하면 기본적으로 extract로 동작합니다(하위 호환):
python cli/main.py <path> <output_dir> [options]
extract 옵션:
--password <password>: 암호화된 아카이브의 비밀번호.
-r, --recursive: 출력물 내부에서 발견된 아카이브를 추출합니다(--max-depth로 제한, 기본값 5).
-b, --bruteforce: 첫 번째에서 멈추지 않고 탐지된 모든 핸들러를 시도합니다.
--open-output-folder <true|false>: 완료 시 출력 폴더를 엽니다.
--check-free-space <true|false>: 출력 볼륨에 공간이 부족할 수 있으면 경고합니다.
--check-unicode <true|false>: 비ASCII 추출 이름에 대해 경고합니다.
--fix-file-extensions <true|false>: 확장자가 없는 추출 파일에 콘텐츠 기반 확장자를 부여합니다(기존 확장자는 절대 덮어쓰지 않음).
--create-log-files <true|false>: 실행별 로그를 출력 디렉터리에 기록합니다.
(각 항목은 생략 시 config.ini 값을 기본값으로 사용합니다. 와
함께 사용하면 지정 값을 저장할 수 있습니다 — 예: 는 이전에 저장된 기본값을 끕니다.)
carve 옵션: --list(binwalk 프래그먼트 테이블 출력), --fragment N(인덱스로 프래그먼트 하나를 캐빙), --raw(핸들러가 아는 프래그먼트뿐만 아니라 모든 프래그먼트를 캐빙).
아래 예제에서
magic-extractor는 빌드된.exe입니다. 소스에서 실행할 때는python cli/main.py로 바꾸면 됩니다 — 인자는 동일합니다.
아카이브 추출 — 형식을 알 필요가 없습니다. 자동으로 탐지됩니다:
magic-extractor extract mystery.bin
# extracts into mystery_extracted/ next to the file
파일 식별 — 파일을 건드리지 않고 각 탐지기가 무엇을 보았는지, 어떤 핸들러가 실행될지 보여줍니다:
magic-extractor identify setup.exe
File: setup.exe
[DIE] detect inno setup installer
Candidate handlers (in order):
- FormatInnoSetupHandler
아카이브 내용 나열(추출 없음):
magic-extractor list backup.7z
재귀 추출 — 출력물 내부에서 발견된 아카이브(예: .tar.gz 또는 더 많은
아카이브를 포함한 설치 프로그램)를 --max-depth 수준까지 추출합니다:
magic-extractor extract app-1.0.tar.gz --recursive
브루트포스 — 탐지가 확실하지 않을 때 첫 번째에서 멈추지 않고 일치한 모든 핸들러를 시도합니다:
magic-extractor extract weird-archive.dat --bruteforce
캐빙 — 더 큰 파일 내부의 특정 오프셋에 임베디드된 아카이브를 추출합니다 (펌웨어 이미지에서 전형적). 먼저 확인한 후 캐빙하세요:
magic-extractor carve router-firmware.bin --list
IDX OFFSET SIZE NAME DESCRIPTION
0 0x00000000 793,720 pe Windows PE binary
1 0x000c1c78 2,495,983 lzma LZMA compressed data
magic-extractor carve router-firmware.bin # carve + extract the known blobs
magic-extractor carve router-firmware.bin --fragment 1 # carve only fragment #1
선택적 tkinter 프런트엔드(gui/에 있음)가 CLI를 감쌉니다 — extract, scan,
carve 모드, 드래그 앤 드롭, 배치 큐, 실행 기록, 환경설정(Preferences)
대화상자가 있는 Universal-Extractor 스타일 창입니다. 브루트포스는 실행
옵션(Run options)에서 사용할 수 있습니다. 동일한 main.py를 호출하므로 탐지
및 추출 동작은 동일합니다.
python gui/main.py # launch the window
python gui/main.py <file> [outdir] # prefill the source (and destination)
python gui/main.py <file> /scan # prefill and start in identify mode
드래그 앤 드롭에는 선택적 tkinterdnd2 패키지가 필요합니다(pip install -r gui/requirements.txt). 없어도 드롭 지원만 제외하고 창은 정상 작동합니다.
환경설정(Preferences) 대화상자에서 Explorer 컨텍스트 메뉴 항목을 등록할 수도
있습니다.
cd cli
pyinstaller --onefile main.py --name magic-extractor --collect-data puremagic
그런 다음 bin/, data/, config.ini를 dist/magic-extractor.exe 옆에
복사하세요. CI가 자동으로 수행합니다 — .github/workflows/release.yml 참조.
MIT — LICENSE.txt 참조. 참고: cli/bin/ 아래에 번들된 타사 추출기/탐지기
바이너리는 자체 라이선스(일부는 독점 프리웨어)를 유지하며 MIT가 적용되지
않습니다. 배포 전에 재배포 조건을 확인하세요.
--update-defaults--open-output-folder false --update-defaults--fast-check: 전체 파일 탐지 대신 처음 64 KiB만 검사합니다.
--update-defaults: 지정한 설정을 config.ini의 기본값으로 저장합니다.