Initial public release: dockerized reverse-engineering workbench

ChipBench packages Ghidra, radare2, binwalk, chip-programming tools,
simulators, and firmware-unpacking utilities into one reproducible container
for analyzing raw chip dumps entirely from the command line or an AI CLI.
Headless Jython scripts drive import, forced-disassembly sweeps, live
queries, and bulk decompilation exports without any GUI.

Derived from a private engagement environment, generalized for public
release under AGPLv3. No engagement-specific artifacts are included.

💘 Generated with Crush

Assisted-by: Crush:glm-5.2
This commit is contained in:
2026-08-18 11:15:05 -05:00
commit 1b447b77ad
28 changed files with 1860 additions and 0 deletions
+22
View File
@@ -0,0 +1,22 @@
#!/usr/bin/env bash
# Container entrypoint. Two modes:
# - default ("supervisor"): launch the desktop + Ghidra + MCP bridge
# - anything else: exec the given command (used by `docker compose run` for
# headless analysis, interactive shells, etc.)
set -euo pipefail
# Ensure the Ghidra project / output trees exist and are writable by our user.
mkdir -p /data/work /data/output /home/chip/.vnc
# (Re)create the VNC password file from $VNC_PASSWORD (default: chiprev).
VNC_PASSWORD="${VNC_PASSWORD:-chiprev}"
if [ ! -f /home/chip/.vnc/passwd ]; then
x11vnc -storepasswd "${VNC_PASSWORD}" /home/chip/.vnc/passwd >/dev/null 2>&1
fi
if [ "${1:-}" = "supervisor" ] || [ "$#" -eq 0 ]; then
exec /usr/bin/supervisord -c /opt/conf/supervisord.conf
fi
# Pass-through: headless analyze, shell, one-off tools, etc.
exec "$@"
@@ -0,0 +1,68 @@
# -*- coding: utf-8 -*-
#
# Part of ChipBench (AGPLv3). SPDX-FileCopyrightText: 2026 Starting Line Productions LLC
# Analyze8051.py -- force-disassemble a raw 8051 binary and re-run analysis.
# Raw binary imports leave no entry points, so Ghidra finds 0 functions.
# This script disassembles from the reset + interrupt vectors, re-analyzes,
# then sweeps remaining undefined bytes in populated code regions.
from ghidra.app.cmd.disassemble import DisassembleCommand
from ghidra.program.model.address import AddressSet
from ghidra.app.plugin.core.analysis import AutoAnalysisManager
prog = currentProgram
codeSpace = prog.getAddressFactory().getAddressSpace("CODE")
if codeSpace is None:
codeSpace = prog.getAddressFactory().getDefaultAddressSpace()
def A(x):
return codeSpace.getAddress(x)
# 8051 interrupt vectors (standard set; enhanced variants may extend)
vectors = [0x0000, 0x0003, 0x000B, 0x0013, 0x001B, 0x0023, 0x002B, 0x0033, 0x003B]
for v in vectors:
cmd = DisassembleCommand(A(v), None, True)
cmd.applyTo(prog, monitor)
instr = prog.getListing().getNumInstructions()
print("After vector disassembly:", instr, "instructions")
mgr = AutoAnalysisManager.getAnalysisManager(prog)
mgr.reAnalyzeAll(None)
mgr.startAnalysis(monitor)
instr = prog.getListing().getNumInstructions()
funcs = prog.getFunctionManager().getFunctionCount()
print("After analysis:", instr, "instructions,", funcs, "functions")
# Sweep remaining undefined bytes in all populated regions, 1KB at a time.
# String islands (0x9250-0x9F00, 0xEF00-0xF400) stay data; the rest is code.
listing = prog.getListing()
memory = prog.getMemory()
SKIP = set(range(0x9200, 0x9F00, 0x400)) | set(range(0xEE00, 0x10000, 0x400))
for base in range(0x0000, 0xF400, 0x400):
if base in SKIP:
continue
blk = memory.getBlock(A(base))
if blk is None:
continue
# skip fully-erased ranges
erased = True
for i in range(base, base + 0x400, 32):
b = memory.getByte(A(i))
if (b & 0xFF) != 0xFF:
erased = False
break
if erased:
continue
rng = AddressSet(A(base), A(min(base + 0x3FF, 0xF3FF)))
sweep = DisassembleCommand(A(base), rng, True)
sweep.applyTo(prog, monitor)
mgr.reAnalyzeAll(None)
mgr.startAnalysis(monitor)
instr = prog.getListing().getNumInstructions()
funcs = prog.getFunctionManager().getFunctionCount()
print("Final:", instr, "instructions,", funcs, "functions")
@@ -0,0 +1,56 @@
# -*- coding: utf-8 -*-
#
# Part of ChipBench (AGPLv3). SPDX-FileCopyrightText: 2026 Starting Line Productions LLC
# AutoFuncs.py -- create functions at every LCALL/LJMP target + scheduler
# jumptable entries, iterating until stable. Handles call tables (JMP @A+DPTR)
# where the table entries are LJMPs by treating table bodies as code.
from ghidra.program.model.address import AddressSet
from ghidra.app.cmd.function import CreateFunctionCmd
from ghidra.app.cmd.disassemble import DisassembleCommand
from ghidra.app.plugin.core.analysis import AutoAnalysisManager
prog = currentProgram
af = prog.getAddressFactory()
cs = af.getDefaultAddressSpace()
fm = prog.getFunctionManager()
mem = prog.getMemory()
def A(x): return cs.getAddress(x)
def mk(a):
if a < 0x10000 and fm.getFunctionAt(a) is None:
CreateFunctionCmd(a).applyTo(prog, monitor)
rounds = 0
prev = -1
while rounds < 4:
n = 0
for i in range(0x0000, 0xEE00):
try:
b = mem.getByte(A(i)) & 0xFF
except:
continue
if b == 0x12 or b == 0x02: # LCALL/LJMP
try:
hi = mem.getByte(A(i+1)) & 0xFF
lo = mem.getByte(A(i+2)) & 0xFF
except:
continue
t = (hi << 8) | lo
if 0x0008 <= t < 0xEE00:
if fm.getFunctionAt(A(t)) is None:
if CreateFunctionCmd(A(t)).applyTo(prog, monitor):
n += 1
# reanalyze
mgr = AutoAnalysisManager.getAnalysisManager(prog)
mgr.reAnalyzeAll(None)
mgr.startAnalysis(monitor)
cur = fm.getFunctionCount()
print("round %d: +%d new, total %d" % (rounds, n, cur))
if cur == prev:
break
prev = cur
rounds += 1
print("AutoFuncs done: %d functions, %d instructions" % (
fm.getFunctionCount(), prog.getListing().getNumInstructions()))
@@ -0,0 +1,65 @@
# -*- coding: utf-8 -*-
#
# Part of ChipBench (AGPLv3). SPDX-FileCopyrightText: 2026 Starting Line Productions LLC
# ExportAll.py -- Jython bulk export (no javac needed).
# Produces <prog>.functions.txt, .strings.txt, .segments.txt, .decompiled.c
import os
from ghidra.app.decompiler import DecompInterface
from ghidra.app.decompiler import DecompileOptions
outdir = os.environ.get("DECOMPILE_OUT", "/data/output")
prog = currentProgram
name = prog.getName()
fm = prog.getFunctionManager()
rm = prog.getReferenceManager()
print("ExportAll.py -> %s" % outdir)
# functions
with open(os.path.join(outdir, name + ".functions.txt"), "w") as fh:
for f in fm.getFunctions(True):
fh.write("%s @ %s\n" % (f.getName(), f.getEntryPoint()))
print("functions: %d" % fm.getFunctionCount())
# segments
with open(os.path.join(outdir, name + ".segments.txt"), "w") as fh:
for b in prog.getMemory().getBlocks():
fh.write("%s %s-%s %d %s%s\n" % (b.getName(), b.getStart(), b.getEnd(),
b.getSize(), "R" if b.isRead() else "-", "W" if b.isWrite() else "-"))
# strings (defined string data)
with open(os.path.join(outdir, name + ".strings.txt"), "w") as fh:
di = prog.getDataTypeManager()
listing = prog.getListing()
it = listing.getDefinedData(True)
n = 0
while it.hasNext():
d = it.next()
dt = d.getDataType()
if dt is not None and ("string" in dt.getName().lower() or "char" in dt.getName().lower()):
try:
v = d.getValue()
except:
v = None
if v is not None and len(str(v)) >= 3:
fh.write("%s: %r\n" % (d.getAddress(), str(v)))
n += 1
print("strings: %d" % n)
# decompile everything
ifc = DecompInterface()
ifc.setOptions(DecompileOptions())
ifc.openProgram(prog)
nf = 0
with open(os.path.join(outdir, name + ".decompiled.c"), "w") as fh:
fh.write("// Decompiled by ExportAll.py (Ghidra %s)\n" % "11.3.2")
for f in fm.getFunctions(True):
res = ifc.decompileFunction(f, 90, monitor)
if res.decompileCompleted():
fh.write("\n/* ==== %s @ %s ==== */\n" % (f.getName(), f.getEntryPoint()))
fh.write(res.getDecompiledFunction().getC())
nf += 1
else:
fh.write("\n/* ==== %s @ %s : DECOMPILE FAILED ==== */\n" % (f.getName(), f.getEntryPoint()))
ifc.dispose()
print("decompiled: %d" % nf)
print("ExportAll.py done")
@@ -0,0 +1,21 @@
# -*- coding: utf-8 -*-
#
# Part of ChipBench (AGPLv3). SPDX-FileCopyrightText: 2026 Starting Line Productions LLC
# MakeFuncs.py -- create functions at hex addresses given as script args.
# Usage: -postScript MakeFuncs.py 0x1234 0x0a07 ...
from ghidra.program.model.address import AddressSet
from ghidra.app.cmd.function import CreateFunctionCmd
args = getScriptArgs()
af = currentProgram.getAddressFactory()
fm = currentProgram.getFunctionManager()
for a in args:
addr = af.getAddress(a[2:] if a.startswith("0x") else a)
if addr is None:
print("bad addr: %s" % a); continue
if fm.getFunctionAt(addr) is not None:
print("exists: %s" % addr); continue
cmd = CreateFunctionCmd(addr)
ok = cmd.applyTo(currentProgram, monitor)
print("create %s -> %s" % (addr, ok))
print("MakeFuncs done")
+291
View File
@@ -0,0 +1,291 @@
# -*- coding: utf-8 -*-
#
# Part of ChipBench (AGPLv3). SPDX-FileCopyrightText: 2026 Starting Line Productions LLC
# Query.py -- headless query interface for chat-driven reverse engineering.
# Usage:
# analyzeHeadless <projDir> <proj> -process <prog> -noanalysis -readOnly \
# -scriptPath <dir> -postScript Query.py <command> [args...]
#
# Commands: info, funcs, decompile, disasm, xrefs-to, xrefs-from,
# func-xrefs, strings, segments, data, search, func, mem
from ghidra.app.decompiler import DecompInterface
import jarray
args = getScriptArgs()
if len(args) == 0:
print("Usage: Query.py <command> [args...]")
print("Commands: info, funcs, decompile, disasm, xrefs-to, xrefs-from,")
print(" func-xrefs, strings, segments, data, search, func, mem")
else:
cmd = args[0]
rest = args[1:]
fm = currentProgram.getFunctionManager()
rm = currentProgram.getReferenceManager()
mem = currentProgram.getMemory()
af = currentProgram.getAddressFactory()
def arg(i, default):
if i >= len(rest):
return default
try:
return int(rest[i])
except ValueError:
return default
def parseAddr(s):
try:
return af.getAddress(s)
except:
return None
def resolveFunc(s):
a = parseAddr(s)
if a is not None:
f = fm.getFunctionAt(a)
if f is None:
f = fm.getFunctionContaining(a)
if f is not None:
return f
for f in fm.getFunctions(True):
if f.getName() == s:
return f
return None
if cmd == "info":
print("Name: " + currentProgram.getName())
print("Language: " + str(currentProgram.getLanguageID()))
print("Compiler: " + str(currentProgram.getCompilerSpec().getCompilerSpecID()))
print("Executable: " + str(currentProgram.getExecutablePath()))
print("ImageBase: " + str(currentProgram.getImageBase()))
print("Size: " + str(mem.getSize()) + " bytes")
print("Functions: " + str(fm.getFunctionCount()))
print("Segments:")
for b in mem.getBlocks():
r = "R" if b.isRead() else "-"
w = "W" if b.isWrite() else "-"
x = "X" if b.isExecute() else "-"
print(" " + b.getName() + " " + str(b.getStart()) + "-" + str(b.getEnd()) + " (" + str(b.getSize()) + "B) " + r + w + x)
elif cmd == "funcs":
off = arg(0, 0)
lim = arg(1, 200)
flt = rest[2] if len(rest) > 2 else None
i = 0
shown = 0
for f in fm.getFunctions(True):
if flt is not None and flt.lower() not in f.getName().lower():
continue
if i < off:
i += 1
continue
if shown >= lim:
break
print(f.getName() + " @ " + str(f.getEntryPoint()))
shown += 1
i += 1
print("--- " + str(shown) + " shown (offset " + str(off) + ") ---")
elif cmd == "decompile":
if len(rest) < 1:
print("decompile needs a name or address")
else:
f = resolveFunc(rest[0])
if f is None:
print("No function found for: " + rest[0])
else:
d = DecompInterface()
d.openProgram(currentProgram)
r = d.decompileFunction(f, 60, monitor)
if r is not None and r.decompileCompleted():
for line in r.getDecompiledFunction().getC().split("\n"):
print(line)
else:
print("Decompilation failed")
d.dispose()
elif cmd == "disasm":
if len(rest) < 1:
print("disasm needs an address")
else:
f = resolveFunc(rest[0])
if f is None:
print("No function at/containing: " + rest[0])
else:
end = f.getBody().getMaxAddress()
listing = currentProgram.getListing()
it = listing.getInstructions(f.getEntryPoint(), True)
from ghidra.program.model.listing import CodeUnit
while it.hasNext():
ins = it.next()
if ins.getAddress().compareTo(end) > 0:
break
cmt = listing.getComment(CodeUnit.EOL_COMMENT, ins.getAddress())
line = str(ins.getAddress()) + ": " + ins.toString()
if cmt is not None:
line += " ; " + cmt
print(line)
elif cmd == "xrefs-to":
if len(rest) < 1:
print("xrefs-to needs an address")
else:
lim = arg(1, 200)
a = parseAddr(rest[0])
if a is None:
print("Bad address: " + rest[0])
else:
n = 0
it = rm.getReferencesTo(a)
while it.hasNext():
if n >= lim:
break
ref = it.next()
ff = fm.getFunctionContaining(ref.getFromAddress())
extra = " in " + ff.getName() if ff is not None else ""
print("From " + str(ref.getFromAddress()) + extra + " [" + ref.getReferenceType().getName() + "]")
n += 1
print("--- " + str(n) + " reference(s) to " + str(a) + " ---")
elif cmd == "xrefs-from":
if len(rest) < 1:
print("xrefs-from needs an address")
else:
lim = arg(1, 200)
a = parseAddr(rest[0])
if a is None:
print("Bad address: " + rest[0])
else:
refs = rm.getReferencesFrom(a)
n = 0
for ref in refs:
if n >= lim:
break
tf = fm.getFunctionAt(ref.getToAddress())
extra = " (" + tf.getName() + ")" if tf is not None else ""
print("To " + str(ref.getToAddress()) + extra + " [" + ref.getReferenceType().getName() + "]")
n += 1
print("--- " + str(n) + " reference(s) from " + str(a) + " ---")
elif cmd == "func-xrefs":
if len(rest) < 1:
print("func-xrefs needs a function name")
else:
lim = arg(1, 200)
total = 0
for f in fm.getFunctions(True):
if f.getName() != rest[0]:
continue
it = rm.getReferencesTo(f.getEntryPoint())
while it.hasNext():
if total >= lim:
break
ref = it.next()
ff = fm.getFunctionContaining(ref.getFromAddress())
extra = " in " + ff.getName() if ff is not None else ""
print("From " + str(ref.getFromAddress()) + extra + " [" + ref.getReferenceType().getName() + "]")
total += 1
print("--- " + str(total) + " reference(s) to function '" + rest[0] + "' ---")
elif cmd == "strings":
flt = rest[0] if len(rest) > 0 else None
lim = arg(1, 500)
shown = 0
it = currentProgram.getListing().getDefinedData(True)
while it.hasNext() and shown < lim:
d = it.next()
tn = d.getDataType().getName().lower()
if "string" not in tn and "char" not in tn and tn != "unicode":
continue
v = str(d.getValue()) if d.getValue() is not None else ""
if flt is not None and flt.lower() not in v.lower():
continue
print(str(d.getAddress()) + ": \"" + v[:120] + "\"")
shown += 1
print("--- " + str(shown) + " string(s) ---")
elif cmd == "segments":
for b in mem.getBlocks():
print(b.getName() + ": " + str(b.getStart()) + " - " + str(b.getEnd()) + " (" + str(b.getSize()) + " bytes)")
elif cmd == "data":
off = arg(0, 0)
lim = arg(1, 200)
i = 0
shown = 0
for b in mem.getBlocks():
it = currentProgram.getListing().getDefinedData(b.getStart(), True)
while it.hasNext():
d = it.next()
if not b.contains(d.getAddress()):
break
if i < off:
i += 1
continue
if shown >= lim:
break
lbl = d.getLabel() if d.getLabel() is not None else "(unnamed)"
print(str(d.getAddress()) + ": " + lbl + " = " + d.getDefaultValueRepresentation())
shown += 1
i += 1
print("--- " + str(shown) + " data item(s) ---")
elif cmd == "search":
if len(rest) < 1:
print("search needs a query")
else:
lim = arg(1, 200)
shown = 0
for f in fm.getFunctions(True):
if rest[0].lower() in f.getName().lower():
if shown >= lim:
break
print(f.getName() + " @ " + str(f.getEntryPoint()))
shown += 1
print("--- " + str(shown) + " match(es) ---")
elif cmd == "func":
if len(rest) < 1:
print("func needs an address")
else:
f = resolveFunc(rest[0])
if f is None:
print("No function at/containing: " + rest[0])
else:
print("Name: " + f.getName())
print("Entry: " + str(f.getEntryPoint()))
print("Signature: " + f.getSignature())
print("Body: " + str(f.getBody().getMinAddress()) + " - " + str(f.getBody().getMaxAddress()))
print("Size: " + str(f.getBody().getNumAddresses()) + " bytes")
elif cmd == "mem":
if len(rest) < 2:
print("mem needs <addr> <len>")
else:
a = parseAddr(rest[0])
length = arg(1, 64)
if a is None:
print("Bad address: " + rest[0])
else:
buf = jarray.zeros(length, "b")
got = mem.getBytes(a, buf)
ubuf = [(x & 0xFF) for x in buf[:got]]
hexstr = ""
ascstr = ""
for idx in range(got):
v = ubuf[idx]
hexstr += "%02x " % v
ascstr += chr(v) if (32 <= v < 127) else "."
if (idx + 1) % 16 == 0:
base = a.add(idx - 15)
print("%s %-48s %s" % (base, hexstr, ascstr))
hexstr = ""
ascstr = ""
if hexstr:
print("%s %-48s %s" % (a, hexstr, ascstr))
else:
print("Unknown command: " + cmd)
print("Commands: info, funcs, decompile, disasm, xrefs-to, xrefs-from,")
print(" func-xrefs, strings, segments, data, search, func, mem")