agentleFS
eduardoghieduardoghi/reverse-engineering-skills/skills/binary-diff/SKILL.md

binary-diff

Skill2 starsChanged 12 days agoMITView on GitHub

Compare two builds of a native binary (PE, ELF or Mach-O executable or library) with ghidriff to find the functions that were added, removed or changed. Use when you need to know what changed between versions, whether a fix landed in a newer build, or where a patch touched the code.

  • Installs packages

7 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use browser-extension-reverse, cloud-k8s and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • zhaoxuya520Skill

    browser-extension-reverse

    Use for authorized reverse engineering of browser extensions (Chrome/Firefox) including manifest analysis, background workers, and extension-based credential or traffic logic recovery.

    Also in 3 projects that use this

  • zhaoxuya520Skill

    cloud-k8s

    Use for authorized cloud, container, and Kubernetes security assessment including metadata SSRF, IAM misconfig, container escape paths, and cluster RBAC review.

    Also in 3 projects that use this

  • Wang200935Skill

    digital-forensics

    Comprehensive CTF forensics workflows covering file type identification,

    Also in 3 projects that use this

  • Youchu-lawhubSkill

    case-review

    收到裁判文书后的研析与复盘——三级覆盖:庭审复盘(庭后五维效果分析)、裁判文书研析报告(主体/诉请与判决/请求权/事实查明/说理/裁判结果六维 + 逐页比对事实认定与证据采信、提炼胜败因)、结案复盘报告(结案报告十项 + 四维反思)。两种深度:自办案件(调取台账/事实梳理/过程文书做深度复盘)与非自办/受限信息(仅基于用户提供的裁判文书与有限信息),输出面向客户/法务领导/业务部门汇报。触发词:复盘、裁判文书分析、判决分析、研析判决、结案报告、结案复盘、办案总结、庭审复盘、败诉分析。

    Also in 3 projects that use this

  • conjure-3301Skill

    email-security

    DNS-level email authentication (SPF/DKIM/DMARC) exploitation, mail infrastructure attacks, relay abuse, and domain verification gaps — the infrastructure layer beneath email header injection

    Also in 3 projects that use this

  • +7 more from zhaoxuya520

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run it in the background and watch the log for | ghidriff | lines and Traceback.

    line 76
  2. Distinctive:

    No function was marked as changed either, because the code still pointed at the same addresses.

    line 137
  3. Very specific:

    Run analyzeHeadless from a directory without a copy of ApplyNames.java.

    line 176

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Binary diffing with ghidriff

ghidriff, a fork of clearbluejar/ghidriff with matching and report fixes, imports both files into a Ghidra project, analyzes them, matches functions (by symbol name first, then by bytes, instructions, graph structure, strings and BSim similarity) and writes a Markdown report plus JSON with every match and a decompiled diff of each changed function.

A function marked as changed is a lead, not a conclusion. The diff comes from decompiled code, so register allocation, stack layout and moved callees all show up as changes. Read the diff, and when the question depends on one branch or one store, confirm it in the disassembly of both builds.

Setup

Install the fork from its main branch, which is not on PyPI, together with the PyGhidra wheel that ships with the Ghidra install, so the Python package matches the Ghidra version.

uv venv ~/.venvs/ghidriff
uv pip install --python ~/.venvs/ghidriff/bin/python \
    /opt/ghidra/Ghidra/Features/PyGhidra/pypkg/dist/pyghidra-*-py3-none-any.whl \
    git+https://github.com/eduardoghi/ghidriff

The PyPI release (1.0.0) crashes at the end of a run on Python 3.14 when a function failed to decompile, misses changes in functions matched by name that kept their size, and can pair one function with two others through implied matches.

Look at the exports first

For a library with exported names, compare the names before running ghidriff. It takes seconds and answers what was added or removed.

rz-bin -E app_1.0.bpl | awk '{print $NF}' | sort > old.exports
rz-bin -E app_1.1.bpl | awk '{print $NF}' | sort > new.exports
comm -13 old.exports new.exports | grep 'TClassName@'   # only in 1.1
comm -23 old.exports new.exports | grep 'TClassName@'   # only in 1.0

New methods on a class are often most of the story of a regression, for example a setter that gained helper methods because its body grew. Disassemble the function that exists in both builds, as the delphi-bpl skill describes, and read what the new methods are called from.

Run

Give the two files different names, because ghidriff names the programs and the project after them.

GHIDRA_INSTALL_DIR=/opt/ghidra ~/.venvs/ghidriff/bin/ghidriff --no-symbols \
    -p diff/proj -o diff/out --log-path diff/ghidriff.log app_1.0.bin app_1.1.bin
  • --no-symbols skips the symbol server lookup. Leave it out only for Windows binaries that have public PDBs.
  • --force-diff is needed when the two files differ too much in symbols or architecture. Without it the run stops with a message such as Symbol counts differ by N. The option tells ghidriff to match anyway. Use it when the difference is expected, for example when a build dropped a whole module, and expect more functions in the added and deleted lists.
  • A 14 MB 32-bit library with 56,000 functions took 17 to 19 minutes on 20 cores the first time (import and analysis of both files) and 3 to 7 minutes on a rerun with the same -p, which reuses the analyzed programs. The project used 420 MB. Keep it while you iterate and delete it afterwards.
  • Ghidra refuses a project path with any element that starts with a dot, such as ~/.cache/..., so keep -p out of hidden directories.
  • ghidriff turns on Ghidra's Decompiler Parameter ID analyzer, and turns off Shared Return Calls.Assume Contiguous Functions Only when a binary already has more than 1000 functions before analysis, which in practice means a PDB was loaded. Override either with --program-options opts.json, for example {"program_options": {"Analyzers": {"Decompiler Parameter ID": false}}}. Both builds need the same options, so don't mix a .gzf analyzed elsewhere with a fresh import.
  • Run it in the background and watch the log for | ghidriff | lines and Traceback. Ghidra prints a lot of harmless warnings.
  • Both files are analyzed in parallel. An OverlappingFileLockException from WindowsResourceReferenceAnalyzer only means that analyzer was skipped on one side and doesn't affect the function matching.
  • Failed to decompile ... Low-level Error warnings usually come from data that the loader turned into functions, such as exported type info or vtables. They don't stop the run.

Read the results

The Markdown report lists at most 200 functions per section (--max-section-funcs), so a large diff gets cut. The JSON in out/json/*.ghidriff.json has everything. Start from the counts:

jq '.stats | {added_funcs_len, deleted_funcs_len, matched_funcs_with_code_changes_len, func_match_overall_percent}' \
    diff/out/json/*.ghidriff.json

List functions whose code changed, most changed first, with the address in the old build:

jq -r '.functions.modified[] | select(.diff_type | index("code"))
       | "\(.ratio)\t\(.old.address)\t\(.old.name)"' diff/out/json/*.ghidriff.json | sort -n

Then narrow down by name (a class, module or namespace) and read one function's decompiled diff:

jq -r '.functions.modified[] | select(.old.name | test("Order")) | .diff' diff/out/json/*.ghidriff.json
jq -r '.functions.added[].name, .functions.deleted[].name' diff/out/json/*.ghidriff.json
  • ratio is the similarity of the decompiled code without the signature. Near 1.0 is a small change, near 0 a rewrite.
  • diff_type lists what changed. address alone means the function only moved. called means its callees changed, which can be the whole difference, so check the diff before assuming the body changed.
  • Functions with the same size and reference count are compared instruction by instruction, with addresses masked, so a changed constant or field offset shows up even when nothing else moved. A pair sent to the diff that way is dropped when only its address changed.
  • A function can appear more than once in modified when two correlators matched it.
  • Functions in added and deleted had no match. A renamed or split function shows up as one deleted and one or more added, so search the new build for its strings before concluding it was removed.
  • strings in the JSON lists added and removed string labels. It catches a changed text only in some cases, see below.

What the report leaves out

The strings section doesn't compare the contents of the files. It lists the string labels Ghidra created (s_...) that at least one reference points at, so a changed text shows up only when Ghidra defined it as a string and disassembled code uses it. In a Delphi package with five changes of one character each, all of the same length, the report caught one:

ChangeIn the report
ASCII literal used by ordinary codeyes, as a deleted and an added string
Literal with accented characters used by ordinary codeno, Ghidra left it as DAT_
Literal used only in an except blockno, the handler isn't disassembled
resourcestring (string table entry)no, it is defined in .rsrc with no label or reference
Form property (DFM)no, forms are binary resources

No function was marked as changed either, because the code still pointed at the same addresses. This was checked with the fork above and Ghidra 12.1.4. For Delphi binaries, compare the texts and the forms on their own:

bpl-xref strings app_1.0.bpl > old.txt
bpl-xref strings app_1.1.bpl > new.txt
diff old.txt new.txt
bpl-xref dfm --all --no-geometry app_1.0.bpl > old.dfm
bpl-xref dfm --all --no-geometry app_1.1.bpl > new.dfm
diff old.dfm new.dfm

strings lists every literal the code points at and every string table entry, sorted by text and without addresses or string IDs, which move between builds, so the diff shows only texts that were added or removed. --no-geometry drops Left, Top, Width, Height and similar properties, which change whenever a form is opened in the designer.

Delphi executables

An executable without exports or symbols gives ghidriff no names to match on, and Ghidra's analysis misses the event handlers that are only reached through a class's published method table, along with the code they call. Name those handlers in the project between two ghidriff runs:

ghidriff ... -p diff/proj app_1.0.exe app_1.1.exe       # creates and analyzes the project
bpl-xref vmt --names app_1.0.exe > old.names
bpl-xref vmt --names app_1.1.exe > new.names
/opt/ghidra/support/analyzeHeadless diff/proj/ghidriff-app_1.0.exe-app_1.1.exe \
    ghidriff-app_1.0.exe-app_1.1.exe -process 'app_1.0.exe*' \
    -scriptPath <this repo>/ghidra_scripts -preScript ApplyNames.java "$PWD/old.names"
# the same for app_1.1.exe with new.names, then ghidriff again with the same -p
  • ApplyNames.java names the functions it finds and creates the ones Ghidra doesn't have. As a pre-script, without -noanalysis, the analysis that follows also picks up the calls inside the new functions. With -noanalysis the names fix the pairing but that code stays out of the diff.
  • ghidriff stores each program with a hash after its name, hence the wildcard in -process. The second ghidriff run reuses the analyzed programs and takes seconds.
  • Run analyzeHeadless from a directory without a copy of ApplyNames.java. A file with the script's name in the current directory is taken first and then refused, because it isn't in a script directory.

On two builds of a Delphi 7 executable, the first run matched 1,396 functions and reported 4 changed ones, all of them similar event handlers paired with the wrong counterpart, while the real changes were in handlers Ghidra hadn't made functions of. After naming 215 published methods, 2,538 functions matched and the report showed the 2 handlers that really changed and the imports that moved to another package.

Delphi packages have their own notes in the delphi-bpl skill.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.