未知のファイルを検出し、適切なバンドル済み抽出プログラムへ振り分ける汎用Windows抽出ツール。
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: フォーマットファミリーごとに1つのハンドラモジュール。src/gui: CLI をラップするオプションの tkinter フロントエンド(GUI 参照)。
icons: ライトモードとダークモード用に PNG 化された Fluent アイコン。test: ユニットテスト、フォーマットおよびエンジンのテストスイート、フォーマットごとのサンプルファイル。tools: 開発者向けツール — generate_data.py(ハンドラからルーティングデータを
構築)と generate_icons.py(GUI アイコンを生成)。update: 同梱バイナリを更新するアップデータ設定とスクリプト。docs: 対応フォーマット、ハンドラの追加方法、サードパーティに関する通知。コンパイル済みビルドでは、bin/、data/、config.ini を exe の外部に保持するため、
ファイルを差し替えるだけで更新できます。cli_paths.py はこれらを実行ファイルの隣
(凍結時)または src/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 にあります(生成され、
実行時に読み込まれます)。1つのキーが複数のハンドラにマップされ、成功するまで順に
試されます: 例えば最初に 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> にはすべてのサブコマンドでフォルダを指定できます。フォルダ内のファイル(サブフォルダは除く)が
1つずつ処理されます。各ファイルにはそれぞれ専用の出力フォルダが作成されます:<stem>_extracted
(ファイルと同じ場所、または output_dir が指定されている場合はその配下)、2つのファイルが同じ 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(インデックスで
1つのフラグメントを切り出し)、--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
List アーカイブの内容を一覧表示する(展開は行わない):
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