未知のファイルを検出し、適切なバンドル済み抽出プログラムへ振り分ける汎用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: フォーマットファミリごとに1つのハンドラモジュール。gui: CLI をラップするオプションの tkinter フロントエンド（GUI を参照）。test: フォーマットごとのサンプルファイル（検出/抽出テスト用のフィクスチャ）。tools: 開発者向けツール（generate_data.py — ハンドラからデータファイルを生成します）。コンパイル済みビルドは、bin/、data/、config.ini を exe の外部に保持しているため、ファイルの差し替えだけで更新できます。main.py のパス解決ロジックは、実行可能ファイルの隣（frozen）または cli/ 配下（開発時）でこれらを見つけます。
通常の抽出では、検出器は次の順序で 早期終了 付きで実行されます。既知のハンドラを返した最初の検出器が優先されます（最もコストの低いものから順に試すため、通常は 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 の値にデフォルト設定されます。 と組み合わせると、
指定した値を永続化できます。例: --update-defaults` は、以前保存されたデフォルトをオフにします。）
carve オプション: --list（binwalk のフラグメントテーブルを表示）、--fragment N（インデックスで1つのフラグメントを抽出）、--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 をラップします。Universal-Extractor スタイルのウィンドウで、extract、scan、carve モード、ドラッグ＆ドロップ、バッチキュー、実行履歴、設定ダイアログを備えています。ブルートフォースは実行オプションで利用できます。同じ 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）。なくてもウィンドウは動作しますが、ドロップ対応がありません。また、設定ダイアログからエクスプローラのコンテキストメニュー項目を登録することもできます。
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 --fast-check：ファイル全体の検出を実行せず、最初の 64 KiB だけをチェックします。
--update-defaults：指定した設定を config.ini のデフォルトとして永続化します。