
magic-extractor v1.3.1
범용 Windows 추출 도구로, 알 수 없는 파일을 감지하여 적절한 번들 추출기로 전달합니다.
Magic Extractor
설명
Magic Extractor는 여러 탐지기를 사용하여 파일을 식별하고 적절한 내장 추출기로 라우팅하는 Windows용 범용 추출 도구입니다. 주류 압축 형식, 오늘날 실제로 접하게 되는 설치 프로그램, 그리고 덜 일반적인 다양한 아카이버를 아우르는 것을 목표로 합니다.
80개 이상의 형식을 자동 감지합니다 — 아카이브, 설치 프로그램, 디스크 이미지, 포렌식 이미지(EWF/AFF/AD1), 디스크 이미지, 메일 저장소, 최신 코덱을 포함합니다. 전체 목록은 formats.md를 참조하세요.
빠른 시작
최신 릴리스를 다운로드하여 압축을 풀고 실행하세요:
magic-extractor.exe extract mystery.bin
identify, list, carve, --recursive, --bruteforce에 대한 예시는 Examples를 참고하세요.
프로젝트 구조
src/cli: 명령줄 도구입니다.bin: 번들로 포함된 탐지기 및 추출기 바이너리입니다.detectors: DIE, Magika, binwalk (TrID의 정의는data/signatures.json으로 변환됩니다).extractors: 7-Zip (대체용으로 7-Zip ZS 포함), unrar, unace, unshield, lessmsi, dark (WiX) 등.
data: 핸들러에서 생성된 라우팅 데이터입니다 (아래 참조).formats: 형식 패밀리별로 하나씩 있는 핸들러 모듈입니다.
src/gui: CLI를 감싸는 선택적 tkinter 프런트엔드입니다 (GUI 참조).icons: 라이트 및 다크 모드용으로 PNG로 구워진 Fluent 아이콘입니다.
test: 단위 테스트, 형식 및 엔진 배터리, 형식별 샘플 파일입니다.tools: 개발자 도구 —generate_data.py(핸들러에서 라우팅 데이터를 빌드) 및generate_icons.py(GUI 아이콘을 굽습니다).update: 번들 바이너리를 갱신하는 업데이터 구성 및 스크립트입니다.docs: 지원 형식, 핸들러 추가 방법, 제3자 고지.
컴파일된 빌드는 bin/, data/, config.ini를 exe 외부에 유지하여
파일 교체로 업데이트할 수 있게 합니다. cli_paths.py는 이를 실행 파일 옆(프로즌)에서
또는 src/cli/ 아래(개발)에서 찾습니다.
탐지 작동 방식
일반 추출의 경우 탐지기는 조기 종료와 함께 다음 순서로 실행됩니다 — 알려진 핸들러를 산출하는 첫 번째 탐지기가 승리합니다 (가장 저렴한 것부터 시작하므로 ML 모델은 보통 건너뜁니다):
- puremagic — 순수 파이썬, 서브프로세스 없음; 잘 형성된 아카이브에 대한 저렴한 MIME 검사.
- 내장 시그니처 —
data/signatures.json의 매직 바이트 패턴; 엔진이 놓치는 아카이버(bcm, dgca, kgb, uharc, alzip, freearc, ...)를 외부 프로세스 없이 이름 붙입니다. - DIE (Detect It Easy) — 시그니처 엔진; 설치 프로그램, PE 및 SFX의 전문가.
- binwalk — 짧은 유형 키(cpio, lzma, ...) 및 임베디드 콘텐츠.
- Magika — Google의 AI 콘텐츠 유형 탐지기, 포괄적 대비책.
각 탐지기는 고유하게 기여합니다 (상호 보완적이며 중복이 아닙니다): 시그니처 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는 조기 종료를 비활성화합니다: 모든 탐지기가 실행되고 탐지된 각 핸들러가 차례로 시도됩니다 (첫 번째 추측이 틀렸을 때 유용합니다).- 실행 파일은 또한 SFX 및 설치 프로그램 핸들러(RAR, ACE, ARC, KGB, UHARC, Inno Setup, BitRock, Clickteam)를 대체 후보로 받습니다; 각각은 자신의 것이 아닌 파일을 거부하므로 체인은 다음으로 넘어갑니다.
carve하위 명령은 추가로 binwalk의 오프셋 맵을 사용하여 임의 오프셋에 임베디드된 아카이브(예: 펌웨어 이미지 내부)를 추출합니다.
탐지 → 핸들러 라우팅 맵은 data/handlers.json에 있습니다 (생성되어 런타임에
로드됨). 하나의 키는 여러 핸들러에 매핑될 수 있으며, 하나가 성공할 때까지 순서대로 시도됩니다:
예를 들어 7-Zip 먼저, 그다음 메인라인 7-Zip이 열 수 없는 것(LZ4가 있는 SquashFS,
ZSTD가 있는 NSIS)을 위한 7-Zip ZS. 일반 토큰 블랙리스트는 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 src/cli/requirements.txt
사용법
Magic Extractor는 하위 명령어를 사용합니다:
python src/cli/main.py extract <path> [output_dir] [options] # detect and extract
python src/cli/main.py identify <path> # report type + candidate handlers
python src/cli/main.py list <path> # list archive contents
python src/cli/main.py carve <path> [output_dir] [options] # carve embedded archives (binwalk offsets)
하위 명령 없이 경로만 지정하면 기본값은 extract이며(하위 호환), 옵션은 경로나 하위 명령 앞에 올 수 있습니다:
python src/cli/main.py <path> <output_dir> [options]
python src/cli/main.py --debug <path>
python src/cli/main.py --version
--debug와 --fast-check는 모든 하위 명령에서 작동하며, --password는
extract, list, carve에서 작동합니다.
<path>는 모든 하위 명령에서 폴더가 될 수 있습니다. 폴더의 파일(하위 폴더 제외)이
하나씩 처리됩니다. 각 파일은 자체 출력 폴더를 갖습니다: <stem>_extracted
(파일 옆, 또는 output_dir이 지정된 경우 그 아래), 또는 두 파일이 같은 stem을
공유할 때는 <name>_extracted입니다.
출력 폴더에 이미 파일이 있으면, extract는 이전 결과와 섞거나 덮어쓰지 않고
새로운 <folder>_<YYYYmmdd-HHMMSS>에 씁니다. --merge-output은 대신 기존 폴더로
추출하며, 같은 이름의 파일과 폴더를 덮어씁니다(GUI는 대상이 잠겨 있을 때 이렇게
합니다). 추출 중인 아카이브는 절대 덮어쓰지 않습니다. 각 핸들러 시도는 자체 임시
폴더에서 실행되므로, 실패한 시도가 부분 파일을 남기는 일은 없습니다.
종료 코드: 0 성공; 1 실패 — 아무것도 추출할 수 없었거나, 폴더 실행에서 파일
하나가 실패했거나, 폴더에 파일이 없었거나, --delete-source가 소스를 삭제하지
못한 경우; 2 잘못된 인수; 3 오류와 함께 추출됨 — 도구가 실패를 보고했지만
대부분의 내용이 추출된 경우(예: Linux 이미지의 심볼릭 링크를 Windows에서 생성할 수
없음)이므로 출력 폴더에 보관되고 소스는 삭제되지 않습니다. --recursive를 사용하면
추출할 수 없는 중첩 아카이브는 경고로 보고되며 종료 코드를 변경하지 않습니다
(추출된 많은 파일, 예를 들어 설치 프로그램의 모든 DLL이 후보로 보입니다).
extract 옵션:
-
--password <password>: 암호화된 아카이브의 비밀번호. -
-r,--recursive: 출력 내부에서 발견된 아카이브를 추출합니다(--max-depth로 제한되며 기본값 5). -
-b,--bruteforce: 첫 번째에서 멈추지 않고 감지된 모든 핸들러를 시도합니다. -
--merge-output: 출력 폴더에 이미 파일이 있더라도 그 폴더로 추출하며, 같은 이름의 항목을 덮어씁니다. -
--delete-source: 성공적으로 추출한 후 소스를 삭제합니다(config.ini에서delete_to_recycle_bin이 꺼져 있지 않은 한 휴지통으로). -
--open-output-folder <true|false>: 완료 시 출력 폴더를 엽니다. -
--check-free-space <true|false>: 출력 볼륨에 공간이 부족할 수 있으면 경고합니다. -
--check-unicode <true|false>: 추출된 이름에 비ASCII 문자가 있으면 경고합니다. -
--fix-file-extensions <true|false>: 확장자가 없는 추출 파일에 내용 기반 확장자를 부여합니다(기존 확장자는 절대 덮어쓰지 않음). 기본값은 꺼짐: 추측이 틀릴 수 있습니다(Makefile,LICENSE,configure가.txt가 됨). -
--create-log-files <true|false>: 출력 폴더에magic-extractor.log를 씁니다.(생략 시 각 옵션은
config.ini값을 기본으로 하며,--update-defaults와 결합하면 주어진 값을 유지합니다 — 예:--open-output-folder false --update-defaults는 이전에 저장된 기본값을 끕니다.) -
--fast-check: 전체 파일 감지를 실행하는 대신 처음 64 KiB만 검사합니다. -
--update-defaults: 주어진 설정을config.ini의 기본값으로 유지합니다.
carve 옵션: --list(binwalk 프래그먼트 테이블 출력), --fragment N(인덱스로
프래그먼트 하나 추출), --raw(핸들러가 아는 것만이 아니라 모든 프래그먼트 추출).
아래 예제에서
magic-extractor는 빌드된.exe입니다. 소스에서 실행할 때는python src/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
Bruteforce — 탐지가 확실하지 않을 때, 첫 번째에서 멈추지 않고 일치하는 모든 핸들러를 시도합니다:
magic-extractor extract weird-archive.dat --bruteforce
Carve — 더 큰 파일 내부의 특정 오프셋에 포함된 아카이브를 추출합니다 (펌웨어 이미지에서 흔히 사용됨). 먼저 검사한 후 carve합니다:
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