Skip to main content
Glama
walkthestars

toothpick

by walkthestars
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Toothpick turns binary executables, game containers, JVM archives, and profiler captures into a single queryable SQLite WAL graph (toothpick.db). It unpacks runtime stubs, lifts instructions across five CPU architectures (x86, x86_64, ARM64, PowerPC, MIPS), computes control-flow edges and reaching-definitions SSA facts, solves branch reachability with Z3, records verified runtime register/memory receipts, rebases hooks across version updates, and scaffolds mods for Unity IL2CPP, Unreal Engine, Godot, native C++ shared libraries, and Lua/Steam Workshop targets.

All query, scan, and Model Context Protocol (MCP) endpoints enforce strict top-K and line-count caps so AI coding agents can inspect large binaries without blowing out their context window.

Quick start

Prerequisites

  • OS: Windows 10/11 (x64) or Linux (x86_64)

  • Python: 3.11+ with uv

  • Optional host tools:

    • .NET SDK 8.0+ — only required when compiling generated C# BepInEx plugins (toothpick build --compile)

    • Ghidra 11+ (GHIDRA_INSTALL_DIR) — only required when requesting PyGhidra decompilation (toothpick static --prefer-ghidra)

    • cdb.exe (Windows Debugging Tools) — only required for live WinDbg/cdb commands (toothpick cdb)

Installation

git clone https://github.com/walkthestars/toothpick.git
cd toothpick
uv sync --locked

Core workflow in 60 seconds

# 1. Triage container format, architecture, game engine, and packer signatures
uv run toothpick triage target.exe

# 2. Unpack simple protection stubs (UPX NRV2B/D/E, XOR loaders) if flagged
uv run toothpick unpack packed_target.exe --out target.exe

# 3. Lift functions, basic blocks, CFG edges, and SSA facts into toothpick.db
uv run toothpick static target.exe --db toothpick.db

# 4. Query the call graph and SSA def-use chains under bounded budgets
uv run toothpick query --db toothpick.db callers 0x140001000 --limit 50
uv run toothpick query --db toothpick.db def_use 0x140001000 --var rax
uv run toothpick query --db toothpick.db slice 0x140001000 --target rax --direction backward

# 5. Solve branch reachability constraints to a target basic block via Z3
uv run toothpick solve 0x140001000 --target-block 0x140001080 --db toothpick.db

# 6. Ground live via Frida (--pid) or scaffold offline with --allow-unverified
uv run toothpick ground 0x140001000 --static-only --db toothpick.db
uv run toothpick hook build --target 0x140001000 --db toothpick.db --out ./my_hook --name SpeedHook --allow-unverified

Related MCP server: styx-mcp

Pipeline overview

  Target Binary / Container / JAR / Dump / IDA Extract / Profiler Capture
         │
         ├──► triage & unpack      Format/engine/packer detection, UPX & Unicorn OEP unpack
         ├──► static / jvm ingest  Capstone CFG + SSA lifting or JVM class/JAR call graph
         ├──► ingest-ida           Schema-v1 IDA Pro JSON import + name-conflict arbitration
         ├──► rtti / struct        MSVC & Itanium C++ RTTI/vtable recovery + ReClass export
         ├──► profile import       Windows ETW/WPR & JVM JFR/async-profiler hot-function ranking
         │
         ▼
  ┌─────────────────────────────────────────────────────────────────────┐
  │                     toothpick.db (SQLite WAL)                       │
  │  funcs · edges · ssa_facts · types · receipts · versions · profiles │
  └─────────────────────────────────────────────────────────────────────┘
         │
         ├──► query / show / mcp   Top-K bounded callers, callees, def-use, slicing, stdio MCP
         ├──► solve / taint        Z3 BitVec path reachability & dynamic taint tracking
         ├──► ground / scan / cdb  Frida, CEServer, WinDbg/cdb & DBI runtime receipts
         ├──► rebase               Multi-pass structural graph diffing across binary updates
         └──► build / hook / lua   Epistemic-gated Unity, Unreal, Godot, C++ & Lua mod builders

CLI reference

Run uv run toothpick <command> --help for full option lists, or see docs/CLI.md for the complete reference.

Command

Purpose

toothpick triage <target>

Identify container (PE, ELF, NSO, NRO, SELF, DOL, raw), CPU architecture, engine (Unity IL2CPP/Mono, Unreal, Godot, .NET, Native), and packer protection. Aborts with exit code 2 on hypervisor/VM protectors (PACKED_ABORT(VM_PROTECTED)).

toothpick unpack <target>

Decompress UPX/XOR stubs, trace packer entry points to the Original Entry Point (OEP) via Unicorn micro-emulation, hunt compiler prologues (--hunt-oep), or rebuild PE headers from a dump (--reconstruct-pe --oep <hex>).

toothpick static <target>

Lift instructions (x86, x86_64, ARM64, PPC, MIPS), partition basic blocks, compute CFG edges and reaching-definitions SSA facts, and upsert into toothpick.db.

toothpick query <subcommand>

Bounded graph queries: callers, callees, def_use, slice (backward/forward), and func inspection.

toothpick solve <func_addr>

Translate basic-block paths into Z3 BitVec constraints and solve for concrete register/memory inputs that reach --target-block <block_addr>.

toothpick ground <func_addr>

Capture runtime register/argument receipts via Frida (--pid/--spawn), CEServer (--backend ceserver --host ... --port ...), or offline verification (--static-only) to mark functions GROUNDED.

toothpick scan <pattern>

Bounded memory and pointer scanner over live PIDs, raw dumps (--file), or CEServer targets (--type i32|f32|string|hex|pointer, narrowing via --session).

toothpick ingest-metadata <file>

Parse Unity IL2CPP global-metadata.dat type definitions and method descriptors into toothpick.db.

toothpick ingest-ida <doc.json>

Ingest versioned ida_extract.v1.json documents produced by icepick, routing symbol collisions through the name-conflict queue.

toothpick build <target>

Generate Unity IL2CPP BepInEx/Harmony C# plugins, Unreal Engine UE4SS Lua/C++ mods (--engine unreal), or Godot GDExtension scaffolds (--engine godot). Enforces the Epistemic Grounding Gate unless --allow-unverified is passed.

toothpick hook build

Emit a self-contained CMake C++ MinHook DLL project (--target <addr> --out <dir> --name <name>) gated by grounding receipts.

toothpick lua build|pack|patch-emit

Scaffold (--class, --method, --desc), package, and emit diff patches for Lua/Steam Workshop mods.

toothpick pck list|extract

Inspect and safely extract Godot .pck resource packs.

toothpick rebase <new_target>

Diff a new binary update against --old-sha via exact digest, structural CFG similarity, semantic embeddings (--semantic), and external diff priors (--priors), outputting a port map (--out).

toothpick rtti scan <file>

Recover MSVC (_s__RTTICompleteObjectLocator) C++ class hierarchies, vtables (--base, --vtables), and demangled names.

toothpick struct

Synthesize struct layouts from memory dumps (--file) or live processes (--pid) and export ReClass.NET .rcnet, C++, C#, or JSON (--format rcnet|cpp|csharp|json).

toothpick jvm ingest <jar_or_class>

Parse JVM .class and .jar archives into toothpick.db methods, call edges, and string pools.

toothpick profile import|hottest

Import VTune/ETW/perf CSVs or JVM JFR/async-profiler captures (profile import) and rank hottest functions (profile hottest --top 50).

toothpick cdb

Run headless WinDbg/cdb.exe crash-dump triage (--dump) or non-invasive live process inspection (--pid).

toothpick dbi

Run Unicorn dynamic binary instrumentation traces (--target), generate Pin/DynamoRIO tools (--generate), or parse trace logs (--parse).

toothpick taint

Run register/memory taint analysis (--binary, --func, --source, --sink) or export Triton/Manticore scripts (--export).

toothpick bench run|compare

Execute timed command benchmarks and evaluate regression gates across runs.

toothpick show <func_addr>

Display the unified function inspection view (metadata, CFG edges, SSA facts, grounding receipts, and trace events).

toothpick ledger

Inspect token and monetary cost accounting across agent sessions (--db, --events-log).

toothpick mcp

Start the stdio Model Context Protocol server (--db toothpick.db, optional --sdk).

MCP server

Run toothpick mcp --db toothpick.db to expose 9 phase-constrained reverse-engineering tools over stdio JSON-RPC 2.0:

{
  "mcpServers": {
    "toothpick": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/toothpick",
        "run",
        "toothpick",
        "mcp",
        "--db",
        "/path/to/toothpick.db"
      ]
    }
  }
}

Exposed MCP tools

Tool

Description

toothpick_callers

Call-graph predecessors of func_addr (top-K capped, default 50, max 1,000).

toothpick_callees

Call-graph successors called by func_addr (top-K capped).

toothpick_def_use

SSA reaching-definition chains inside func_addr, optionally filtered by var_name.

toothpick_slice

Backward or forward intra-function program slice from target register/variable with max_depth and limit caps.

toothpick_get_func

Single function record (signature, basic-block count, IR/decompiled text bounded by max_lines).

toothpick_rebase

Port an address from old_sha256 to new_sha256 using stored version-rebase mappings.

toothpick_show

Full inspection card for func_addr (function record, callers/callees, SSA facts, grounding receipts, trace events).

toothpick_ledger

Token and cost accounting breakdown across model classes (Orchestrator, Solver, Bulk).

toothpick_hottest

Top-N hottest functions from imported ETW/JFR performance profiles joined against toothpick.db.

Full request/response schemas and client examples are documented in docs/MCP.md.

Epistemic Grounding Gate

Mod generators (toothpick build, toothpick hook build, toothpick lua build) refuse to emit patches targeting unverified addresses by default. A target function must hold a dynamic GROUNDED receipt in toothpick.db (recorded via toothpick ground --pid <PID> or --backend ceserver) before code generation proceeds.

  • Dynamic grounding path: Run toothpick ground <func_addr> --pid <PID> --db toothpick.db (or --backend ceserver), then run toothpick build or toothpick hook build.

  • Static-only / offline path: toothpick ground --static-only records a STATIC_FALLBACK (UNGROUNDED) receipt. To generate a mod scaffold without a live process receipt, pass --allow-unverified; generated source files and READMEs are stamped with an explicit UNVERIFIED banner.

  • IDA imports: Functions imported via toothpick ingest-ida carry UNGROUNDED provenance until verified by live toothpick ground, preventing decompiler heuristics from silently masquerading as runtime truth.

Development

uv sync --locked --dev
uv run python scripts/ci.py          # runs all 5 CI gates (ruff, uv build, pytest, coverage, license audit)
uv run pytest -p no:faulthandler     # run the test suite directly
uv run ruff check .                  # run the linter

Security & known limitations

  • Untrusted binaries: Static commands (triage, static, query, solve, rtti, jvm ingest, ingest-ida) never execute the target binary on the host OS. Dynamic commands (ground without --static-only, scan --pid, cdb --pid, dbi) attach to live processes and should only be used against untrusted targets inside an isolated VM. See SECURITY.md.

  • VM-protected binaries: Commercial virtualizing protectors (Denuvo, VMProtect, Themida) trigger an immediate PACKED_ABORT(VM_PROTECTED) (exit code 2) during triage and unpack. Use toothpick unpack --detect-vm for non-aborting forensic section/entropy inspection, or dump the process from memory at runtime and pass --reconstruct-pe --oep <hex>.

  • Intra-procedural slicing: toothpick query slice operates over intra-function SSA facts; cross-function dataflow should be combined with callers/callees traversal.

Contributing

Contributions are welcome — see CONTRIBUTING.md. Two things are asked of contributors: a Signed-off-by line on every commit (the Developer Certificate of Origin, git commit -s; CI checks it), and a one-time acceptance of the Contributor License Agreement on a contributor's first pull request.

License

AGPL-3.0-only, with commercial/enterprise dual licensing available. See LICENSE, COPYRIGHT, and CLA.md.

Running unmodified Toothpick locally places no obligations on your own code or analysis artifacts. Modifying Toothpick, distributing modified versions, or operating a modified Toothpick over a network triggers the AGPL-3.0 copyleft/network provisions — offer those modifications under the same license, or contact the Project Owner (walkthestars) for a commercial enterprise license.

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • radare2-mcp

    drvcvt
    F
    license
    B
    quality
    D
    maintenance
    Provides 85 tools for binary analysis including static analysis, disassembly, decompilation, ESIL emulation, live debugging, vulnerability scanning, and exploit development through structured JSON responses over the Model Context Protocol.
    85
    2
    -

  • styx-mcp

    jackmis0724
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides 7 reverse-engineering tools (hexdump, disasm, strings, xref, Ghidra decompilation, angr symbolic execution, OLLVM deobfuscation) for LLM agents like hermes-agent and Claude Desktop.
    1
    MIT

  • IDA MCP

    dhsgud
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to inspect, reverse engineer, decompile, and operate on binaries through IDA Pro, including headless and GUI sessions, over stdio or Streamable HTTP.
    29 npm
    MIT

  • verdex

    Yilanchia
    A
    license
    Not graded
    quality
    C
    maintenance
    Exposes read-only local analysis tools for source auditing, web traffic review, binary reverse engineering, exploit scaffolding, OSINT, and reporting via JSON-RPC over stdio, enabling LLMs to orchestrate evidence-based security workflows without executing targets or sending network requests.
    1
    MIT