DebuggerJ++

Debugger / disassembler con GUI per l'analisi di malware su eseguibili a 32 e 64 bit, nello stile di OllyDbg / x64dbg. Pensato per sezionare virus e malware con finalità difensive: creare firme di antivirus/antimalware, capire il comportamento e ripulire le macchine.

⚠️ Analizza sempre i campioni in una macchina virtuale isolata / sandbox, senza rete, con snapshot. Avviare un binario sotto il debugger esegue il suo codice.

Caratteristiche (v0.2)

• Aprire .exe / .dll / .sys e parsing completo del PE (32/64 bit, entrypoint, sezioni, import, export, entropia).
• Finestra CPU: disassemblaggio (Zydis) del codice, con evidenziazione di call/jmp/ret, destinazione dei salti, guide visive di flusso per jmp/jz/jnz/ecc. e l'istruzione corrente quando sei in pausa. Il menu contestuale Jump To apre la destinazione del salto.
• Breakpoint software (0xCC), hardware (DR0–DR3, esecuzione/scrittura/lettura-scrittura), per eccezione e di memoria tramite PAGE_GUARD (accesso, scrittura o esecuzione). Include lista, etichette, attivazione/disattivazione, condizioni di registri/hit, azioni di solo log e breakpoint di eventi (thread/DLL). Quelli di memoria si configurano in pausa e lavorano per pagine, come la tecnica usata da OllyDbg.
• Controlli: Play (avvia / continua), Pause, Step Into (F7), Step Over (F8), Step To Ret, Rewind (navigazione della cronologia), Stop e riavvio della sessione.
• Registri (x64: RAX..R15/RIP/EFLAGS; x86: EAX..EIP) in pausa, con modifica diretta.
• Memoria: dump hex + mappa delle regioni (VirtualQueryEx) con permessi, tipo e modulo; salto rapido a RSP, lettura/scrittura, assemblaggio con Keystone e patching/NOP.
• Strings & ricerca: estrazione di stringhe ASCII/UTF-16 e ricerca di pattern hex con wildcard (48 8B ?? C3) o testo, nel file o in memoria viva.
• Moduli & simboli: sezioni, import/export del PE, TLS callback, catena SEH x86, DLL caricate a runtime, risoluzione dei simboli con DbgHelp e sorgente/riga quando c'è un PDB.
• Navigazione e tracce: riferimenti a codice/dati, stack delle chiamate, run trace, funzioni candidate, xref/loop/bookmark persistenti, annotazioni (commenti/etichette) e salti a un indirizzo o modulo/DLL. Un doppio clic su un modulo apre il suo codice nella CPU.
• Cache di analisi: stringhe, rilevamenti di packer e annotazioni vengono salvati in cache/ accanto al debugger. Vengono riutilizzati alla riapertura di un file e invalidati se cambiano la sua dimensione, data di modifica o la lunghezza minima delle stringhe.
• Sessioni e report: sessioni .dbgjsession con annotazioni e breakpoint; esportazione di report Markdown con obiettivo, sezioni, rilevamenti, stato e breakpoint.
• Packer: rilevamento tramite firme (set integrato + signatures/userdb.txt in stile PEiD) ed euristica di entropia / sezioni sospette.
• Unpacking assistito: ricerca dell'OEP, dump memory-aligned, risoluzione e ricostruzione sperimentale dell'IAT, e opzioni anti-anti-debug per un'analisi controllata.
• Pannello IA multiagente: Anthropic/Claude, ChatGPT/OpenAI, DeepSeek, Gemini, Grok, Mistral, Groq, OpenRouter, Ollama e LM Studio. La chat può includere automaticamente registri, stack e disassemblaggio corrente.
• Tools per IA: abilitando Permitir control del debugger (tools), l'agente può consultare o controllare la sessione: aprire/avviare/riavviare, continuare o mettere in pausa, fare passi, leggere memoria e registri, disassemblare, cercare, impostare breakpoint, navigare verso DLL, applicare patch ed eseguire le altre operazioni esposte dal debugger.
• Finestra Code: trasforma una routine in pseudocodice C++ esplicativo usando il disassemblaggio, la memoria, i simboli e i moduli. È un'interpretazione per l'analisi, non una recupero letterale del codice sorgente.
• MCP: server locale compatibile con strumenti MCP affinché un agente esterno controlli DebuggerJ++. Consulta mcp/README.md.
• Plugin estensibili: manifest JSON e DLL native x64 opzionali in plugins/ aggiungono azioni alla UI e tool dinamici all'MCP. Le DLL vengono caricate solo quando l'utente attiva espressamente l'opzione e devono essere affidabili. Consulta docs/PLUGINS.md.
• Interfaccia configurabile: pannelli separabili, visibilità persistente, mosaico e layout personalizzati in stile OllyDbg/x64dbg.

Compilare (Windows)

Compila solo su Windows con MSVC perché utilizza la Windows Debug API, DbgHelp, Direct3D 11 e WinHTTP.

1. Installa Visual Studio 2022 con Desktop development with C++, CMake 3.20+ e Git.

2. Doppio clic su build.bat (o da un x64 Native Tools Command Prompt):

   build.bat
   

   CMake scaricherà solo (FetchContent) Zydis, Dear ImGui e nlohmann/json.

3. Esegui build\Release\DebuggerJ++.exe come Amministratore (per poter eseguire il debug).

Uso rapido

1. File → Apri .exe. Vengono popolati CPU, sezioni, stringhe e la scansione dei packer.
2. Imposta un breakpoint sull'EntryPoint (pannello Breakpoints) e premi Play (avvia).
3. Il processo si ferma al breakpoint del loader; premi di nuovo Play per raggiungere il tuo breakpoint. Da lì usa Step Into / Step Over, ispeziona Registri e Memoria, cerca stringhe e chiedi all'agente IA riguardo all'ASM.
4. In Window → Code, usa Usa RIP e Interpreta come C++ per ottenere una spiegazione della routine corrente.

Agenti IA e API key

Configura gli agenti in Tools → Options → AI. Al primo avvio vengono rilevate, se presenti, le variabili ANTHROPIC_API_KEY e OPENAI_API_KEY; puoi anche incollare una chiave nel form di un agente. ChatGPT/OpenAI è offerto come preset ChatGPT (OpenAI).

Le credenziali vengono salvate unicamente in ai_config.json accanto all'eseguibile per l'uso locale dell'applicazione. Non caricare quel file né file .env nel repository: sono già esclusi da .gitignore.

Per consentire all'agente di agire, seleziona un provider/modello compatibile con function calling e abilita Consenti controllo del debugger (tools) nella finestra IA. La finestra Code limita l'agente a strumenti di consultazione per non alterare il processo.

Architettura

Vedi docs/ARQUITECTURA.md.

Licenza

DebuggerJ++ è distribuito sotto la GNU General Public License v3.0 o successiva (GPL-3.0-or-later). Puoi usarlo, studiarlo, modificarlo e ridistribuirlo secondo quei termini. Le dipendenze di terze parti conservano i propri avvisi e licenze.

Limitazioni e prossimi miglioramenti

È una base funzionale per l'analisi difensiva. Aree previste per una prossima versione:

• Condizioni avanzate espresse come regole/espressioni per i breakpoint.
• Aggancio a processi già in esecuzione, monitoraggio dei processi figli e miglior controllo dei thread.
• Simboli PDB più completi, informazioni sul sorgente e stack walking robusto quando non ci sono frame pointer.
• Persistenza completa delle sessioni, esportazione di report e una vista a grafo del flusso di controllo.
• Validazioni aggiuntive per le operazioni di modifica e miglioramenti nella ricostruzione dell'IAT.