## 概要

IDA Proの自動解析はシングルスレッドです。34MBのil2cpp DLLでは*数分*かかります。spectrIDAはバイナリをN個のシャードに分割し、idalibを介して並列実行し、1つの`.i64`にマージした後、微調整された8Bモデルで**すべての関数に名前を付け**ます。しかも、サイバーパンクテーマと絶妙な皮肉が効いた1つのターミナルUIからすべてを実行できます。

それが第1章であり、単独で完結しています。純粋な速度向上であり、必要なければAIは不要です。

第2章では、出力をセッションを超えて存続するものに変換します。MCPクライアント（Claude、[pi](https://pi.dev)、MCPを話す任意のもの）が実際に利用できるNeo4jグラフを生成し、あなたがデコンパイラの出力を1関数ずつチャットウィンドウにコピーペーストする必要がなくなります。```
Binary  ─▶  Parallel IDA Analysis  ─▶  Demangle  ─▶  AI Naming  ─▶  Neo4j Graph  ─▶  MCP Server  ─▶  Claude
              (N idalib shards)       (free, real)   (stripped     (persists,        (search/chain/
                                                       leftovers     forever,          rename, live)
                                                       only)         across sessions)

必要条件: **IDA Pro 9.x** with idalib · **Python 3.10+** · **Ollama**```bash
# install Ollama (Windows)
winget install Ollama.Ollama

# pull the model (8.7 GB — go get coffee)
ollama pull hf.co/gdfhhjk/spectrida-re-gguf:latest

# first run — detects your IDA install and sets everything up
spectrida onboard

# or just try the demo right now
spectrida --demo

## TUIキー

| キー | アクション |
|-----|--------|
| `N` | 選択した関数に名前を付ける — AIが結果をライブストリーミング |
| `R` | 名前変更 — AIの提案で事前入力 |
| `D` | 逆コンパイルされた擬似コードの切り替え (Hex-Rays) |
| `C` | 呼び出しチェーン — 呼び出し元と呼び出し先 |
| `B` | 現在のリスト内のすべての `sub_*` 関数を一括で命名 |
| `O` | 概要 — バイナリ全体のAI要約 |
| `/` | あいまい検索 |
| `?` | ヘルプ |
| `Q` | 終了 |

## プログラムAPI

TUIは不要 — スクリプト、Claude Code、ノートブックなどからspectrIDAを駆動:```python
import asyncio
from spectrida.api import open_i64

async def main():
    async with open_i64("GameAssembly.i64") as db:

        # list all 153k functions
        funcs = await db.list_functions()

        # name one function — returns name + reasoning + confidence
        result = await db.name_function(0x10001000)
        print(result["new_name"])     # init_atexit_handler
        print(result["reasoning"])    # allocates array of 3 fn ptrs, calls _atexit...

        # batch name everything (with live progress)
        async def on_progress(done, total, r):
            print(f"  {done}/{total}  {r['old_name']} -> {r['new_name']}")

        await db.batch_name(limit=500, rename=True, progress_cb=on_progress)

        # ask what the binary does
        overview = await db.overview()
        print(overview)

        # export to IDA script
        await db.export("names.idc", fmt="idc", named_only=True)

asyncio.run(main())

環境変数の上書き: `SPECTRIDA_IDALIB` · `SPECTRIDA_MODEL` · `SPECTRIDA_WORKERS` · `SPECTRIDA_OLLAMA_URL`

---

## 新しいバイナリ形式の追加

フォーマット対応はプラグインシステムであり、if/elif の山ではありません — PE、NSO、ELF はすべて `spectrida/analysis/formats/` 以下のファイルで、自動的に発見されます。現在登録されているものを確認するには、`spectrida formats` を実行してください。```bash
$ spectrida formats
ELF        spectrida.analysis.formats.elf.ELFHandler
NSO        spectrida.analysis.formats.nso.NSOHandler
PE         spectrida.analysis.formats.pe.PEHandler
generic    spectrida.analysis.formats.generic.GenericHandler

@staticmethod
def sniff(header: bytes, path: str) -> bool:
    return header[:4] == b"MYF0"          # however you recognize the format

def prepare(self, path: str, workdir: str) -> PreparedImage:
    # Format idalib already loads natively (ELF, PE, Mach-O)? Just parse
    # the section/segment table — return the original path unchanged.
    return PreparedImage(
        binary_path=path,
        image_base=0,
        sections=[Section(name=".text", va=0x1000, raw_off=0x400,
                           raw_size=0x2000, vsize=0x2000, is_code=True)],
        arch=None,        # set "x86_64"/"arm64" only if IDA can't detect it itself
    )

# Only needed if idalib has NO native loader for this format (NSO is the
# example): do any manual idaapi/ida_segment setup here, called right
# after idapro.open_database() succeeds, before analysis starts.
# def post_open(self) -> None: ...

That's the whole contract:

| Method | Required? | What it does |
|---|---|---|
| `sniff(header, path)` | yes | Magic-byte/extension check — does this handler own the file? |
| `prepare(path, workdir)` | yes | Return a `PreparedImage`: the file idalib should open + its section table |
| `post_open()` | no (default no-op) | Manual segment setup for formats with no native IDA loader (see `nso.py`) |
| `make_shard_binary(image, dst, va_start, va_end)` | no (default works) | Override only if zeroing out-of-shard section bytes is wrong for your format (see `nso.py` — never zero a compressed file) |
| `code_range(image)` | no (default works) | Override only if "min/max of `is_code` sections" isn't the right answer |
| `read_bytes(image, va_start, va_end)` | no (default works) | Override if `prepare()` already holds the relevant bytes in memory (NSO) instead of on disk |
| `global_entry_points(image, text_start, text_end)` | no (default: None) | Only override if a per-shard local scan would miss real entry points — NSO needs this because AArch64 leaf functions are only discoverable via BL targets seen elsewhere in the binary, not a local prologue scan |

| メソッド | 必須? | 説明 |
|---|---|---|
| `sniff(header, path)` | はい | マジックバイト/拡張子チェック — このハンドラがファイルを所有しているか？ |
| `prepare(path, workdir)` | はい | `PreparedImage` を返す：idalib が開くファイル + そのセクションテーブル |
| `post_open()` | いいえ (デフォルトは何もしない) | ネイティブIDAローダーがないフォーマット向けの手動セグメント設定（`nso.py`参照） |
| `make_shard_binary(image, dst, va_start, va_end)` | いいえ (デフォルトで動作) | シャード外のセクションバイトをゼロにすることがフォーマットにとって間違っている場合のみオーバーライド（`nso.py`参照 — 圧縮ファイルは決してゼロにしない） |
| `code_range(image)` | いいえ (デフォルトで動作) | 「`is_code` セクションの最小/最大」が正しい答えでない場合のみオーバーライド |
| `read_bytes(image, va_start, va_end)` | いいえ (デフォルトで動作) | `prepare()` が関連するバイトをディスクではなくメモリに保持している場合（NSO）にオーバーライド |
| `global_entry_points(image, text_start, text_end)` | いいえ (デフォルト: None) | シャードごとのローカルスキャンで実際のエントリポイントを見逃す場合のみオーバーライド — NSOではこれが必要。なぜなら、AArch64のリーフ関数はローカルのプロローグスキャンではなく、バイナリ内の別の場所で見られるBLターゲットを介してのみ発見可能だからです。 |

Look at `formats/pe.py` for the simplest possible handler (pure header parsing, no overrides) and
`formats/nso.py` for the full case (wraps decompression + manual segment setup + every override).

最も単純なハンドラ（純粋なヘッダーパース、オーバーライドなし）については `formats/pe.py` を参照し、完全なケース（展開のラッピング + 手動セグメント設定 + すべてのオーバーライド）については `formats/nso.py` を参照してください。

Third-party packages can register a handler too, without touching spectrIDA's source at all, via
the `spectrida.formats` entry-point group:

サードパーティパッケージも、spectrIDAのソースに一切触れずに、`spectrida.formats` エントリポイントグループを介してハンドラを登録できます。```toml
# in a separate package's pyproject.toml
[project.entry-points."spectrida.formats"]
myformat = "spectrida_myformat_plugin:HANDLER"

それだけです。Claude Codeとpiにサーバーを自動登録し（`mcp` + `neo4j`が不足している場合は、素の`pip install spectrida`でスキップされた場合にプルインします）、設定を書き込み、どの再起動が必要かを通知します。

**Neo4jが起動している状態で、Claudeが実際に取得するもの（`spectrida`のconfig `[graph]`セクション、またはローカルインスタンスを指定するだけ）：**

- `search_functions` / `get_function` / `get_callees` / `get_callers` / `trace_chain` — 高速なキャッシュ済みグラフ読み取り。`get_function`は疑似コード**と**逆アセンブリ（厳密な命令境界とオペランド — 疑似コードだけでは得られない層であり、「これは何をするか」から「これをパッチする正確な場所はどこか」に移行する瞬間に重要）に加えて、インラインの呼び出し元/呼び出し先を返すため、Claudeはレスポンス内で呼び出し先がまだ`sub_*`かどうかを確認することで、さらに深くチェーンするかどうかを判断できます — 何も見るものがないことを確認するためだけの余分な往復は不要です。
- `get_full_pseudocode` / `rename_function` — キャッシュされたスニペットでは不十分な場合や、名前がついに判明した場合に、ライブで信頼性の高い読み取り/書き込みを`.i64`に直接行います。
- `analyze_binary` — 未解析のバイナリ（PEまたはNSO、どちらでも並列シャーディング）を渡すと、パイプライン全体（解析 → デマングル（Itanium **および** MSVC） → 本当にストリップされた残骸にAI命名 → すべてをグラフにプッシュ）を1つのバックグラウンドジョブとして実行し、ポーリング可能なので、数分かかる実行でも会話をブロックしません。
- `doctor` / `start_all` — チャットを離れずにllama-server + Neo4jを確認または起動。llama-server自体がどこにもインストールされていない場合、`start_all`はwinget（Windows）またはbrew（macOS）経由で先にそれを取得します — 別途llama.cppのダウンロード/セットアップは不要です。

魔法ではありません — 誰もまだ見ていないために`sub_140001234`のままの関数は、やはり`sub_140001234`のままです。しかし、グラフはモデルが**解明した**すべてを永久に、セッションをまたいで記憶し、Claudeは一度に1つの関数を見つめる代わりに、既にコードベースを読んだ同僚のようにそれを辿ることができます。

**今後提供予定：**

- **深いコンテキスト命名** — コールツリーをNレベル深く追跡し、完全なチェーンをモデルに提供。`encrypt_block`から3ホップ先の関数は、自分が暗号パスにいることを認識できるはず。
- **難読化解除** — TigressVMパターン検出とハンドラトレーシング
- **実際のパッチ適用** — 逆アセンブリがグラフに格納されたので、エージェントはバイトレベルのパッチを計画**できます**。「ここが変更すべき正確な命令」を「そしてここが書き込みだ」に変えるのが次のステップです。

---

## 第3章 — 幽霊は壁をすり抜ける

第1章と第2章はバイナリを読み込み、それを記憶します。しかし、関数を読むことはそれが**何であるか**を教えるだけで、トリガーを引いたときに**何をするか**は決して教えません。第3章 — [**phantomrt**](https://pypi.org/project/phantomrt/) — がトリガーを引きます。```bash
pip install "spectrida[atlas]"

**そして、上記のNSOのホラーストーリーの精神に基づいて：** 最初の実際のバグハントは正直に*何も*見つけられませんでした — そしてその理由はクラッシュよりも興味深いものでした。本当に古く、本当に脆弱なFreeTypeを狙ったブランドファジングはゼロでした。カバレッジガイドファジングは見事な**64,000エッジ**をカバーしたと報告しました — しかしそれは嘘で、バイナリがPIEであり、ASLRが毎回アドレスを静かに再ランダム化していたため、「新しいカバレッジ」のほとんどはローダーがデッキをシャッフルしていただけでした。ASLRを無効にすると、正直な数字は*実際の*727エッジに落ち着き、そこで頭打ちになります — なぜならすべてのシードがTrueTypeフォントだったため、ファザーは1つのパーサーに閉じ込められ、バグが実際に存在するCFF/Type1/BDFコードに構造的に変異することができませんでした。修正はよりスマートなミューテーターではなく、より良いシードでした：エージェントが実際のOpenType/Type1/BDFサンプルを取得し、1回のファズ反復の前にカバレッジは727 → 4,013に跳ね上がり、適切に探索されました。それでも予算内ではクラッシュは発生しません — これは通常数時間かかるジョブに対して1コアで3分間実行した正直な状態です。仕組みは本物です。報告する代わりに、*自分自身の*偽の番号を捕まえました。それがすべての要点です。

**正直なゴースト免責事項：** phantomrtは`0.1.0`です。アルファ版です。堅牢な動的レイヤーであり、魔法のバグオラクルではありません — おもちゃのターゲットでは仕掛けられたバグを即座に見つけ、実際のターゲットでは行き詰まったとき（`needs_state`）、クラッシュが*候補*に過ぎないとき（ポインタが実際に入力制御されているか確認してください）、そしてより多くの時間とより良いシードが必要なときを正直に教えてくれます。Switchバイナリはライブで実行できません — Fridaは起動できるものを必要とします — そのため、エミュレーションが唯一の方法であり、`needs_state`が頻繁に表示されます。それは正直であり、壊れているわけではありません。

それは意図的に重い追加機能です（`torch`, `unicorn`, `frida`）— ベースの `pip install spectrida` では何もインストールされません。ソースは [`phantomrt/`](https://github.com/ggfuchsi-oss/spectrida-reverse_engineering_stack/blob/HEAD/phantomrt/) にあります；独自のゴースト風味のREADMEは[こちら](https://github.com/ggfuchsi-oss/spectrida-reverse_engineering_stack/blob/HEAD/phantomrt/README.md)です。

*静的ゴーストはあなたの関数に名前を付けます。こちらはそれらを告白させます。* 👻

---

## ライセンス

MIT. 好きに使ってください。動けばクール。動かなければ、GGUF量子化のせいにしてください。

意地とコーヒーとRTX 4070で作られました。
このモデルはマーケティングゼロで199回ダウンロードされています。ダウンロードごとに開発速度が0.01%向上します。
（これは真実ではありません。しかし近いです。）👻