binref/refineryハイオクタン・トリアージ分析
[
][docs]
[
][tests]
[
][codecov]
[
][pypi]
__ __ High Octane Triage Analysis __
|| _||______ __ __________ _____ ||
|| \||___ \__| ____/ ______/___ / ____\ ||
==||=====|| | __/ |/ \ /==| / __ \ __\===]|
'======|| | \ | | \_ _| \ ___/| | ||
||____ /__|___|__/ / | \____]| | ||
=========''====\/=========/ /==|__|=====|__|======'
\ /
\/
Binary Refinery™ は、圧縮や暗号化といったバイナリデータの変換を実装した Python スクリプトのコレクションです。
しばしば単に refinery と呼びますが、これは対応するパッケージの名前でもあります。
これらのスクリプトは、入力を stdin からのみ読み取り、出力を stdout に書き出すように設計されています。
主な哲学は、各スクリプトは ひとつの 仕事をこなす単位であるべきだというもので、
個々の単位はコマンドライン上でパイプ演算子 | を使って パイプライン に組み合わせることで、より複雑なタスクを実行できます。
このプロジェクトの主な焦点はマルウェアのトリアージであり、
CyberChef のようなものをコマンドライン上で実装しようとする試みです。
Python の仮想環境を作成してください。Python 3.11 以降が必要です。refinery は次のようにインストールします:
python -m pip install -U pip
python -m pip install -U binary-refinery[extended]
ユニットの動作を学ぶには -h を付けて実行するか、[docs][] を grep するか、binref コマンドを使って探してください。
実際に動作しているところを見たい場合は[最近の動画][VOD3]をご覧ください。
ただし、この readme の残りも読んでください。
リリーススケジュールはありませんが、リリースは非常に頻繁に行われるため、定期的に更新することをお勧めします。 バグ修正は GIT の外では文書化されませんが、その他のすべての変更 (つまり新機能) は変更履歴に文書化されています。 特に影響の大きいリリースに関する更新については、[Mastodon][] でフォローしてください。
ユニットを -h または --help スイッチ付きで実行したときに表示されるヘルプテキストが、その主要なドキュメントです。
[自動生成されたドキュメント][docs]には、各ユニットのその出力のコンパイルがトップレベルに含まれていますが、
ツールキットの 3 つの基本概念の仕様も含まれています:
[フレーミング][frame]、[multibin 引数][argformats]、[メタ変数][meta] です。
すべてのユニットの説明とヘルプテキストの全文検索も、提供されている binref コマンドを介してコマンドラインで利用できます。
リファレンスドキュメントはやや無味乾燥になりがちであることを認識し、
チュートリアルシリーズを制作する取り組みが進行中です。ぜひチェックすることを強くお勧めします。
さらに、以下に追加のリソース (第三者が作成したものを含む) をまとめています。
[!NOTE]
Refinery はまだアルファ版であり、インターフェースが時々変更されることがあります。 つまり、ユニットやパラメータが削除されたり名前が変更されたりする可能性があります。 したがって、古い動画やブログ記事の特定のコマンドラインが動作しなくなることがあります。
2021/08] [OALabs][OA] が快く[特集動画でツールキットのデモ][VOD1]をさせてくれました。
動画では、基本的に
最初のチュートリアルの内容を順に進めています。2021/11] [Johannes Bader][JB] が binary refinery を使った malspam の解析について素晴らしい[ブログ記事][BLOG]を書きました。2024/03] [Malware Analysis For Hedgehogs][MH] が refinery を使って [XWorm サンプルをアンパックする動画][VOD2]を制作しました。2024/11] [the CyberYeti][CY] が[配信で refinery を紹介させてくれました][VOD3]。2025/06] [the CyberYeti][CY] と[再び配信に出演しました][VOD4]。こちらはもう少しラフな内容です。
ここで見られるバグはすべて修正済みです。😉ショーケースには、以下の例のセクションのサンプルやチュートリアルも含まれます。
Binary Refinery は (c) 2019 Jesko Hüttenhain であり、[3-Clause BSD License][license] の下で公開されています。 このリポジトリには完全なライセンス文のコピーも含まれています。 このライセンスでカバーされていないことを行いたい場合は、著者に気軽に連絡してください。
refinery には少なくとも Python 3.11 が必要です。 独自の[仮想環境][venv]にインストールすることをお勧めします: このパッケージは非常に多くの依存関係を引き込む可能性があり、 グローバルな Python にインストールするとバージョン競合が発生しやすくなります。 また、このツールキットは多数の新しいコマンドを導入するため、 一部のシステムでこれらの一部が衝突する可能性が高く、 それらを独自の別個の仮想環境に保つことがそれを防ぐ一つの方法です。
すべての refinery コマンドを常にシェルで利用できるようにしたい場合 (つまり、カスタム仮想環境に切り替える必要なく)、
インストールの プレフィックス を選択するオプションもあります。
これは、インストールされるすべてのコマンドシムの前に付けられます。
たとえば、プレフィックスとして r. を選択した場合、[emit][] ユニットはコマンド r.emit としてインストールされます。
追加の利点は、r. と入力して Tab を 2 回叩くと、利用可能なすべての refinery コマンドのリストが得られることです。
ただし、ドキュメントではプレフィックスは想定されておらず、refinery の開発目標はほとんどのシステムで_衝突しない_ことであることに注意してください。
著者はプレフィックスを使用しておらず、安全策としてこのオプションを提供しています。
refinery をインストールおよび更新する最も簡単な方法は pip 経由です。 まず最新バージョンを実行していることを確認してください:
python -m pip install -U pip
次に refinery パッケージをインストールするだけです:
pip install -U binary-refinery
すべてのユニットにプレフィックスを選択したい場合は、環境変数 REFINERY_PREFIX で指定できます。
たとえば、次のコマンドは Linux でプレフィックス r. を付けて現在の Python 環境に refinery をインストールします:
REFINERY_PREFIX=r. pip install -U binary-refinery
Windows では、次のコマンドを実行する必要があります:
set REFINERY_PREFIX=r.
pip install -U binary-refinery
特別なプレフィックス ! を指定すると、シェルコマンドがまったく作成されず、
binary refinery はライブラリとしてのみインストールされます。
現在の refinery HEAD をインストールしたい場合は、上記のすべての手順を繰り返し、pip パッケージの代わりにこのリポジトリを指定できます。
たとえば、次のコマンドは最新の refinery コミットをインストールします:
pip install -U git+git://github.com/binref/refinery.git
最後に、[REMnux][remnux-main] を使用している場合は、彼らの [refinery docker コンテナ][remnux]を使用できます。
ローカルのマルウェア解析用 [claude][] に binary refinery を使わせたい場合は、[Binary Refinery Skill][agent] をチェックしてください。
以下は、さまざまなシェル環境が現在どの程度サポートされているかの概要です:
| Shell | Platform | State | Comment |
|---|---|---|---|
| Bash | Posix | 🔵 良好 | 著者が時々使用。 |
| CMD | Windows | 🔵 良好 | 著者が頻繁に使用。 |
| PowerShell | Windows | 🟡 妥当 | [PowerShell のバージョンが少なくとも 7.4 であれば動作します。][psh1] |
| Zsh | Posix | 🟠 軽微な問題 | [議論][zsh1]の後、[修正][zsh2]があります。 |
| Fish | Posix | 🟠 軽微な問題 | issue [#55][fsh1] と議論 [#22][fsh2] を参照。 |
別のシェルを使用していてフィードバックを共有したい場合は、お知らせください!
(時に大規模な) 外部依存関係を持つ、非常に限定的な状況で使われるユニットがいくつかあります。
たとえば、[stego][] は画像解析ライブラリ Pillow を必要とするユニットです。
一部のライブラリは、初めてのユーザーにとって refinery のインストール時間を妥当なレベルに保つために、デフォルトではインストールされません。
対応するユニットは、依存関係が欠落している場合に何をすべきかを教えてくれます:
$ emit config.png | stego RG
(13:37:00) failure in stego: dependency Pillow is missing; run pip install Pillow
その後、これらの欠落している依存関係を手動でインストールできます。 欠落している依存関係に煩わされたくなく、refinery のインストールが長くなることを気にしない場合は、次のようにパッケージをインストールできます:
pip install -U binary-refinery[all]
これにより、必要なものに加えて_すべての_依存関係がインストールされます。 より正確には、次の追加カテゴリが利用可能です:
| Name | Included Dependencies |
|---|---|
default | 妥当な依存関係の推奨セレクション、著者の選択 |
extended | 拡張セレクション、最も obscure なものだけを除外 |
all | すべての refinery ユニットのすべての依存関係 |
これらはここに昇順でリストされています。つまり、extended は default がインストールするすべてをインストールします。
あるいは、このリポジトリをクローンして、スクリプト update.sh (Linux の場合) または update.ps1 (Windows の場合) を使用して、refinery パッケージをローカルの仮想環境にインストールできます。 この方法のインストールと更新のプロセスは、単にスクリプトを実行するだけです:
binary-refinery をアンインストールし、binary-refinery[all] をインストールします。すべてのドキュメントをローカルで生成することもできます。
そのためには、run-pdoc3.py スクリプトを実行してください。
これは、binary refinery が Python パッケージとしてインストールされている環境から実行しない限り失敗します。
実行するには、run-pdoc3.py の最初のコマンドライン引数として仮想環境のパスを指定する必要があり、
これによりスクリプトはその環境のインタプリタを使用して自身を再度実行します。
run-pdoc3.py を実行したいと確信している場合、
現在のデフォルトの Python インタプリタでスクリプトを強制的に実行するコマンドラインスイッチがあります。
このスクリプトは [pdoc3 パッケージ][pdoc3]をインストールし、それを使用して refinery パッケージの HTML ドキュメントを生成します。
ドキュメントは、この readme ファイルのすぐ隣のサブディレクトリ html にあります。