
ハイオクタン・トリアージ分析
[][docs]
[
][tests]
[
][codecov]
[
][pypi]
__ __ High Octane Triage Analysis __
|| _||______ __ __________ _____ ||
|| \||___ \__| ____/ ______/___ / ____\ ||
==||=====|| | __/ |/ \ /==| / __ \ __\===]|
'======|| | \ | | \_ _| \ ___/| | ||
||____ /__|___|__/ / | \____]| | ||
=========''====\/=========/ /==|__|=====|__|======'
\ /
\/
Binary Refinery™ は、圧縮や暗号化といったバイナリデータの変換を実装する Python スクリプトのコレクションです。
しばしば単に refinery と呼ぶこともあり、これは対応するパッケージの名前でもあります。
スクリプトは、入力は stdin からのみ読み取り、出力は stdout に書き出すように設計されています。
基本理念は、各スクリプトが 1 つ の処理を担う単位であるべきというものであり、
個々の単位はコマンドライン上でパイプ演算子 | を用いて パイプライン に組み合わせることで、より複雑な処理を実行できます。
本プロジェクトの主な焦点はマルウェアのトリアージであり、
CyberChef のようなものをコマンドライン上で実装する試みです。
Python の仮想環境を作成してください。Python 3.11 以降が必要です。refinery は次のようにインストールします:
python -m pip install -U pip
python -m pip install -U --no-cache-dir binary-refinery[extended]
ユニットの動作を学ぶには -h を付けて実行するか、[docs][] を grep するか、binref コマンドを使ってください。
実際に動作している様子を見たい場合は[最近の動画][VOD3]をご覧ください。
ただし、この readme の残りの部分もぜひお読みください。
リリーススケジュールは特に定めていませんが、リリースは非常に頻繁に行われるため、定期的に更新することをお勧めします。 バグ修正は GIT 以外では文書化されていませんが、それ以外の変更(つまり新機能)はすべて変更履歴に記載されています。 特に影響の大きいリリースに関する更新情報は、[Mastodon][] でフォローしてください。
ユニットを -h または --help スイッチ付きで実行したときに表示されるヘルプテキストが、そのユニットの主要なドキュメントです。
[自動生成されたドキュメント][docs]には、各ユニットのその出力のコンパイルがトップレベルに含まれているほか、
ツールキットの3つの基本概念である[フレーミング][frame]、[マルチビン引数][argformats]、[メタ変数][meta]の仕様も含まれています。
すべてのユニットの説明とヘルプテキストの全文検索も、提供されている binref コマンドを使ってコマンドラインから利用できます。
リファレンスドキュメントはやや無味乾燥になりがちであることを認識し、
一連のチュートリアルを作成する取り組みを継続的に行っています。ぜひ一度ご覧になることを強くお勧めします。
さらに、以下に追加のリソース(第三者が作成したものを含む)をまとめています。
[!NOTE]
Refinery はまだアルファ版であり、インターフェースが変更されることがあります。 つまり、ユニットやパラメータが削除されたり名前が変更されたりする可能性があります。 そのため、古い動画やブログ記事に記載されている特定のコマンドラインが動作しなくなることがあります。
2021/08] [OALabs][OA] のご厚意により、[機能動画でツールキットをデモ][VOD1]させていただきました。
動画では、主に
最初のチュートリアルの内容を順に進めています。2021/11] [Johannes Bader][JB] が、binary refinery を使ったマルスパムの解析について素晴らしい[ブログ記事][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条項BSDライセンス][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 --no-cache-dir binary-refinery
すべてのユニットに付けるプレフィックスを選択したい場合は、環境変数 REFINERY_PREFIX で指定できます。
たとえば、次のコマンドは Linux 上で現在の Python 環境にプレフィックス r. を付けて refinery をインストールします:
REFINERY_PREFIX=r. pip install -U --no-cache-dir binary-refinery
Windows では、次のコマンドを実行する必要があります:
set REFINERY_PREFIX=r.
pip install -U --no-cache-dir binary-refinery
特殊なプレフィックス ! を指定すると、シェルコマンドが一切作成されず、
binary refinery はライブラリとしてのみインストールされます。
REFINERY_NO_EXTENSIONS=1 を設定すると、Cython 拡張なしでインストールされます。
その場合、refinery はいくつかのアルゴリズムについて(はるかに遅い)純粋な Python 実装を使用します。
現在の refinery の HEAD をインストールしたい場合は、pip パッケージの代わりにこのリポジトリを指定して、上記のすべての手順を繰り返すことができます。
例えば、以下を実行すると最新の refinery コミットがインストールされます:
pip install -U --no-cache-dir git+git://github.com/binref/refinery.git
最後に、[REMnux][remnux-main]を使用している場合は、その[refinery docker container][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]
これにより、必須の依存関係に加えて すべて の依存関係がインストールされます。 より正確には、以下の追加カテゴリが利用可能です:
| 名前 | 含まれる依存関係 |
|---|---|
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 サブディレクトリにあります。