binviz

バイナリ可視化＆トリアージツール：単一の共有アドレス空間モデル上で、リンクされた対話型ビュー（エントロピー、ヒストグラム、画像/ドットプロットサーフェス、制御フローグラフ）を提供します。

pipx install binviz && binviz serve

機能概要

ファイルを開くと、すべてのビューが同じアドレス空間を参照します。1つのビューで範囲を選択すると、他のビューも連動します — 目的は「この領域は何か」という問いに、複数の視点から同時に答えることです。

• マッピング。 binviz model は LIEF を通じて ELF/PE/Mach-O をリージョン、シンボル、オフセット↔仮想アドレス対応に解析し、ギャップとオーバーレイを具体化します。不正な入力は失敗するのではなく、生のモデルにフォールバックします。
• 注目すべき部分を見つける。 ウィンドウ化エントロピーやその他の名前付きシグナル、バイトクラスおよびヒルベルトサーフェス、そして手動ではなく実測されたグラウンドトゥルースコーパスからの閾値に対するウィンドウ分類（ARCHITECTURE.md §2.1）。パック、暗号化、コード、パディングは互いに異なって見えます。
• エンコーディングを特定する。 バイグラムおよびスパーストライグラムヒストグラム、繰り返しと自己相似性のためのドットプロット、15種類のパック済みピクセルフォーマットと24種類のベイヤーモードに対応した画像ビュー — ストライド提案機能付き。なぜなら、誤った行ストライドは写真を斜めのノイズに変え、写真が存在しないと結論づけてしまうからです。
• コードを読む。 線形スイープと再帰下降による Capstone デコード（objdump との差分テスト済み）、ジャンプテーブルを含む5段階の関数発見カスケード、ワーカー内でレイアウトされる制御フローグラフ — 復元された境界の不確実性は隠すのではなく描画されます。
• 判定を得る。 binviz triage はファイルがどのように見えるか、そしてその理由を示します。UIでは各発見事項が、その由来となったバイトへクリックで移動できます。

UIは5つのワークスペース — Overview、Bytes、Patterns、Code、All — で構成され、同じ選択範囲を共有します。静的解析のみ：サンプルは解析され、実行されることはありません。

スクリーンショット

プレート

UIが描画するのと同じコードでCLIから直接レンダリングされます — python docs/make_plates.py で再生成できます。

静的バイナリ	同じプログラム、UPXパック
コード、文字列、パディングが明確な領域に分離します。	構造が均一なノイズに崩壊 — パッキングの特徴です。
ウィンドウ化エントロピーは帯状で低いままです。	アンパッキングスタブまで平坦で高い状態が続きます。

正しい行ストライド	誤った行ストライド

同じバイト、1つの数値だけが異なります。これがストライド提案機能が存在する理由です：誤った行ストライドは写真を斜めのノイズに変え、写真が存在しないと結論づけてしまうからです。

ARCHITECTURE.md はその構成方法を示しています：何が提供されるか、すべてのサーフェスが継承するブランディング、新しい画面が従うべき規約、そして意図的な制限事項です。SECURITY.md はセキュリティ態勢です。

クイックスタート

python -m venv .venv
# -c はスイートがグリーンである正確なバージョンに固定します；pyproject.toml は
# 範囲を公開するため、これがないと今日解決されるバージョンが使われます
.venv/Scripts/pip install -e ".[dev]" -c constraints-dev.txt   # POSIX: .venv/bin/pip

# グラウンドトゥルースコーパスを構築（ziglang pip パッケージの zig cc を使用；
# UPX が PATH、$UPX、または corpus/tools/upx-*/ に解凍されている必要があります）
make -C corpus                            # または: python corpus/build.py

# 閾値はハードコードではなく実測されます（ARCHITECTURE.md §2.1 参照）
python corpus/calibrate.py                # corpus/calibration.json を書き込み

pytest                                    # 機能スイート
pytest -m perf -s                         # 100 MB パフォーマンスターゲット

binviz probe  corpus/out/hello_O2
binviz model  corpus/out/hello_upx
binviz signal corpus/out/hello_upx --name entropy_4096 --png out.png
binviz hist   corpus/out/ramp16.bin --n 2 --dtype u16le --png bigram.png

# サーフェス: -p はサーフェスパラメータを渡します
binviz surface corpus/out/hello_static --name hilbert -p mode=byteclass --png h.png
binviz surface corpus/out/rgb_raw.bin  --name image -p mode=rgb8 -p width=320 --png i.png
binviz surface corpus/out/repeats.bin  --name dotplot -p mode=exact --png d.png
binviz stride  corpus/out/bayer_raw.bin --mode bayer_RGGB_RGB_12

# コード
binviz disasm    corpus/out/hello_O2 --limit 20
binviz functions corpus/out/hello_static --sort size
binviz cfg       corpus/out/hello_O2 --func main --dot main.dot

# 判定とその理由
binviz triage corpus/out/hello_upx

サーバーの実行

binviz serve                              # 127.0.0.1:8000

セッショントークンを含むURLが表示されるので、それを開いてください。すべての /api ルートはトークンを必要とします。なぜなら「localhost のみでリッスンする」ことは、別のタブのWebページに対する防御にはならず、他のオリジンと同様に 127.0.0.1 に到達できるからです。SECURITY.md にその理由が記載されています。

ファイルアクセスは --root（デフォルト：作業ディレクトリ）に制限されており、その外のパスは拒否されます。

制限

4つすべてにフラグと環境変数があり、4つすべてがローカル呼び出しが意図以上にリソースを消費するのを防ぐために存在します。デフォルトはラップトップ向けに選択されています。マシンがより大きい場合は引き上げてください。

フラグ	環境変数	デフォルト	制限する内容
--max-cache BYTES	BINVIZ_MAX_CACHE	5 GiB	キャッシュされた解析の合計サイズ。これを超えると、最も最近使用されていないエントリが退避されます — 解析中または表示中のものは決して退避されません。
--max-upload BYTES	BINVIZ_MAX_UPLOAD	8 GiB	受け入れ可能な最大アップロードサイズ。
--max-analyses N	—	4	同時解析数。これを超えると /api/open は 503 を返します。
--root DIR	—	cwd	サーバーがファイルを読み取れるディレクトリ。

解析は ~/.cache/binviz（または $BINVIZ_CACHE）にコンテンツハッシュをキーとしてキャッシュされるため、バイナリを再度開くのは即座です。より多く保持したい場合は --max-cache を引き上げてください。キャッシュはいつでも手動で削除しても安全です — 最悪の場合、次回のオープンで再解析されるだけです。

その他のフラグ：--token は再起動をまたいでトークンを固定します（BINVIZ_TOKEN を読み取る Vite dev プロキシで便利）、--port、--cache、CI 用の --no-auth。--no-auth は何を無効にしたかを示すバナーを表示します。共有マシンでは使用しないでください。

デスクトップウィンドウ

pip install "binviz[app]"
binviz app                    # ネイティブウィンドウ；--browser でブラウザを使用

binviz serve と同じサーバー、同じトークン、同じ --root 制限 — 違いは表示方法だけです。pywebview がインストールされていない場合、binviz app は代わりにブラウザを開きます。

提供中のURLを意図的に表示します：UIをウィンドウにラップしてもネットワークリスナーは削除されず、存在を忘れやすくなるだけです。リスナーはいずれにせよ認証されており、binviz app には --no-auth はありません。

ウィンドウはページに対して正確に1つの関数 — ネイティブファイルピッカー — のみを公開し、それ以外は何も公開しません。そのリストがなぜこれほど短いかの理由は src/binviz/app.py を参照してください。

スタンドアロンアプリのビルド

リリースはホイールのみを提供します。capstone と lief をバンドルし、パックされたバイナリの解析のために存在する署名なしのフリーズ済み Python 実行可能ファイルは、まさに SmartScreen と AV ヒューリスティックが誤検知するプロファイルです — そのため、それを提供する代わりに、リポジトリには自分でビルドするために必要なものが含まれており、コード署名を完全に回避します。

pip install pyinstaller                # 6.x
python tools/build_ui.py               # web/ をビルドし、パッケージにステージング
pyinstaller packaging/binviz.spec      # -> dist/binviz/

約100 MB を想定してください。numpy と lief が大部分を占めます。これは onedir バンドルであり、単一の自己解凍ファイルではありません：デスクトップウィンドウ用に dist/binviz/binviz.exe を起動するか（またはダブルクリック）、任意のサブコマンドを渡します — dist/binviz/binviz.exe triage sample.exe — フリーズ済みビルドはウィンドウだけでなくCLI全体だからです。

ステージング手順は必須です。web/dist は Python パッケージの外にあるため、これをスキップするとウィンドウが JSON 404 で開くアプリが生成されます。spec はこれを静かに起こさせずにビルドを拒否します。

macOS では同じコマンドで packaging/icons/icon.icns からブランド化された dist/Striate.app も生成されます。どちらも Mac で実行されたことはありません — ARCHITECTURE.md §5 を参照してください。

--root は依然として作業ディレクトリをデフォルトとするため、ダブルクリックされた実行可能ファイルは起動したフォルダに制限されます — 通常はアプリ自身のフォルダです。ショートカットの「作業フォルダー」を設定するか、--root DIR を指定して起動してください。