recurse

IDE agentico di reverse engineering con disassembler multi-architettura in puro Rust, decompilatore nativo, debugger e agente LLM per l'analisi di binari e attività CTF.

recurse-agent è solo l'agente; l'analisi statica risiede in recurse-static e il debugger in recurse-debug, così l'agente non tira dentro codice di sistema che non utilizza. Nessun crate dipende da Tauri, e ciascuno si compila/testa in modo autonomo; recurse-eval pilota l'agente in modalità headless. Tutti sono membri del workspace, quindi un solo Cargo.lock e una sola target/ coprono l'intero repository.

Funzionalità

• Workspace in stile Cursor: lista delle funzioni, tab disassembly/strings/imports, grafo CFG, e una sidebar chat dell'agente (attivabile con il pulsante Chat o Ctrl+L)
• Pagina Recon: informazioni sul binario, hash MD5/SHA1/SHA256/CRC32, entropia, librerie collegate, un report di hardening autocontenuto (RELRO / PIE / NX / canary / FORTIFY / RPATH — nessun checksec esterno), e conteggi dell'analisi
• Rinomina le funzioni dalla lista (doppio clic o pulsante ✎); i nomi persistono in SQLite e compaiono nella lista delle funzioni, nelle annotazioni del disassembly e all'agente
• Agente grounded: ogni indirizzo è un oggetto cliccabile (lista funzioni, nodi del grafo, xref, annotazioni del decompilatore) — non testo incollato che il modello può allucinare
• Sessione di analisi live su qualsiasi binario — inclusi file senza estensione
• Memoria di progetto persistente in SQLite con retrieval FTS5/BM25 — rinomine, risultati e note sopravvivono a /clear e alla riapertura, e alimentano la sessione successiva
• Core headless (recurse-agent) con tracing di debug per turno; lo stesso loop dell'agente gira nella UI e nell'harness di eval
• Agente LLM basato su un endpoint compatibile OpenAI (OpenRouter di default) con un selettore di modello; pilota direttamente la sessione (disasm, xrefs, strings, imports, decompile)
• UI dark-first costruita con Tailwind CSS v4 + shadcn/ui
• Operazione lift: eleva una funzione in un IL di de-obfuscation in stile VTIL ed esegue passate di propagazione/folding/dead-code-elimination/branch-resolution sull'intera routine — utile quando il disassembly sembra un dispatcher di VM o una catena di predicati opachi (vedi docs/vtil-lift.md)
• Decompilatore nativo: decompile produce pseudocodice simile al C (if/while structuring, copertura totale delle istruzioni) dalla stessa pipeline recurse-vtil — nessuno strumento esterno, r2 non richiesto
• Server recurse-mcp standalone: lo stesso Engine su MCP stdio per qualsiasi agente compatibile MCP (Claude Code, Cursor, Claude Desktop, …) — niente Tauri, niente licenza IDA, niente bridge Python (vedi docs/recurse-mcp.md)

Backend di analisi

L'analisi passa attraverso un singolo trait Engine (crates/recurse-static/src/engine.rs), quindi il motore è una scelta, non una dipendenza obbligata:

• native (default) — parsing ELF/PE/Mach-O puro-Rust e disassembly multi-architettura (object + capstone): x86/x86-64, ARM, AArch64, MIPS, PowerPC, RISC-V, SPARC, SystemZ, M68K, BPF. Nessun processo figlio, nessuno strumento esterno, nessun LGPL nella build. Include un decompilatore (la pipeline lift → optimize → structure di recurse-vtil — vedi docs/vtil-lift.md) e un'operazione lift per la de-obfuscation in stile VTIL.
• r2 (radare2) — supportato come alternativa opt-in per installazioni che vogliono il suo decompilatore più completo o una console raw. Installa r2 e selezionalo come motore; gira come processo separato e non è mai linkato o incluso in bundle con Recurse.

Scegli con il menu delle impostazioni, la variabile d'ambiente RECURSE_BACKEND, o la configurazione salvata. L'agente ottiene un unico strumento analyze neutro rispetto al backend (functions, disasm, graph, lift, decompile, xrefs, strings, imports, info, più raw per la console del motore) — filtrato alle operazioni che il motore attivo supporta effettivamente, quindi raw (il native non ha console) è pubblicizzato solo quando disponibile. La UI consuma tipi di risultato canonici, non il JSON di alcun motore. Vedi docs/backends.md per il trait, le scelte dei crate e la motivazione sulla licenza. Aprire un binario grande è veloce perché l'analisi è lazy — la discovery indicizza le funzioni in modo economico e i basic block vengono decodificati solo quando una funzione viene visualizzata; vedi docs/lazy-analysis.md.

Perché non semplicemente MCP-to-IDA / farlo alla leggera in Claude Code?

Attaccare un server MCP a IDA/Ghidra, o incollare disassembly in un agente CLI, funziona per CTF da 5 funzioni e crolla su binari reali. Recurse è un ambiente costruito appositamente, non un wrapper di chatbot:

• World-model del binario, non scraping di testo. Funzioni, xref, stringhe e il CFG sono stato di prima classe condiviso dall'agente e dalla UI. Niente ri-parsing di dump pdF nel contesto ad ogni turno, niente 0x401023 inventati.
• Verifica > generazione. Nel RE non esiste npm test — la verifica è visiva. Le rinomine dell'agente si propagano alla lista delle funzioni, al grafo e al decompile istantaneamente, così un umano conferma o rifiuta con un clic.
• Costruito per scalare. Il malware reale ha 10k funzioni. Strumenti on-demand + memoria persistente battono il dump di decompile completi fino all'esaurimento del contesto.
• Motore agentabile. Un motore scriptabile e pipeable significa che gli agenti possono eseguire 100 turni, fare fork, reset e diff — e puoi effettivamente distribuirlo. Il motore nativo di default non richiede alcuno strumento esterno.
• Sicuro per il malware di default. Local-first, routing BYO-key/OpenRouter, e un percorso verso modelli offline — nessuna exfiltration forzata di campioni verso un chatbot cloud.

Prerequisiti

1. Toolchain principali

Verifica:

2. Motore di analisi

Il motore native di default è puro Rust — niente da installare. Per usare r2 (radare2) come motore di analisi, installalo e selezionalo (il menu delle impostazioni, o RECURSE_BACKEND=r2); Recurse pilota il binario r2 nel tuo PATH. r2 è opzionale, non è mai richiesto dalla build, e non è mai distribuito con Recurse — porta la tua installazione.

3. Dipendenze di sistema Tauri Linux

Debian/Ubuntu/Pop!_OS:

Altre distro: segui i prerequisiti Tauri ufficiali.

4. Decompilatore

Entrambi i motori ne forniscono uno: native produce pseudocodice tramite recurse-vtil (lift → optimize → structure — vedi docs/vtil-lift.md), niente da installare; r2 può fornire il proprio decompilatore più completo quando il suo plugin è installato.

Build

Le dipendenze dell'app risiedono in tauri/; Rust proviene dalla radice del workspace. just incapsula entrambi (vedi just --list), oppure pilotali direttamente.

Sviluppo

Questo avvia il server di sviluppo Vite e lancia la finestra Tauri. La prima compilazione richiede un po' (build Rust); le successive sono veloci.

Binario di produzione

Il bundle finisce in target/release/bundle/ (target del workspace):

• .deb / .rpm / .AppImage per Linux
• binario standalone in target/release/recurse

Su Arch e altre distro rolling lo step AppImage richiede una correzione locale una tantum (linuxdeploy upstream è indietro rispetto alla toolchain della distro) — vedi docs/linux-appimage-build.md.

Solo il frontend (senza shell desktop)

Controlli di qualità

Comandi diretti equivalenti: cargo clippy --workspace --all-targets, cargo test --workspace alla radice; npm run lint / npm run format / npm run build dentro tauri/.

Eval

L'agente è valutato in modalità headless contro tier di crackme (vedi crates/recurse-eval/README.md). I tier sono YAML: filtri di selezione sul dataset, o una lista congelata di hexid, più parametri di esecuzione.

eval-run è un binario, non un test, quindi cargo test non spende mai denaro o tempo sull'agente. Endpoint + key vanno in crates/recurse-eval/.env (copia .env.example). Ogni esecuzione scrive target/eval-traces/<tier>/<backend>/run.log (la narrazione completa) più un <hexid>.json per task con la conversazione completa per turno. Il backend (native o r2) è selezionabile per esecuzione — vedi il README di eval.

LLM dell'agente

Il pannello chat dell'agente gira su qualsiasi endpoint compatibile OpenAI. Configura la API key, la base URL e il modello dalla finestra Model & Provider in-app (persistita in ~/.recurse/recurse.db), o tramite env:

Modelli locali / base URL personalizzata

Punta l'agente a qualsiasi server compatibile OpenAI locale o self-hosted — Ollama, LM Studio, llama-server di llama.cpp, vLLM, text-generation-webui, o un gateway remoto. Imposta la Base URL nella finestra (sia una base URL nuda che una route completa /chat/completions funzionano) e scegli un modello dal catalogo di quel server, o digita un id di modello (llama3.1:8b, qwen2.5-coder, …) direttamente:

Gli endpoint locali non richiedono API key: quando la key è vuota la richiesta viene inviata senza header Authorization, e la lista dei modelli viene letta dal {base}/models dell'endpoint stesso. Un endpoint personalizzato è considerato configurato senza key, quindi la chat funziona out of the box contro un server locale.

Senza credenziali ricade su un client echo così il wiring resta esercitabile.

L'agente vede il contesto live del binario (arch, bits, tipo) e può pilotare l'intera superficie di analisi (disassembly, xrefs, strings, imports, decompilazione) attraverso la sessione.

Licenza

Apache-2.0 — © 2026 Aayush Khanna