agentleFS
eduardoghieduardoghi/reverse-engineering-skills/skills/delphi-bpl/SKILL.md

delphi-bpl

Skill2 starsChanged 12 days agoMITView on GitHub

Reverse engineer 32-bit Delphi binaries, especially BPL runtime packages, by going from exported names and string literals to the code that uses them and decompiling it with rz-ghidra or Ghidra (ReVa). Use when you need to know what a function in a .bpl, Delphi .dll or Delphi .exe does, which code reads a field or string, or how a value is calculated.

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. About 0 are common, 9 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Go from a string to the code: when you know a field name, message, SQL fragment or key but not the function:

    line 32
  2. Distinctive:

    Go from a screen to the code: when you know what the user clicks but not which method runs.

    line 62
  3. Very specific:

    Only components with a field declared in the class show up.

    line 92
  4. Very specific:

    Use the next export or the parent function's start as the end of the range, and give pD the size in bytes.

    line 129
  5. Very specific:

    Always pass asm.comments=false to pd/pD on large files.

    line 133
  6. Distinctive:

    Decompile one function with rz-ghidra: when the control flow is hard to follow in the disassembly.

    line 155
  7. Very specific:

    Confirm in the disassembly: when a conclusion depends on a branch, an offset, a constant or the argument order, and always when the …

    line 186
  8. Distinctive:

    Check the conclusion against what the program does: when it depends on a runtime value (a setting, a record, a mode flag) or when someone …

    line 190
  9. Distinctive:

    Check this before reading any code.

    line 205
  10. Distinctive:

    When both files hold the class, they share the logic, so a reading of one carries over to the other.

    line 216
  11. Very specific:

    When the faulting function belongs to a library routine such as TStrings.IndexOfName, the bug is in the caller that passed nil.

    line 244
  12. Very specific:

    try blocks: start with xor eax, eax; push ebp.

    line 278
  13. Distinctive:

    A stored change that has no effect: When the program keeps ignoring a value that was changed where it is stored, look for a cache of the …

    line 370
  14. Very specific:

    Search for format strings that build file names (bpl-xref str app.bpl '%s.') and for calls to the temporary directory helper, then read the …

    line 372
  15. Very specific:

    Check that the lists are not empty before trusting an "equal".

    line 416
  16. Distinctive:

    When a class gains fields, every method that touches the fields after the new ones changes its offsets, so almost the whole unit shows up …

    line 419
  17. Very specific:

    When the code reads the same in every build and the behaviour still differs, look at the objects in memory.

    line 427
  18. Very specific:

    Import headless and let Ghidra pick the borlanddelphi compiler spec on its own.

    line 550
  19. Distinctive:

    Keep binaries, Ghidra projects and decompiled output out of git repositories.

    line 590

≈ “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

Delphi BPL reverse engineering

A BPL (Borland Package Library) is a regular 32-bit PE DLL built by Delphi or C++Builder. It exports every symbol of every unit in the package with Borland name mangling, so most functions already have their real names. Start from those names and from string literals, not from a blank disassembly.

Decompiled Delphi code is rougher than decompiled Java. Delphi's register calling convention, Extended floats and string helpers confuse every decompiler, so read the output as a lead and check anything important in the disassembly.

Tools: bpl-xref (from this repo's bin/, needs python-pefile), rizin with the rz-ghidra plugin, and Ghidra 12.1.3 or newer with the ReVa extension for long sessions.

Method

  1. Read the exports and imports. They cost about a second even on a 30 MB package.

    rz-bin -E app.bpl > exports.txt                       # vaddr in column 3, name last
    grep -i 'TOrder@' exports.txt | awk '{print $3, $NF}'
    rz-bin -l app.bpl                                     # other packages and DLLs it imports

    The imported packages tell you which BPLs hold the code it calls. Repeat step 1 on them when a call leaves the file.

  2. Go from a string to the code when you know a field name, message, SQL fragment or key but not the function:

    bpl-xref str app.bpl 'CustomerName' 'Invalid order'

    A fragment works too. It is reported as 'Customer' in 'CustomerName' at 0x..., with the references of the literal that holds it. For each match it prints the literal kind guessed from the bytes before it (AnsiString, UnicodeString, ShortString), every relocated pointer to it in code, the nearest push ebp; mov ebp, esp before each reference and the exports around it. Nested procedures are not exported and sit right before their parent, so when the reference is between two exports the "next" one is often the owner.

    A ptr line instead of ref means the pointer sits in a data section, usually a table (package names, resource strings, initialized records). The code reads the table slot, not the string, so run bpl-xref calls on the ptr address to reach it.

    Messages declared as resourcestring live in the string table resource as UTF-16 without a terminator, and code never points at the text. It loads a record of a module handle pointer and the string ID (mov eax, offset rec; call LoadResString). str also searches the string table, matching any string that contains the text, and prints (resourcestring ID), the record with its exported name when there is one (@Uorders@SInvalidOrder) and the code that references the record. A record without references in a package is usually loaded by other packages through that export.

    An EXE usually has no exports, so there are no "prev"/"next" lines. Start from the entry point (rz-bin -e app.exe), from the import thunks, which flags names, and from the event handlers that dfm --events finds through the VMTs (step 3).

  3. Go from a screen to the code when you know what the user clicks but not which method runs. Delphi stores each form as a binary DFM in an RCDATA resource named after the form class, and the form maps every event to a method name.

    bpl-xref dfm app.bpl                          # every form, its class and number of events
    bpl-xref dfm app.bpl TFORDEREDIT              # one form as text .dfm
    bpl-xref dfm --events app.bpl | grep -i -A1 'btnSave'

    Find the form by a caption or label in the text output, then take the component's OnClick, OnChange or other event. --events prints each handler with the exported method it names (@Unit@TForm@BtnSaveClick$qqrp14System@TObject), so the address is ready for steps 4 to 6. Events inside collection items show up as Edit1.Buttons[0].OnClick. Without an export, as in an EXE or for a handler an ancestor form declares, it looks the name up in the published method tables of the form's class and its ancestors and prints 0x... TFOrderEdit.BtnSaveClick (published). When the ancestry continues in another package it names the imported ancestor instead, and the method is in that package's exports. A handler marked ? was found neither way, and every exported method with that name is listed as a candidate. A form whose class has no VMT in the file is usually one the linker kept after dropping its class, so no code runs it.

    bpl-xref vmt reads the same VMTs without exports, in the layout of Delphi 2 to 2007 or of Delphi 2009 and later, which it picks from the file. Without a class it lists every class with its parent. With one it prints the published methods and the published fields with their offsets, so mov eax, [ebx+0x3a0] in a form method is edtCustomer: TEdit:

    bpl-xref vmt app.exe | grep -i order          # classes, parents, size of the published tables
    bpl-xref vmt app.exe TFOrderEdit              # methods, then +offset name: type for each field

    Only components with a field declared in the class show up. Pages of a TNotebook and components of an ancestor form from another package don't.

  4. Find who calls a function, especially a nested procedure, which has no export and no name:

    bpl-xref calls app.bpl 0x0045a1c0 '@Uorders@TOrder@Post$qqrv'

    It takes hex addresses or exact export names and lists call/jmp rel32 instructions plus relocated pointers (VMT slots, event handler tables). The rel32 hits come from a byte scan, not from disassembly, so treat them as candidates and check each one with pd 1 @ addr. Virtual and interface calls go through call dword [reg + offset] and don't show up. For those, find the VMT slot that points at the method (a ptr hit) and search for its offset.

    A call on an interface pointer (mov ebx, [eax]; call dword [ebx + 0x74]) doesn't use the class VMT. Its slot holds a stub that adjusts Self and jumps to the method (add eax, -0x1c; jmp Method, or add dword [esp+4], -0x18; jmp Method for a stdcall method), and the tables of all the interfaces of a class sit one after another. To name the method behind an offset, take a method you know the interface has, find its stub (the jmp that bpl-xref calls lists for the method), then the pointer to the stub (a ptr hit), and walk back to the start of that table. The table starts with the stubs of QueryInterface, AddRef and Release, three in a row with one adjustment, and the offset in the call counts from the first of them. Walking back over everything that looks like a code pointer goes past it into the table of the previous interface and shifts every slot. One table read that way came out four entries off.

  5. Read the disassembly with names. Plain pd shows call 0x00401f30 and mov edx, 0x0045c6fc. Generate rizin flags for the import thunks and for the string literals the range uses, then save the disassembly to a file:

    bpl-xref flags app.bpl 0x0045a1c0 0x0045b000 > flags.rz
    rizin -e scr.color=0 -e asm.comments=false -e asm.lines=false -e asm.bytes=false -q \
        -i flags.rz -c 'pD 0xe40 @ 0x0045a1c0' app.bpl 2>rizin.err > func.asm

    The same lines then read call thunk.Uorders_TOrder_Post_qqrv and mov edx, str.CustomerName. Use the next export or the parent function's start as the end of the range, and give pD the size in bytes. A 3.5 KB function is about a thousand lines, so grep the file (grep -n 'call\|0x4b8\]' func.asm) or read it in pieces instead of printing it whole.

    Always pass asm.comments=false to pd/pD on large files. The comments rizin computes for each instruction get slower the longer the listing: on a 60 MB package, 4 KB took 10 s, 16 KB didn't finish in 5 minutes, and with comments off 93 KB took 7 s, most of it startup. asm.lines=false drops the jump arrows, which only get in the way of grep. Flag names are cut at 48 characters, and a literal of one or two characters gets a name that doesn't show the character (str. for a space, str.. for a dot, str.__1 for an asterisk). When the reading depends on which separator a Pos or a concatenation uses, print the bytes at the address instead of trusting the name. Print the full text of a literal with ps ascii @ addr (AnsiString), psw @ addr (UnicodeString) or psp @ addr (ShortString, from its length byte). Read fcomp dword [addr] style constants with pf f @ addr (Single) or pf F @ addr (Double).

    Without a range, flags names every literal in the file. A large package has hundreds of thousands, which adds about 7 s to each rizin start. Every start also parses all the exports (around 5 s for 60k), so batch addresses with several -c options or -i cmds.rz in one run. rizin warns bin_file_strings: search interval size ... exceeds max region size on large files. That warning is harmless, but stderr also carries real errors (a flags file that fails to parse, a bad command), so send it to a file instead of /dev/null and check it when the output is empty or the names are missing.

    For a quick look at a wide range without names, objdump -d -M intel --no-show-raw-insn --start-address=0x0045a1c0 --stop-address=0x0045b000 app.bpl takes a fraction of a second.

  6. Decompile one function with rz-ghidra when the control flow is hard to follow in the disassembly. A small function takes a few seconds, a 2,000-instruction one around 20.

    rizin -e scr.color=0 -e analysis.cc=borland -q \
        -c 'af @ 0x0045a1c0' -c 'pdg @ 0x0045a1c0' app.bpl 2>rizin.err

    analysis.cc=borland only changes pdg. pd and pD ignore it.

  7. Make register arguments visible. Calls to other Delphi functions come out as Foo() with no arguments, because the arguments travel in eax, edx and ecx. Give the callee a signature with afs, keeping -e analysis.cc=borland on the command line:

    rizin -e scr.color=0 -e analysis.cc=borland -q \
        -c 'af @ 0x00401f30' \
        -c 'afs void set_value(int self, char *name, double v) @ 0x00401f30' \
        -c 'af @ 0x0045a1c0' -c 'pdg @ 0x0045a1c0' app.bpl 2>rizin.err

    The call then reads set_value(self, "CustomerName"). Both settings are needed. Without afs the arguments stay hidden, and afs without analysis.cc=borland reads them from the stack, which gives wrong values (set_value(iVar3, (char *)iVar2, ...)). afc borland adds nothing. rz-ghidra warns Matching calling convention borland ... failed, args may be inaccurate, which is expected. double arguments are still shown as two uStack_* stores before the call.

  8. Use Ghidra with ReVa for anything longer than a few functions: cross-references across the whole file, call graphs, renaming as you go. See the Ghidra section for import and the time it takes.
  9. Confirm in the disassembly when a conclusion depends on a branch, an offset, a constant or the argument order, and always when the decompiled output has unkfloat10, in_EAX or stack variables with no clear source. Quote the address and instruction for each conclusion.
  10. Check the conclusion against what the program does when it depends on a runtime value (a setting, a record, a mode flag) or when someone will act on it. Look for the effect in the data the program writes, or run the smallest input that takes the branch in question. When the reading and the observed behaviour disagree, one of the assumptions is wrong. Say so and find which one instead of reporting either result.

    A branch that depends on a setting read by name needs two answers: where stored values come from and what the default is. The loader's query or file read gives the first. The default is usually an argument of the call that registers the setting, so search for the setting's name and read the arguments around that call. When no stored value exists, the default applies.

Which file actually runs

An EXE can contain the units of a package that it never imports. The package is then a copy built from the same source and loaded by something else, so analyzing or patching it changes nothing for the EXE. Check this before reading any code.

  • rz-bin -l app.exe lists the packages the EXE imports. A package missing from that list is not loaded by it.
  • bpl-xref vmt app.exe | grep -i ClassName shows whether the classes you care about are inside the EXE. They then have their own VMT address in the EXE's range.
  • The module named in a crash log or a profiler is the file that ran. An exception address inside app.exe for a class that you found in lib.bpl means the EXE has its own copy.
  • On Linux or Wine, /proc/PID/maps lists the images that the process loaded. On Windows, EnumProcessModulesEx does (see "Inspecting a running process").

When both files hold the class, they share the logic, so a reading of one carries over to the other. The copies are separate builds, so addresses and thunk targets differ and small details can too. Find the same function in the file that runs and confirm the instructions there before patching.

From a crash log line to a function

A log often prints a module and an address, such as Access violation at address 4A2F10C8 in module 'lib.bpl'. Read of address 00000000. To land on the code:

  1. Get the module's preferred base with rz-bin -I lib.bpl | grep baddr. When the process loaded it at that base, the logged address is the file's virtual address. A module that loaded elsewhere needs the rebase delta, which /proc/PID/maps or a debugger gives.
  2. Sort the exports (rz-bin -E lib.bpl) and take the last one at or before the logged address. The offset into the function is the difference. Nested procedures have no export and sit before their parent, so the owner can be the next export.
  3. Disassemble a window around the address with objdump -d -M intel --start-address=... --stop-address=... lib.bpl. In an EXE without exports, walk back from the address to the nearest push ebp; mov ebp, esp for the start of the function and run bpl-xref calls on it to find the callers.

What the instruction tells you:

  • mov reg, [ebp-4] followed by mov edx, [reg], with a read of address 0, is a method called on a nil Self. The object was never created, or it was freed and its pointer cleared.
  • The same address repeated hundreds of times points to a deterministic nil, not to memory corruption. A field freed with FreeAndNil and used again behaves like this, because the pointer is zero and the read always faults at the same instruction. A real use after free usually shows varying addresses, garbage values or crashes that come and go.
  • When the faulting function belongs to a library routine such as TStrings.IndexOfName, the bug is in the caller that passed nil. Read the caller, not the library.

Counting outcomes by message type in the same log shows how wide the failure is. Group the lines that report a result by type and by outcome. A type with no successes fails every time, and a type that mixes both depends on the data.

Reading Delphi code

  • Mangled names. @Unit@TClass@Method$qqr<params>. $qqr is the register convention, $qqs stdcall (COM methods). $bctr is a constructor, $bdtr a destructor. @$xp$... is RTTI and @Unit@TClass@ (ending in @) is the class VMT, both data even when they sit in the code section. The return type is not encoded.
  • Parameter codes. x const, r var (by reference), p pointer, v no parameters, i Integer, o Boolean, us Word, uc Byte, d Double, g Extended, and a length-prefixed type name such as 17System@AnsiString. $qqrx17System@AnsiStringd is (const s: AnsiString; d: Double).
  • Register convention. Self goes in eax for methods. The first three integer, pointer or string parameters go in eax, edx, ecx, and the rest are pushed left to right. Double and Extended always go on the stack, so the decompiler numbers them in reverse (param_7 is the first one). Ordinal results come back in eax, floats in ST(0), and strings and records through a hidden last var parameter.
  • Strings. An AnsiString literal has a -1 reference count and a 32-bit length right before the first character, and code points at that character. A UnicodeString literal (Delphi 2009 and later) is UTF-16 with the same layout plus a code page and element size. ShortString constants and RTTI names are referenced through their length byte. Exports such as @System@@UStrCat mean Delphi 2009 or later, @System@@LStrCat alone means an older compiler.
  • Calls to other packages go through a jmp dword [import] thunk. rizin names it sub.<package>.bpl__<Unit>_<Func>, so the thunk name is the callee.
  • Object fields are offsets from Self ([eax + 0x480]). Ghidra may type Self as a pointer and scale the offset, so (ushort *)p + 0x240 is byte offset 0x480. Getter and setter exports (GetFoo/SetFoo) are a cheap way to map offsets to field names: decompile a few and read the offset each one touches.
  • Unit initialization is in @Unit@initialization$qqrv and @Unit@Finalization$qqrv. Global registrations (class factories, lookup tables) often happen there.
  • try blocks start with xor eax, eax; push ebp; push <handler>; push dword fs:[eax]; mov fs:[eax], esp and end by restoring fs:[0]. The handler jumps to @System@@HandleFinally for try/finally and to @System@@HandleAnyException or @System@@HandleOnException for try/except. When a literal shows up only in the except block, usually in an error message that names the operation, the code you want is the protected block right before it. Script interpreters embedded in Delphi programs often dispatch built-in functions this way, so the function's name leads to its error handler and the implementation sits just above.
  • Handlers outside the function in Ghidra. Ghidra doesn't follow the handler address that the try prologue pushes. The function body comes out as two ranges with the handler in the gap between them, the handler belongs to no function and its code isn't disassembled, so the decompiled code shows it only as &LAB_<handler> stored in a stack slot. An error message used only in the except block is missing from the decompiled code and Ghidra lists no references to it, while bpl-xref str still finds the reference. Disassemble from the LAB_ address to read the handler. For on E: EClass do the handler is jmp @System@@HandleOnException followed by a count and pairs of class cell and branch address, so each branch starts at the address in its pair, not after the jump. Checked with Ghidra 12.1.4 on packages.
  • Floating point width. fld/fstp with tbyte is Extended (10 bytes), qword is Double and dword is Single. A value that passes through a Double parameter or result is no longer equal to the same decimal literal held as Extended. Compare against a small range when a test checks a computed float.
  • Class references. A mov eax, [abs] before a constructor, an IsClass or a factory call loads a class pointer from a cell. For an imported class the cell is the import slot. For a class defined in the package the cell is the vmtSelfPtr at VMT minus 0x4C (0x58 from Delphi 2009 on), which holds the VMT's own address, and the class name is the ShortString just before the VMT. The class pointer is the VMT address. IsClass(obj, cls) takes the object in eax and the class in edx and answers in al.
  • Library objects that the package doesn't import methods for. The fields of VCL classes sit at fixed offsets for a given compiler, so code you inject can read them directly. In the Delphi 7 era layout a TTreeNode has the text at +8 and Data at +0xC, and a TStrings descendant answers IndexOf, Add and Delete through virtual slots. Confirm each offset in code that already touches it (a handler that reads [node+0xC] before using Data) rather than trusting a table.
  • Creating a VCL control from injected code. Load the class pointer from the import slot of its VMT, call the constructor (mov dl, 1, owner in ecx), then SetParent, SetBounds, SetAnchors and SetText, and keep the object in a state cell that the form's OnDestroy hook clears. Both SetParent and SetBounds are virtual, so call them through the object as described in the binary-patch skill. With a nil owner nothing frees the control when the form goes away, so pass the form as owner when the control should die with it.
  • Editing a string literal in place. A shorter text fits if you write the new length and leave the total size alone, padding with zeros after the new terminator. A longer one doesn't fit. To drop an argument from a format string without touching the code, use an index: '%1:s' prints the second argument of 'Item %d: %s' and ignores the first. Run bpl-xref str first, because every reference to the literal gets the new text, including screens you didn't mean to change. When a text doesn't change on screen, it may come from a translation table and not from the literal.
  • Exceptions with extra fields. In an on E: Exception do handler the exception object is kept in a frame slot, saved right after the handler starts (mov [ebp-0x30], eax). A factory such as CreateDet(cls, message, details) stores the extra strings in fields after the standard ones. Code that logs only E.Message discards the rest, and @System@@DoneExcept frees the object, so read the field before that call. Find its offset in the factory, where the extra argument is stored with LStrAsg.
  • Objects created in a loop and kept only under a condition. A loop that creates an object, hands it to a routine that fills it and adds it to a parent only when it ended up non-empty (Length > 0) leaks every empty one, because the path that skips the Add has no Free. In the disassembly look for a constructor call, then a size test, then a conditional jump over the call that stores the object with nothing that releases it on the other side. Confirm with memory growth per iteration (see below), and after the fix compare the program's output before and after.
  • Reference counting bugs. Assigning a string goes through @System@@LStrAsg (or UStrAsg), which adds a reference. A plain mov [obj + x], reg of a string pointer does not. If the source is then released with LStrClr or LStrArrayClr before the field is used, the field points at freed memory and the result depends on whether that memory was reused. Interface variables are released with @System@@IntfClear. TObject.Free or FreeAndNil on one calls through the wrong table and usually crashes. An object created and then overwritten without a Free is a leak.
  • Which method a virtual call reaches. call dword [ecx + 0x34] after mov ecx, [eax] calls slot 0x34 of the object's VMT. To list what that slot runs in each class, search the file for the address of each candidate method as a dword. The match is the VMT slot, and its offset is the match address minus the class VMT export (@Unit@TClass@). Methods that are only reached through a slot show no call references, so this is also how to find who runs them.
  • TStringList.Objects. Up to Delphi 2007 a TStringList never owns the objects stored with AddObject, and freeing the list leaves them alive. Code that hangs a freshly loaded collection on a list owned by a short-lived object leaks one collection per object. The same fact makes it safe to keep a pointer to such an object after the list is gone. Check the Destroy of the owner, and of the classes in the collection, before relying on it.
  • TWriter and TReader streams. Component streams and many custom file formats are written value by value. ReadInteger, ReadBoolean, ReadString, ReadDate and ReadListBegin read a one-byte type code first, and ReadStr (a short string) does not. The codes up to Delphi 2007 are 0 vaNull (end of list), 1 vaList, 2 vaInt8, 3 vaInt16, 4 vaInt32, 5 vaExtended (10 bytes), 6 vaString (length byte), 7 vaIdent, 8 vaFalse, 9 vaTrue, 10 vaBinary, 11 vaSet, 12 vaLString (32-bit length), 13 vaNil, 14 vaCollection, 15 vaSingle, 16 vaCurrency, 17 vaDate (8-byte double), 18 vaWString (32-bit length of UTF-16 units), 19 vaInt64 and 20 vaUTF8String. With the reads of the loader in order, a field near the start of a file can be read without loading the rest. Find the loader by searching for the field's offset in the class (add eax, OFFSET before @LStrAsg, or mov [reg + OFFSET], eax) and follow the reads before it, including the version checks (cmp dword [eax + n], VERSION) that skip fields in old files.
  • When something is loaded again. Code that loads data once (a list read from a database, a cached object) usually guards it with a field of the object. It tests the field (cmp byte [eax+0x1c], 0), loads, and then sets it (mov byte [eax+0x1c], 1). To learn when the data is loaded again, find every write to that offset in the methods of the class. Take the address range of the class's exports and search the disassembly:

    objdump -d -M intel --no-show-raw-insn --start-address=0x... --stop-address=0x... app.bpl |
        grep -E 'mov +BYTE PTR \[e[a-z]+\+0x1c\]'

    Each write of zero is a place that invalidates the data. Run bpl-xref calls on the methods that hold them to see who triggers it. In one case only the destructor and an import routine of other subclasses cleared the flag, so the data stayed in memory until the program closed. The same offset is a different field in an unrelated class, so stay within the class and its descendants, which share the field layout.

  • A stored change that has no effect. When the program keeps ignoring a value that was changed where it is stored, look for a cache of the processed result, often a file in the temporary directory or next to the data. Search for format strings that build file names (bpl-xref str app.bpl '%s.') and for calls to the temporary directory helper, then read the check that decides whether the cache is still valid. It often compares a version, a size and a hash of only part of the input. In one case the processed form of some data was cached under a hash of its text alone, so changing an option stored elsewhere did nothing until the cache file was deleted.

Comparing two builds

Export names stay the same between builds of a package and addresses don't. Match exported functions by name, and nested procedures through the literals they reference (bpl-xref str on both files). Then compare only the instructions the question depends on. A function that was rewritten may also have been renamed or split, so when an export disappears, look for the same literals in the new file before concluding the code is gone.

To see everything that changed between two builds, run ghidriff as described in the binary-diff skill. On a BPL it matches most functions by their export names. Filter the JSON by unit (test("@Unitname@")) to find what changed in the area you care about. The exported RTTI (@$xp$...) and VMTs (@Unit@TClass@) come out as functions that fail to decompile or decompile to nonsense, and many of them land in modified. Skip names that start with @$xp$.

ghidriff misses most changes in texts and forms of a Delphi binary, such as literals with accented characters, messages used only in except blocks, resourcestrings and every form property. Compare those with bpl-xref strings and bpl-xref dfm --all --no-geometry, as the binary-diff skill shows. On an EXE, which has no exports, also name the published methods in the project with bpl-xref vmt --names and ghidra_scripts/ApplyNames.java before trusting the report, or changed event handlers can be missing from it.

For a first pass over one unit, before running ghidriff, compare its exported functions instruction by instruction. Take each export of the unit and the next export as the range, so the nested procedures that sit before the next export are included. Disassemble both builds with objdump, mask what moves between builds, and compare the lists. It takes seconds for a few hundred functions.

import re, subprocess
def body(path, start, end):
    out = subprocess.run(['objdump', '-d', '-M', 'intel', '--no-show-raw-insn',
                          f'--start-address={start}', f'--stop-address={end}', path],
                         capture_output=True, text=True).stdout
    ins = [l.split('\t', 1)[1] for l in out.splitlines() if re.match(r'\s*[0-9a-f]+:\t', l)]
    ins = [re.sub(r'0x[0-9a-f]{5,}', 'ADDR', i) for i in ins]          # absolute addresses
    ins = [re.sub(r'([+-])0x[0-9a-f]+\]', r'\1OFF]', i) for i in ins]  # field offsets
    return [re.sub(r'^(call|j\w+)\s+[0-9a-f]+\b.*', r'\1 X', i) for i in ins]
  • Check that the lists are not empty before trusting an "equal". objdump prints 8 digit addresses without leading spaces, and a pattern that required them matched nothing, so every function came out "equal" between two builds that had in fact changed.
  • When a class gains fields, every method that touches the fields after the new ones changes its offsets, so almost the whole unit shows up as different with the same function sizes. Masking the displacements removes most of that. What is left at the same size is usually small constants that also moved with the layout. Read the diff of the functions the question depends on before calling the change a logic change, and use ghidriff when you need the full picture.

Inspecting a running process

When the code reads the same in every build and the behaviour still differs, look at the objects in memory. On Linux, including programs running under Wine, /proc/PID/mem can be read from Python without attaching a debugger, and the process keeps running.

mem = open(f'/proc/{pid}/mem', 'rb', 0)
for line in open(f'/proc/{pid}/maps'):
    lo, hi = (int(x, 16) for x in line.split()[0].split('-'))
    if 'r' not in line.split()[1] or lo >= 0x80000000:
        continue
    try:
        mem.seek(lo); data = mem.read(hi - lo)
    except OSError:
        continue      # guard pages and unreadable mappings
    ...

On Windows the same reads go through the Win32 API from 64-bit Python with ctypes, and the process keeps running too. LIST_MODULES_ALL is what makes the 32-bit modules of a Delphi program visible from 64-bit Python, and each module handle is the image's load address:

import ctypes
from ctypes import wintypes as w
k32 = ctypes.WinDLL('kernel32', use_last_error=True)
k32.OpenProcess.restype = w.HANDLE
k32.VirtualQueryEx.argtypes = [w.HANDLE, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_size_t]
k32.ReadProcessMemory.argtypes = [w.HANDLE, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_size_t,
                                  ctypes.POINTER(ctypes.c_size_t)]
k32.K32EnumProcessModulesEx.argtypes = [w.HANDLE, ctypes.c_void_p, w.DWORD, ctypes.POINTER(w.DWORD), w.DWORD]
k32.K32GetModuleFileNameExW.argtypes = [w.HANDLE, ctypes.c_void_p, w.LPWSTR, w.DWORD]

class MBI(ctypes.Structure):  # MEMORY_BASIC_INFORMATION
    _fields_ = [('BaseAddress', ctypes.c_void_p), ('AllocationBase', ctypes.c_void_p),
                ('AllocationProtect', w.DWORD), ('PartitionId', w.WORD), ('RegionSize', ctypes.c_size_t),
                ('State', w.DWORD), ('Protect', w.DWORD), ('Type', w.DWORD)]

h = k32.OpenProcess(0x0400 | 0x0010, False, pid)  # PROCESS_QUERY_INFORMATION | PROCESS_VM_READ
mods, needed = (ctypes.c_void_p * 1024)(), w.DWORD()
k32.K32EnumProcessModulesEx(h, mods, ctypes.sizeof(mods), ctypes.byref(needed), 3)  # LIST_MODULES_ALL
name = ctypes.create_unicode_buffer(260)
for base in mods[:needed.value // ctypes.sizeof(ctypes.c_void_p)]:
    k32.K32GetModuleFileNameExW(h, base, name, 260)
    print(hex(base), name.value)

READABLE = 0x02 | 0x04 | 0x08 | 0x20 | 0x40 | 0x80  # PAGE_READONLY to PAGE_EXECUTE_WRITECOPY
mbi, addr = MBI(), 0
while addr < 1 << 32 and k32.VirtualQueryEx(h, ctypes.c_void_p(addr), ctypes.byref(mbi), ctypes.sizeof(mbi)):
    lo, size = mbi.BaseAddress or 0, mbi.RegionSize
    addr = lo + size
    if mbi.State != 0x1000 or mbi.Protect & 0x100 or not mbi.Protect & READABLE:
        continue      # not committed, guard page or no access
    buf, got = ctypes.create_string_buffer(size), ctypes.c_size_t()
    if not k32.ReadProcessMemory(h, ctypes.c_void_p(lo), buf, size, ctypes.byref(got)):
        continue
    data = buf.raw[:got.value]
    ...

The module list also shows the WOW64 modules above 4 GB, which the scan skips. Reading a program that runs as administrator needs Python started as administrator too.

  • Reading another process needs ptrace permission. With kernel.yama.ptrace_scope = 1 (the usual default) only a parent can read its child, and the read fails with Permission denied. Set it to 0 with sudo sysctl kernel.yama.ptrace_scope=0 for the session and back to 1 when done. Without sudo, a program you start yourself can allow it for its own process, which is useful with strace -p once it has settled, since starting it under strace slows down its startup. The exception ends with the process, but while it runs any program of the same user can trace it.

    python3 -I -c 'import ctypes, os, sys
    ctypes.CDLL(None).prctl(0x59616d61, ctypes.c_ulong(-1).value, 0, 0, 0)  # PR_SET_PTRACER, any
    os.execv(sys.argv[1], sys.argv[1:])' ./program &
    sleep 15
    strace -f -e trace=ioctl -p $!

    strace -k adds a stack to each call and can slow a busy program so much that the trace no longer shows its normal behavior. In one test, 15 seconds of tracing ioctl went from over 30,000 calls to about 300.

  • The first dword of every Delphi object is its class pointer, which is the address of the exported VMT symbol @Unit@TClass@ (adjusted by the rebase delta if the package didn't load at its preferred base, which /proc/PID/maps or the module list on Windows shows). Scanning readable memory for aligned dwords equal to that address lists the instances. Expect false hits inside the VMT itself, in RTTI and in freed objects, so check a few fields before trusting one.
  • To find which field holds a sub-object when you don't know the offset, scan the object for pointers whose target starts with the VMT of the class you expect. Then read the container. Get the layout from the getters (TList.GetCount, TCollection.GetCount) in the build you are looking at, since field offsets change between compiler versions.
  • An AnsiString field points at the first character, with the length in the dword before it and the reference count before that.
  • Comparing instances answers questions that the code alone doesn't. For example, when the same data exists in a runtime object and in an edit copy, counting the items each one holds shows which copy lost them.
  • Growth per unit of work. To compare variants of a patched binary, sample the resident size and a counter that a hook increments once per unit, then divide the growth by the units over the same range for every variant. The cost of a unit depends on its content, so the cumulative average of runs of different lengths misleads. One variant looked like 0.77 MB per item that way and was 1.14 over the range the other runs shared. Disabling one callee at a time narrows a leak down quickly, but a variant that skips only the allocation's consumer may not change anything, because the leaked object is created before it.
  • Where the time goes. Sampling /proc/PID/task/TID/stat (the state letter) and /proc/PID/task/TID/syscall shows whether the main thread is running or blocked, and in which system call. perf record -e cpu-clock:u -g -p PID counts CPU only, so a program that spends most of its time waiting looks almost idle, and the wall clock is the number that matters to the user. Under Wine the packages have no names in /proc/PID/maps. Build the module table by reading the first bytes of each candidate image at its preferred base from /proc/PID/mem and comparing the TimeDateStamp with the file's header, then name each sampled address with the nearest export from rz-bin -E. The wine-debugging skill has the rest.

Debuggers under Wine are fragile. winedbg --gdb on a 32-bit program in Wine's new WoW64 mode reports the target as i386, but its break-in thread runs at a 64-bit address. gdb truncates that address, reports a SIGSEGV, and detaching then can leave the program dead or frozen. The gdb proxy also accepts a single connection, so a failed session can't be resumed. Prefer reading memory as above, or a GUI debugger such as x32dbg running inside the same Wine prefix, and warn whoever is using the program that it may close.

Ghidra and ReVa

  • Use Ghidra 12.1.3 or newer. Up to 12.1.2 the PE loader read the export ordinal table as signed 16-bit values, so every name whose index is 32768 or above came out unnamed. A package with 63k exports lost almost half its names. Re-import files loaded by an older version, since upgrading the project keeps the wrong symbols.
  • Import headless and let Ghidra pick the borlanddelphi compiler spec on its own. The script is ghidra-analyzeHeadless in the Arch package and support/analyzeHeadless in the release zip.

    ghidra-analyzeHeadless ~/ghidra-projects/app app -import app.bpl -loader PeLoader \
        -analysisTimeoutPerFile 7200

    A 30 MB BPL with 63k exports took about 5 minutes to import and 15 to analyze on 20 cores, and the project used 700 MB. Name matching in the PE loader grows with the square of the export count, so import time climbs fast with very large packages. Reopening an analyzed project with -process app.bpl -noanalysis -readOnly takes seconds.

  • ReVa in assistant mode (Ghidra GUI open, ReVa Application Plugin enabled, MCP server on http://localhost:8080/mcp/message) works on the persistent, already analyzed project. That's the mode to use for large packages.

    claude mcp add --scope user --transport http ReVa -- http://localhost:8080/mcp/message
  • ReVa in headless/stdio mode (mcp-reva) creates a temporary project for every session and has to import and analyze from scratch. With a large BPL the import passes its 120 s default timeout and ReVa falls back to another loader, which yields a 16-bit MZ program at 0x1000:0000. If you see that address, the import is wrong. Fine for small DLLs, not for big packages.
  • ReVa's run-script only works when Ghidra was started through PyGhidra (pyghidra in the Arch package, support/pyghidraRun in the release zip), not through the plain ghidra launcher.

Other tools

  • pefile stops at 8192 exports and calls the rest corrupt. Pass the limit to the constructor, pefile.PE(path, max_symbol_exports=1 << 20). Changing pefile.MAX_SYMBOL_EXPORT_COUNT has no effect, because the constructor reads it only as a default. Its import list is also incomplete for large BPLs. It stops after 8192 symbols and silently drops names with characters such as %, which Delphi uses in System@%SmallString$iuc$255%. bpl-xref reads the import table itself.
  • IDR (Interactive Delphi Reconstructor) recovers class and form data from EXEs, but it's GUI-only on Windows and supports up to Delphi XE4. For BPLs the exports already give the names it would recover. Dhrake needs IDR's output.
  • strings -a and strings -el (UTF-16) are quick to check that a literal exists before running bpl-xref str.

Keep binaries, Ghidra projects and decompiled output out of git repositories.

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.