AI Assembly Explainer

A local tool that explains Windows DLLs in plain English, and a REA-style agent that answers questions about them with evidence. The disassembler produces the facts; a local Qwen model only explains them. Based on the project plan AI Assembly Explainer — Project Plan.pdf.

Core idea: stages 1–4 are ordinary code and always correct; only the explain stage uses the model, and a validator catches it when it names something that is not in the assembly. Every claim in the agent's report cites the tool call, address and bytes it came from.

Layout

dll_analyzer/
  tools.py         static triage / exports / imports            (pefile, Windows-ok)
  disasm.py        functions, basic blocks, CFG, pseudo-C        (radare2 + r2ghidra)
  explain.py       Qwen block/function/DLL notes + name check    (Ollama)
  render.py        Graphviz SVG + interactive Cytoscape HTML      (graphviz)
  capabilities.py  capa matches + FLOSS strings                  (flare-capa/floss)
  dotnet.py        .NET detection + ilspycmd C#                  (dnfile/ilspycmd)
  evidence.py      SQLite evidence log, E-ids, support check     (stdlib)
  report.py        observed/inferred/unknown report, validator   (stdlib)
  registry.py      the one shared tool list
  agent.py         local Qwen tool-calling agent loop            (Ollama)
  backends.py      lazy backend imports (never break the import)
pipeline.py        Part 1 end-to-end: extract -> explain -> render -> report
server.py          Part 2 MCP server (Claude Code / Cursor / any client)
app.py             Streamlit UI
testdlls/          testlib.c + build.sh -> four .dll variants
benchmark/         questions.yaml with answer keys
tests/             test_tools.py (needs Windows), test_validation.py (anywhere)

Backend imports are lazy: the package imports with only pefile present, and each stage raises one clear "install X" message if its tool is missing. So the static layer and the stdlib logic run on Windows today; the rest runs once the Linux toolchain is installed.

Related MCP server: Antardrishti

Status

Easiest way: the GUI (Windows)

python gui.py          # or double-click run_gui.bat / gui.pyw

A windowed DLL browser so you never hunt for paths:

• Running processes tab — pick a process, see every DLL it has loaded with its full path on disk (a mini process-manager view).

• Folder scan tab — scan System32 / SysWOW64 or any folder (optionally recursive), with a live filter box.

Select any DLL and the buttons analyse it in place: Triage, Exports, Imports and Disassemble (graph) run now on Windows; Reverse-engineer runs the full pipeline if the Linux stack is present, otherwise copies the exact WSL command for that file to your clipboard. Open folder / Copy path for the rest.

IDA/Ghidra-style graph view (Disassemble (graph))

Opens a window with a function list, a control-flow graph (basic blocks as boxes, IDA-coloured edges: blue = unconditional, green = branch taken, red = fall-through), a flat disassembly tab, and a C/pseudocode panel. The disassembler is Capstone (pip install capstone), so the graph and the C-style skeleton work on Windows with no WSL. The "AI explain" button fills the C panel with Qwen's plain-English reconstruction, grounded on the assembly, when a local Ollama is reachable (a WSL ollama serve counts — localhost forwards into Windows). Real decompilation to C is Ghidra/Hex-Rays territory; the skeleton shows the true branch structure and the LLM supplies intent.

Or the terminal menu

python run.py

A text menu with everything — GUI, triage, pipeline, agent, UI, build, tests. It shows which backends are installed and, if you pick something that needs a tool you don't have yet, tells you exactly what to install instead of crashing. No need to remember any of the commands below.

Setup (Windows, what works now)

python -m pip install -r requirements.txt
python run.py                                     # then pick 1 (triage) or 2 (symbols)
python -m unittest discover -s tests -v           # test_validation runs; test_tools needs Windows DLLs

Triage a DLL or list its symbols:

python -m dll_analyzer.tools triage  "C:/Windows/System32/kernel32.dll"
python -m dll_analyzer.tools exports "C:/Windows/System32/kernel32.dll" CreateFile
python -m dll_analyzer.tools imports "C:/Windows/System32/kernel32.dll" ntdll

Setup (Linux VM, the full pipeline)

sudo apt install -y git build-essential graphviz python3-pip python3-venv mingw-w64
git clone https://github.com/radareorg/radare2 && radare2/sys/install.sh
r2pm -ci r2ghidra                                 # decompiler plugin (pseudo-C)
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5-coder:7b                       # explainer
ollama pull qwen2.5:14b                            # agent planner (or :7b)
python3 -m venv venv && source venv/bin/activate
pip install -r requirements-full.txt

Build the benchmark DLLs, then run the pipeline and the agent:

bash testdlls/build.sh
python pipeline.py testdlls/build/test_O0.dll --out out/ --limit 10
python -c "from dll_analyzer.agent import run; print(run('Does this DLL touch the registry?', 'testdlls/build/test_O0.dll')['answer'])"
streamlit run app.py

Register the MCP server with Claude Code to test the tools with a strong model first:

claude mcp add dll-analyzer -- python /absolute/path/server.py

Important Ollama setting: the default context window is tiny. explain.py and agent.py already set num_ctx (16384 / 32768); keep it, or long functions get silently truncated.

Scope and ethics

Analyse only DLLs you compiled yourself, open-source libraries, or software whose licence permits reverse engineering — many commercial EULAs forbid it. Packed or obfuscated binaries (VMProtect, Themida) are out of scope; UPX files can be unpacked first with upx -d. .NET DLLs are bytecode, detected by triage_dll and routed to the dotnet branch. State this in the report; examiners look for it.