dex-analyzer-for-llm (dexllm)

LLM-facing Android APK / DEX static analyzer: a C++ core (pybind11 wrapper around LuckyPray/DexKit) with an embedded, fully ported DAD-aligned Java decompiler, plus MCP and FastAPI/SSE backends for agent integrations.

Built for mobile threat hunting / malware triage — fast, low-memory, embeddable, and parallel-safe — rather than Xposed module development.

Why

See docs/workflow.md for how dexllm operates end to end (load → verify → search → decompile → agent, all diagrammed), docs/usage.md for the task-oriented API walkthrough (L1–L7 + decompile), docs/api.md for the flat API reference (every method, return type, example output), docs/architecture.md for the ports-&-adapters boundary map, docs/dexkit-vs-art-dex-handling.md for how dexllm's DEX handling compares to AOSP/ART (verification, multidex, cross-dex), and CLAUDE.md for the decompiler port internals.

Architecture

Hexagonal (ports & adapters): the DAD-aligned decompiler core knows nothing about how dex bytes are loaded — it talks to the outside through one narrow port (IDexCodeSource), so the same pipeline runs on a real APK (production adapter) or hand-built snapshots (test adapter). Every byte crosses a load-time structural verifier first.

flowchart TB
    accTitle: Ports and Adapters Architecture
    accDescr: The Python API drives the decompiler facade and the DAD domain core, which reads dex only through the IDexCodeSource port. Production and test adapters implement that port, and every dex passes the VerifyDex structural verifier before the DexKit Core slicer parses it.

    python_api["Python API, MCP stdio, FastAPI/SSE"]
    pybind["pybind11 binding<br/>native/binding/module.cpp"]
    facade["Decompiler facade + LRU cache<br/>native/dad_cpp/decompiler.cpp"]
    raw_dex["raw .dex / classes*.dex"]
    verify_dex["VerifyDex structural verifier<br/>1:1 AOSP DexFileVerifier port"]
    dexkit_core["DexKit Core + slicer"]
    prod_adapter["DexItemCodeSource<br/>core_ext, production adapter"]
    mock_adapter["MockCodeSource<br/>tests, no DexKit"]
    port{{"IDexCodeSource port<br/>pure abstract"}}
    output["Java text | nested AST"]

    subgraph core["Domain core: native/dad_cpp - 1:1 androguard DAD port"]
        snapshot["MethodSnapshot, immutable DTO"]
        pipeline["graph, dataflow, control_flow"]
        emit["writer / dast"]
        snapshot --> pipeline --> emit
    end

    python_api --> pybind --> facade
    facade -->|drives| snapshot
    raw_dex --> verify_dex --> dexkit_core --> prod_adapter
    prod_adapter -->|implements| port
    mock_adapter -->|implements| port
    port -->|reads method code| snapshot
    emit --> output

    classDef io fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    classDef guard fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
    classDef boundary fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef domain fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f

    class raw_dex,output io
    class verify_dex guard
    class port boundary
    class snapshot,pipeline,emit domain

The boundary is enforced by scripts/check_dad_boundary.sh: native/dad_cpp/ may never #include DexKit, FlatBuffers, the zip reader, or core_ext.

Parser lineage — dexllm parses with Google's slicer (tools/dexter — a mutable heap IR built for rewriting, with no structural verification, only SLICER_CHECK assertions). ART itself parses with libdexfile (lazy zero-copy accessors + its own DexFileVerifier). They are independent AOSP libraries sharing only the dex format. dexllm therefore pairs slicer's parsing with a 1:1 port of ART's DexFileVerifier (VerifyDex, below) and of utf.cc (MUTF-8) — slicer's convenience, ART's rigor.

Why not just use libdexfile? Because it's a foundation rewrite, not a parser swap: dex::Reader is the backbone of all of DexKit Core (L1–L7 search, enumeration), and libdexfile isn't standalone-vendorable (it needs libartbase + libbase and builds with Soong, not CMake). Its one real edge — rigorous verification — we already ported. Full side-by-side + decision: docs/dexkit-vs-art-dex-handling.md §0.5.

Runtime flows — the load/verify path, the DAD decompile pipeline (Construct → BuildDefUse → … → IdentifyStructures → Writer), the L1–L7 capability ladder, and agent (MCP/FastAPI) integration are all diagrammed in docs/workflow.md.

Malformed-dex verification (vs ART DexFileVerifier)

dexllm processes adversarial input, so every dex passes a load-time structural verifier — VerifyDex (native/core_ext/dex_verifier.h, the single safety contract) — before the core parses it. A reject throws with a byte-level reason (dk.verify_report()); valid dexes are unaffected. It is a readable 1:1 port of AOSP ART's DexFileVerifier (// ART :NNNN anchors, spec-reference not runtime dep), turned to crash-safety, not execution trust.

Deliberately not checked — execution-trust mechanics irrelevant to a read-only analyzer, or out of the structural scope: adler32/SHA-1 checksums, instruction dataflow semantics, debug_info, the contents of call_site entries,² proto shorty-match, access-flag bitmasks, and the offset→map-type cross-check.³

Validated: clean corpus 0 false-reject · 29/29 C++ test suites · ASan corpus + malformed-dex fuzz 0 heap-overflow/UAF/SEGV (the same fuzz segfaults 66/120 with no structural verifier). The verifier adds ~58% to load time (still ~100× faster than androguard); decompile throughput is unaffected. Full per-check breakdown: docs/dexkit-vs-art-dex-handling.md §1.

Benchmark vs androguard

dexllm ports androguard's DAD decompiler to C++, so the comparison is pure runtime (native vs Python) and output parity, single-threaded, same APK / same methods. Reproduce with bench/bench_vs_androguard.py:

pip install -e ".[dev]"          # dexllm + androguard
python bench/bench_vs_androguard.py /path/to/app.apk

APK: com.example.android.tvleanback.apk — 4135 classes · 500-method decompile sample · single-threaded (Ryzen 9 9950X, Python 3.13):

Java decompile output parity vs androguard (indent-normalized): method byte-identical 92.4% (462/500) · whole-class byte-identical 56.5% · whole-class line-overlap 94.0%. (Byte-identical at class scale is strict — one differing line fails the whole class; line-overlap is the fairer "how close" measure.) Residual mismatches are semantic-equivalent (variable-name suffixes) or cases where dexllm emits spec-correct Java that androguard gets wrong:

• Unicode strings/identifiers — dexllm decodes dex MUTF-8 to the exact UTF-16 code units ART builds in a mirror::String (decoder ported 1:1 from art/libdexfile/dex/utf-inl.h). In a string literal — in a method body and in a static final initializer alike, by one shared escaper since dexllm#83 — it then renders those units one by one: the Java metacharacters and \n \r \t take their short escapes, any OTHER unit below 0x20 and every surrogate become \uXXXX (so a supplementary (astral) char stays a surrogate pair, exactly like ART), and everything else is written as itself — readable UTF-8 for BMP text (한글/CJK), and raw for DEL, the C1 range and U+0085 / U+2028 / U+2029. androguard DAD instead emits one \u followed by the full codepoint hex — e.g. a real-corpus U+DFFFD comes out as "\udfffd" (5 hex digits → invalid Java: the lexer reads \udfff + a literal d, silently corrupting the string), where dexllm emits the valid "\udb3f\udffd". (Verified against the actual AOSP source — see docs/dexkit-vs-art-dex-handling.md.) An IDENTIFIER is rendered readably instead (dexllm#28): a class named A𐀀sTest reads the same in decompiled Java, in the smali listing and in list_classes(), rather than splitting into A\ud800\udc00sTest in the Java pane alone. Code-unit fidelity is a claim about string CONTENT — what mirror::String actually holds — while an identifier is a source symbol; the split spelling broke correlation for anyone reading two views of the same class side by side, or pasting a class name into a hooking script. A BMP identifier (A한ysisTest) always rendered readably, so the old behaviour was inconsistent as well: it survived by unit count rather than by rule.
• Literals — boolean return false/true (not return 0/1), return null for a null reference, IEEE-754 float/double literals (1.0f, Double.NaN) where androguard prints the raw integer bits, and null/true/false field initializers (not Python None/True/False). A static initializer's float payload is zero-extended to the right, as ART reads it, so a short encoding decodes to the constant the class declares rather than to a denormal (dexllm#70). A static value with no Java expression form at all — a MethodHandle, a method reference, an annotation — rides as a trailing // = Cls::name comment rather than being dropped, so Type name; never means both "no initializer" and "one we could not spell" (dexllm#64). Both reference decompilers do worse on that family: jadx 1.5.0 loses the whole class on a MethodType or a MethodHandle (Can't decode value) and emits a bare = ; for a method reference, and androguard prints a memory address for an array or an annotation.

Parallel decompile — dexllm releases the GIL in decompile_*, so threads give real parallelism on one shared instance; androguard cannot use threads at all (GIL + non-thread-safe analysis). Full-APK decompile of the same 4135 classes:

Speedup is workload-dependent. Here it peaks at ~10.5× near the 16 physical cores (Ryzen 9 9950X is 16C/32T); the 32 logical (SMT) threads regress slightly to ~9.9× from scheduler contention, so bench_vs_androguard.py (which uses os.cpu_count() = 32) reports the 32-thread figure above. On a 39k-class app the speedup drops to ~3× because returning hundreds of MB of decompiled text becomes GIL-bound. The APK-load gap instead widens with size: that 39k-class / 5-dex app loads in ~120 ms (lazy slicer parse + linear structural verification) versus androguard's multi-second whole-program analysis.

Each tool at its realistic max — dexllm parallel (32 threads) vs androguard single-threaded (its only mode), full-APK decompile, end-to-end:

Repository layout

.
├── pyproject.toml          scikit-build-core build config
├── CMakeLists.txt          native build (drives vendor/ + native/)
├── src/dexllm/             Python package: DexKit, tools, mcp_server, server, capability, …
├── native/                 C++ sources
│   ├── core_ext/             extension over upstream DexKit (search / ref enumeration)
│   ├── dad_cpp/              DAD-aligned Java decompiler (graph/dataflow/control_flow/writer/dast)
│   └── binding/              pybind11 module (C++ ↔ Python boundary)
├── tests/                  C++ parity suites (tests/parity, ctest) + Python pytest suite
├── examples/               runnable usage examples
├── bench/                  reproducible androguard benchmark
├── docs/                   detailed API walkthrough (usage.md)
├── vendor/dexkit_core/     vendored LuckyPray DexKit Core (its own LICENSE;
│                           UPSTREAM records the baseline and the fork point, and
│                           docs/dexkit-vendor-divergences.md every local change)
├── test_apk/               APK corpus for regression (fetched separately; gitignored)
├── CLAUDE.md               decompiler port internals / dev notes
└── LICENSE                 Apache-2.0

Install

From PyPI (recommended — no toolchain)

pip install dexllm
# + LLM backends (MCP + FastAPI):
pip install "dexllm[all]"
# upgrading from an older install? plain `install` is a no-op once dexllm is
# present ("Requirement already satisfied") — you need -U:
pip install -U dexllm

Pre-built wheels for Linux (manylinux_2_28 x86_64) and macOS (x86_64 + arm64, requires macOS 13.3+), CPython 3.9–3.13, are published to PyPI. pip picks the wheel matching your platform/Python — no C++ compiler needed.

To pin a version, use a version specifier — not --find-links, which adds a source rather than replacing PyPI, so pip still resolves to the highest version it can see anywhere:

pip install "dexllm==0.11.0"
# ≤0.8.1 predates PyPI and lives only on Releases — point pip at that tag's assets:
pip install "dexllm==0.8.1" --find-links https://github.com/mobile-threat-hunter/dex-analyzer-for-llm/releases/expanded_assets/v0.8.1

The wheels are also mirrored on this repo's Releases — download a specific .whl and pip install ./that-file.whl if you'd rather not go through an index.

On a platform with no matching wheel (Windows, musllinux, PyPy, aarch64) pip falls back to the sdist and builds from source — see below for the toolchain that needs.

Build from source (development)

Requirements: Python 3.9+ and a C++20 compiler. CMake / Ninja / pybind11 / scikit-build-core are build-time deps that pip provisions automatically — you don't install them by hand.

• Linux: GCC 10+ or Clang 12+, plus zlib dev headers (apt install build-essential zlib1g-dev).
• macOS (Intel or Apple Silicon): Xcode Command Line Tools (xcode-select --install) — provides Apple Clang (C++20 from Xcode 14+) and the system zlib. No Homebrew packages required. The build is platform-agnostic (scikit-build-core resolves the wheel tag per OS/arch).

# from the repo root — same on Linux and macOS
pip install -e .                 # core (native analyzer + decompiler)
pip install -e ".[all]"          # + MCP server + FastAPI backend
pip install -e ".[dev]"          # + pytest + androguard (for tests / parity)

The mcp extra is pinned to >=1.0,<2: dexllm.mcp_server targets the mcp 1.x low-level Server API, and 2.x removed those decorators (the module then fails at import). If your environment already carries mcp 2.x, pip install -e ".[mcp]" downgrades it.

After editing C++ sources, rebuild with the two-step loop (or /dexkit-build):

cd build/cp*-cp*-* && ninja      # 1. rebuild the native lib
cd - && pip install -e . --no-build-isolation   # 2. reinstall from repo root

Quick start

import dexllm

# Probe a file by content without loading it (handles disguised/extension-less APKs)
dexllm.identify("/path/to/suspect")   # → {format, is_apk, has_manifest, dex_count, source}

# Structurally verify a dex/apk without loading — never raises (the verify() sibling of identify())
dexllm.verify("/path/to/suspect")     # → [{dex_id, name, valid, reason, source, art_deviations}, …] (per dex)

dk = dexllm.DexKit("/path/to/app.apk")   # .apk/.jar/.zip, a bare .dex, or a disguised container

# What framework APIs does it touch? (capability / threat triage)
for ref in dk.list_external_method_refs(framework_only=True)[:10]:
    print(ref.java_signature)

# Decompile
print(dk.decompile_method("Lcom/example/Foo;->bar()V"))
print(dk.decompile_class("Lcom/example/Foo;"))
ast = dk.decompile_method_ast("Lcom/example/Foo;->bar()V")   # nested AST + Java text
pc = dk.decompile_method_with_pc_map("Lcom/example/Foo;->bar()V")  # {"source", "pc_map": [(line, byte_off), …]}

# Search — and its forward direction (which strings does THIS code load?)
for m in dk.find_methods_using_strings(["http"]):
    print(m)
print(dk.list_method_strings("Lcom/example/Foo;->bar()V"))   # its const-string operands
print(dk.list_class_strings("Lcom/example/Foo;"))            # + static VALUE_STRING inits
for site in dk.find_call_sites_to("Landroid/util/Log;->d(Ljava/lang/String;Ljava/lang/String;)I"):
    print(site)

Typed API for embedding — dexllm.sdk wraps the same engine in ports & adapters (@runtime_checkable Protocol use cases + frozen-dataclass models with an accurate type on every argument/return):

from dexllm.sdk import open_apk, DexAnalysisUseCase

session: DexAnalysisUseCase = open_apk("app.apk")
session.decompile_method("Lcom/x/Y;->m(I)V")   # -> DecompiledMethod
session.permission_callers(app_only=True)      # -> tuple[PermissionCallers]

See docs/usage.md.

Typed out of the box — the wheel ships PEP 561 type stubs (py.typed + .pyi), so the native DexKit methods, the return objects (CallSite, ClassSummary, …), and the module helpers (identify, extract_iocs, …) autocomplete and type-check under mypy / pyright with no extra setup.

LLM backends (need the [all] extra):

python -m dexllm.mcp_server                 # MCP stdio (Claude Desktop / Cursor / Continue)
uvicorn dexllm.server:app --port 8000       # FastAPI + SSE web backend

The web backend's POST /upload takes the same inputs as everything else — identified by content, not by filename — and returns the identify() verdict alongside the session_id. Both servers open a sample the strict verifier refuses with lenient=True instead, and say so: /upload answers opened: "lenient" with the strict_refusal, and every MCP answer for such a session carries a session_note (dexllm#112).

Tests

# C++ parity suites (self-contained, no APK needed) — primary regression gate
cd build/cp*-cp*-* && ninja parity_tests && ctest --output-on-failure

# Python suite (skips APK-dependent tests if no APK is available)
pip install -e ".[dev]"
DEXLLM_TEST_APK=/path/to/app.apk pytest tests -v

See tests/README.md for details.

Licence

Apache-2.0 — see LICENSE. Vendored DexKit Core under vendor/dexkit_core/ keeps its own licence (vendor/dexkit_core/LICENSE).