## O que é

A análise automática do IDA Pro é single-threaded. Em uma DLL il2cpp de 34 MB, são *minutos*. spectrIDA divide o binário em N fragmentos, executa-os em paralelo via idalib, mescla em um único `.i64` e, em seguida, permite que um modelo 8B ajustado **nomeie cada função** — tudo a partir de uma única interface de terminal com tema cyberpunk e exatamente a quantidade certa de sarcasmo.

Esse é o Capítulo 1, e ele se sustenta por si só: pura velocidade, sem necessidade de IA se você não quiser.

O Capítulo 2 transforma a saída em algo que sobrevive à sessão — um grafo Neo4j no qual um cliente MCP (Claude, [pi](https://pi.dev), qualquer um que fale MCP) pode realmente viver, em vez de você copiar e colar a saída do descompilador em uma janela de chat, uma função de cada vez:```
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)

Requisitos: **IDA Pro 9.x** com 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

---

## Teclas da TUI

| Tecla | Ação |
|-----|--------|
| `N` | Nomear função selecionada — a IA transmite o resultado ao vivo |
| `R` | Renomear — pré-preenchido com a sugestão da IA |
| `D` | Alternar pseudocódigo descompilado (Hex-Rays) |
| `C` | Cadeia de chamadas — chamadores e chamados |
| `B` | Nomear em lote todas as funções `sub_*` na lista atual |
| `O` | Visão geral — resumo da IA de todo o binário |
| `/` | Pesquisa difusa |
| `?` | Ajuda |
| `Q` | Sair |

---

## API Programática

Nenhuma TUI necessária — controle o spectrIDA a partir de scripts, Claude Code, notebooks, etc.:```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())

Env var overrides: `SPECTRIDA_IDALIB` · `SPECTRIDA_MODEL` · `SPECTRIDA_WORKERS` · `SPECTRIDA_OLLAMA_URL`

---

## Adicionando um novo formato binário

O suporte a formatos é um sistema de plugins, não uma pilha de ramificações if/elif — PE, NSO e ELF são apenas arquivos em `spectrida/analysis/formats/`, descobertos automaticamente. Execute `spectrida formats` para ver o que está registrado atualmente.```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)` | sim | Verificação de bytes mágicos/extensão — este handler é o dono do arquivo? |
| `prepare(path, workdir)` | sim | Retorna uma `PreparedImage`: o arquivo que o idalib deve abrir + sua tabela de seções |
| `post_open()` | não (padrão sem operação) | Configuração manual de segmentos para formatos sem um loader IDA nativo (veja `nso.py`) |
| `make_shard_binary(image, dst, va_start, va_end)` | não (padrão funciona) | Sobrescreva apenas se zerar bytes de seção fora do shard estiver errado para seu formato (veja `nso.py` — nunca zere um arquivo comprimido) |
| `code_range(image)` | não (padrão funciona) | Sobrescreva apenas se "mín/máx das seções `is_code`" não for a resposta correta |
| `read_bytes(image, va_start, va_end)` | não (padrão funciona) | Sobrescreva se `prepare()` já mantiver os bytes relevantes em memória (NSO) em vez de em disco |
| `global_entry_points(image, text_start, text_end)` | não (padrão: None) | Sobrescreva apenas se uma varredura local por shard perder pontos de entrada reais — NSO precisa disso porque funções folha AArch64 só são descobertas através de alvos BL vistos em outras partes do binário, não por uma varredura local de prólogo |

Veja `formats/pe.py` para o handler mais simples possível (parseamento puro de cabeçalho, sem sobrescritas) e
`formats/nso.py` para o caso completo (empacota descompressão + configuração manual de segmentos + todas as sobrescritas).

Pacotes de terceiros também podem registrar um handler, sem tocar no código-fonte do spectrIDA, através
do grupo de pontos de entrada `spectrida.formats`:```toml
# in a separate package's pyproject.toml
[project.entry-points."spectrida.formats"]
myformat = "spectrida_myformat_plugin:HANDLER"

É isso. Ele registra o servidor com Claude Code e pi automaticamente (puxando `mcp` + `neo4j` se um simples `pip install spectrida` os pulou), escreve a configuração deles e informa qual reinicialização você deve.

**O que Claude realmente obtém, uma vez que o Neo4j esteja em execução (seção `[graph]` da configuração do `spectrida`, ou apenas aponte para uma instância local):**

- `search_functions` / `get_function` / `get_callees` / `get_callers` / `trace_chain` — leituras rápidas do grafo em cache. `get_function` retorna pseudocódigo **e** desassembly (limites exatos de instrução e operandos — o que a camada de pseudocódigo não pode fornecer, o que importa no momento em que você passa de "o que isso faz" para "onde exatamente eu aplicaria um patch") além de chamadores/callees inline, para que Claude decida se aprofunda a cadeia verificando se um callee ainda é `sub_*` ali mesmo na resposta — sem viagem de ida e volta extra apenas para descobrir que não há mais nada a ver.
- `get_full_pseudocode` / `rename_function` — leituras/gravações diretas e autoritativas no `.i64` quando o trecho em cache não é suficiente ou um nome é finalmente descoberto.
- `analyze_binary` — entregue a ele um binário que nunca viu (PE ou NSO, paralelamente fragmentado de qualquer forma) e ele executa todo o pipeline — analisar → demangle (Itanium *e* MSVC) → nomear via IA os resíduos genuinamente despojados → empurrar tudo para o grafo — como um trabalho em segundo plano que você consulta, para que uma execução de vários minutos nunca bloqueie a conversa.
- `doctor` / `start_all` — verificar ou iniciar llama-server + Neo4j sem sair do chat. Se o próprio llama-server não estiver instalado em nenhum lugar, o `start_all` o obtém via winget (Windows) ou brew (macOS) primeiro — nenhum download/configuração separada do llama.cpp necessária.

Não é mágica — uma função que ainda é `sub_140001234` porque ninguém olhou para ela ainda continua sendo `sub_140001234`. Mas o grafo lembra de tudo que o modelo *descobriu*, para sempre, entre sessões, e Claude pode percorrê-lo como um colega que já leu o código-fonte, em vez de ficar olhando para uma função de cada vez.

**Ainda por vir:**

- **Nomeação de contexto profundo** — seguir árvores de chamada N níveis de profundidade, alimentar a cadeia completa para o modelo. Uma função a 3 saltos de `encrypt_block` deve saber que está no caminho cripto.
- **Deofuscação** — detecção de padrões TigressVM e rastreamento de handlers
- **Aplicação real de patches** — o desassembly está no grafo agora, então um agente *pode* planejar um patch no nível de byte; transformar "aqui está a instrução exata para mudar" em "e aqui está a escrita" é o próximo passo.

---

## Capítulo 3 — o fantasma atravessa paredes

Os Capítulos 1 e 2 leem o binário e o lembram. Mas ler uma função diz o que ela *é*, nunca o que ela *faz* quando você puxa o gatilho. O Capítulo 3 — [**phantomrt**](https://pypi.org/project/phantomrt/) — puxa o gatilho.```bash
pip install "spectrida[atlas]"

**E, no espírito da história de terror da NSO acima:** a primeira verdadeira caçada de bugs honestamente não encontrou
*nada* — e a razão foi mais interessante do que um travamento teria sido. Apontado para um
FreeType genuinamente antigo, genuinamente vulnerável, o fuzzing cego obteve zero. O fuzzing guiado por cobertura então
relatou um triunfante **64.000 arestas** cobertas — o que era mentira, porque o binário era PIE e
ASLR estava silenciosamente re-randomizando os endereços a cada execução, então "nova cobertura" era principalmente o carregador
embaralhando o baralho. Desabilitar ASLR, o número honesto cai para *reais* 727 arestas, e estabiliza
lá — porque cada semente era uma fonte TrueType, então o fuzzer ficou preso dentro de um analisador e
não conseguiu mutar estruturalmente seu caminho para o código CFF/Type1/BDF onde os bugs realmente vivem. O
conserto não foi um mutador mais inteligente, foram melhores sementes: o agente buscou amostras reais OpenType/Type1/BDF,
a cobertura saltou 727 → 4.013 antes de uma única iteração de fuzzing, e explorou corretamente.
Ainda assim, nenhum travamento no orçamento — que é o estado honesto de uma execução de 3 minutos em um núcleo contra um
trabalho que normalmente leva horas. A maquinaria é real. Ela pegou seu *próprio* número falso em vez de
reportá-lo. Esse é o ponto principal.

**Disclaimer honesto de fantasma:** phantomrt é `0.1.0`. Alfa. É uma camada dinâmica sólida, não um oráculo
mágico de bugs — encontrou bugs plantados em um alvo de brinquedo instantaneamente, e em alvos reais diz honestamente
quando está travado (`needs_state`), quando um travamento é apenas um *candidato* (vá verificar se o ponteiro
é realmente controlado por entrada), e quando precisa apenas de mais tempo e melhores sementes. Binários do Switch
não executam ao vivo — Frida precisa de algo que possa lançar — então lá, emulação é a única porta
e dirá `needs_state` bastante. Isso é honesto, não quebrado.

É o extra pesado intencionalmente (`torch`, `unicorn`, `frida`) — a base `pip install spectrida`
não puxa nada disso. O código-fonte está em [`phantomrt/`](https://github.com/ggfuchsi-oss/spectrida-reverse_engineering_stack/blob/HEAD/phantomrt/); seu próprio README com sabor fantasma está
[aqui](https://github.com/ggfuchsi-oss/spectrida-reverse_engineering_stack/blob/HEAD/phantomrt/README.md).

*O fantasma estático nomeia suas funções. Este as faz confessar.* 👻

---

## Licença

MIT. Faça o que quiser com ele. Se funcionar, legal.
Se não funcionar, culpe a quantização GGUF.

Construído com rancor, café e uma RTX 4070.
O modelo tem 199 downloads com zero marketing. Cada um adiciona 0,01% à velocidade de desenvolvimento.
(Isto não é verdade. Mas está perto.) 👻