scientific-method-engine 0.1.0__py3-none-any.whl

scientific_method_engine/ghidra/ReportCallArguments.java

@@ -0,0 +1,65 @@
+// Reports the three nearest pushed arguments at every direct call to a function.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.Instruction;
+import ghidra.program.model.symbol.Reference;
+import ghidra.program.model.symbol.ReferenceIterator;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class ReportCallArguments extends GhidraScript {
+    private static final int ARGUMENT_COUNT = 3;
+    private static final int MAX_PRECEDING_INSTRUCTIONS = 20;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length != 1) {
+            printerr("Supply one callee virtual address.");
+            return;
+        }
+
+        Address callee = toAddr(arguments[0]);
+        ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(callee);
+        while (references.hasNext() && !monitor.isCancelled()) {
+            Reference reference = references.next();
+            Instruction call = currentProgram.getListing().getInstructionAt(reference.getFromAddress());
+            if (call == null || !call.getFlowType().isCall()) continue;
+
+            Function function = currentProgram.getFunctionManager().getFunctionContaining(call.getAddress());
+            List<Instruction> pushes = nearestPushes(call, function);
+            println(call.getAddress()
+                + (function == null ? "" : " in " + function.getEntryPoint() + " " + function.getName())
+                + " args=" + format(pushes));
+        }
+    }
+
+    private List<Instruction> nearestPushes(Instruction call, Function function) {
+        List<Instruction> pushes = new ArrayList<>();
+        Instruction cursor = call;
+        for (int count = 0;
+             count < MAX_PRECEDING_INSTRUCTIONS && pushes.size() < ARGUMENT_COUNT;
+             count++) {
+            cursor = cursor.getPrevious();
+            if (cursor == null || (function != null
+                && !function.getBody().contains(cursor.getAddress()))) break;
+            if (cursor.getFlowType().isCall()) break;
+            if ("PUSH".equals(cursor.getMnemonicString())) pushes.add(cursor);
+        }
+        return pushes;
+    }
+
+    private String format(List<Instruction> pushes) {
+        StringBuilder result = new StringBuilder("[");
+        for (int index = 0; index < pushes.size(); index++) {
+            if (index > 0) result.append(", ");
+            Instruction push = pushes.get(index);
+            result.append(push.getAddress()).append(": ").append(push);
+        }
+        return result.append(']').toString();
+    }
+}

scientific_method_engine/ghidra/ReportCallPaths.java

@@ -0,0 +1,106 @@
+// Reports bounded direct-call paths between two explicitly selected functions.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.Instruction;
+import ghidra.program.model.listing.InstructionIterator;
+
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+
+public class ReportCallPaths extends GhidraScript {
+    private static final int MAX_DEPTH = 12;
+    private static final int MAX_VISITED_EDGES = 2000;
+    private static final int MAX_PATHS = 100;
+
+    private Address target;
+    private int depthLimit;
+    private int visitedEdges;
+    private int reportedPaths;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length != 3) {
+            printerr("Supply start address, target address, and maximum depth.");
+            return;
+        }
+
+        Function start = functionAt(arguments[0]);
+        Function targetFunction = functionAt(arguments[1]);
+        depthLimit = Integer.parseInt(arguments[2]);
+        if (start == null || targetFunction == null) return;
+        if (depthLimit < 1 || depthLimit > MAX_DEPTH) {
+            printerr("Maximum depth must be between 1 and " + MAX_DEPTH + ".");
+            return;
+        }
+
+        target = targetFunction.getEntryPoint();
+        List<Function> path = new ArrayList<>();
+        path.add(start);
+        Set<Address> active = new HashSet<>();
+        active.add(start.getEntryPoint());
+        search(start, path, active, 0);
+        if (reportedPaths == 0) println("No bounded direct-call path found.");
+        if (visitedEdges >= MAX_VISITED_EDGES)
+            println("Stopped after the " + MAX_VISITED_EDGES + "-edge safety limit.");
+        if (reportedPaths >= MAX_PATHS)
+            println("Stopped after the " + MAX_PATHS + "-path safety limit.");
+    }
+
+    private Function functionAt(String value) {
+        Address address = toAddr(value);
+        Function function = currentProgram.getFunctionManager().getFunctionContaining(address);
+        if (function == null) printerr(value + ": no containing function");
+        return function;
+    }
+
+    private void search(Function current, List<Function> path, Set<Address> active, int depth) {
+        if (monitor.isCancelled() || depth >= depthLimit
+            || visitedEdges >= MAX_VISITED_EDGES || reportedPaths >= MAX_PATHS) return;
+
+        // Every instruction of the body, including code before the entry and after a gap, which a
+        // walk forward from the entry would stop short of.
+        InstructionIterator instructions = currentProgram.getListing()
+            .getInstructions(current.getBody(), true);
+        while (instructions.hasNext()) {
+            Instruction instruction = instructions.next();
+            if (instruction.getFlowType().isCall()) {
+                for (Address destination : instruction.getFlows()) {
+                    visitedEdges++;
+                    Function callee = currentProgram.getFunctionManager()
+                        .getFunctionContaining(destination);
+                    if (callee == null) continue;
+                    Address entry = callee.getEntryPoint();
+                    if (entry.equals(target)) {
+                        printPath(path, instruction.getAddress(), callee);
+                    }
+                    else if (!active.contains(entry)) {
+                        path.add(callee);
+                        active.add(entry);
+                        search(callee, path, active, depth + 1);
+                        active.remove(entry);
+                        path.remove(path.size() - 1);
+                    }
+                    if (visitedEdges >= MAX_VISITED_EDGES || reportedPaths >= MAX_PATHS) return;
+                }
+            }
+        }
+    }
+
+    private void printPath(List<Function> path, Address callSite, Function callee) {
+        StringBuilder result = new StringBuilder();
+        for (Function function : path) {
+            if (result.length() > 0) result.append(" -> ");
+            result.append(function.getEntryPoint());
+        }
+        result.append(" -[").append(callSite).append("]-> ")
+            .append(callee.getEntryPoint());
+        println(result.toString());
+        reportedPaths++;
+    }
+}

scientific_method_engine/ghidra/ReportCallSitesWithScalars.java

@@ -0,0 +1,95 @@
+// Reports bounded call sites whose preceding argument setup contains requested scalars.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.Instruction;
+import ghidra.program.model.scalar.Scalar;
+import ghidra.program.model.symbol.Reference;
+import ghidra.program.model.symbol.ReferenceIterator;
+
+import java.util.HashSet;
+import java.util.Set;
+
+public class ReportCallSitesWithScalars extends GhidraScript {
+    private static final int PRECEDING_INSTRUCTIONS = 12;
+    private static final int MAX_MATCHES = 100;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length < 2) {
+            printerr("Supply a callee address followed by one or more scalar values.");
+            return;
+        }
+
+        Address callee = toAddr(arguments[0]);
+        Set<Long> requested = new HashSet<>();
+        for (int index = 1; index < arguments.length; index++) {
+            requested.add(Long.decode(arguments[index]));
+        }
+
+        int matches = 0;
+        ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(callee);
+        while (references.hasNext() && matches < MAX_MATCHES && !monitor.isCancelled()) {
+            Reference reference = references.next();
+            Instruction call = currentProgram.getListing()
+                .getInstructionAt(reference.getFromAddress());
+            if (call == null || !call.getFlowType().isCall()) continue;
+
+            Function function = currentProgram.getFunctionManager()
+                .getFunctionContaining(call.getAddress());
+            Instruction cursor = call;
+            boolean matched = false;
+            for (int count = 0; count < PRECEDING_INSTRUCTIONS; count++) {
+                cursor = cursor.getPrevious();
+                if (cursor == null || (function != null
+                    && !function.getBody().contains(cursor.getAddress()))) break;
+                if (cursor.getFlowType().isCall()) break;
+                if (containsRequestedScalar(cursor, requested)) matched = true;
+            }
+            if (!matched) continue;
+
+            matches++;
+            println("===== call " + call.getAddress()
+                + (function == null ? "" : " in " + function.getEntryPoint()
+                    + " " + function.getName()) + " =====");
+            cursor = call;
+            Instruction[] before = new Instruction[PRECEDING_INSTRUCTIONS];
+            int populated = 0;
+            for (; populated < PRECEDING_INSTRUCTIONS; populated++) {
+                cursor = cursor.getPrevious();
+                if (cursor == null || (function != null
+                    && !function.getBody().contains(cursor.getAddress()))) break;
+                if (cursor.getFlowType().isCall()) break;
+                before[populated] = cursor;
+            }
+            for (int index = populated - 1; index >= 0; index--) {
+                println("  " + before[index].getAddress() + "  " + before[index]);
+            }
+            println("> " + call.getAddress() + "  " + call);
+        }
+
+        if (matches == 0) println("No matching call sites found.");
+        else if (matches == MAX_MATCHES) println("Output capped at " + MAX_MATCHES + " calls.");
+    }
+
+    private static boolean containsRequestedScalar(Instruction instruction, Set<Long> requested) {
+        for (int operand = 0; operand < instruction.getNumOperands(); operand++) {
+            for (Object object : instruction.getOpObjects(operand)) {
+                if (object instanceof Scalar scalar && matchesRequested(scalar, requested)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
+    // Arguments are decoded as signed longs while operands are reported unsigned, so a request
+    // such as -1 must also be compared against the operand's signed value to match at all.
+    private static boolean matchesRequested(Scalar scalar, Set<Long> requested) {
+        return requested.contains(scalar.getUnsignedValue())
+            || requested.contains(scalar.getSignedValue());
+    }
+}

scientific_method_engine/ghidra/ReportCallsToRange.java

@@ -0,0 +1,67 @@
+// Reports call/jump sites whose resolved flow target lies in a segment range.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.Instruction;
+import ghidra.program.model.listing.InstructionIterator;
+import ghidra.program.model.listing.Listing;
+
+public class ReportCallsToRange extends GhidraScript {
+    private static final int MAX_MATCHES = 50;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length < 2) {
+            printerr("Supply start address and end address (inclusive), e.g. 1028:d820 1028:dab7");
+            return;
+        }
+
+        Address start = toAddr(arguments[0]);
+        Address end = toAddr(arguments[1]);
+        if (end.compareTo(start) < 0) {
+            printerr("End address must be >= start address.");
+            return;
+        }
+
+        println("===== flow targets in " + start + ".." + end + " =====");
+        Listing listing = currentProgram.getListing();
+        InstructionIterator instructions = listing.getInstructions(true);
+        int matches = 0;
+        while (instructions.hasNext() && matches < MAX_MATCHES && !monitor.isCancelled()) {
+            Instruction instruction = instructions.next();
+            if (!instruction.getFlowType().isCall() && !instruction.getFlowType().isJump()) {
+                continue;
+            }
+
+            Address[] flows = instruction.getFlows();
+            if (flows == null) {
+                continue;
+            }
+
+            for (Address target : flows) {
+                if (target.compareTo(start) < 0 || target.compareTo(end) > 0) {
+                    continue;
+                }
+
+                Function fromFunction = listing.getFunctionContaining(instruction.getAddress());
+                Function toFunction = listing.getFunctionContaining(target);
+                println(instruction.getAddress()
+                    + (fromFunction == null ? "" : " in " + fromFunction.getEntryPoint() + " " + fromFunction.getName())
+                    + " -> " + target
+                    + (toFunction == null ? "" : " (" + toFunction.getEntryPoint() + " " + toFunction.getName() + ")")
+                    + " :: " + instruction);
+                matches++;
+                break;
+            }
+        }
+
+        if (matches == 0) {
+            println("No resolved call/jump targets in range.");
+        } else if (matches == MAX_MATCHES && instructions.hasNext()) {
+            println("Output capped at " + MAX_MATCHES + " matches.");
+        }
+    }
+}

scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java

@@ -0,0 +1,55 @@
+// Reports direct x86 cdecl calls whose first argument is one requested constant.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.Instruction;
+import ghidra.program.model.scalar.Scalar;
+import ghidra.program.model.symbol.Reference;
+import ghidra.program.model.symbol.ReferenceIterator;
+
+public class ReportConstantFirstArgumentCalls extends GhidraScript {
+    private static final int MAX_CALLS = 300;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length != 2) {
+            printerr("Supply a callee virtual address and constant first argument.");
+            return;
+        }
+
+        Address callee = toAddr(arguments[0]);
+        long requested = Long.decode(arguments[1]);
+        ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(callee);
+        int matches = 0;
+        while (references.hasNext() && matches < MAX_CALLS && !monitor.isCancelled()) {
+            Reference reference = references.next();
+            Instruction call = currentProgram.getListing().getInstructionAt(reference.getFromAddress());
+            if (call == null || !call.getFlowType().isCall()) continue;
+            Instruction firstPush = call.getPrevious();
+            if (!isPushOf(firstPush, requested)) continue;
+
+            Function function = currentProgram.getFunctionManager().getFunctionContaining(call.getAddress());
+            Instruction secondPush = firstPush.getPrevious();
+            println(call.getAddress()
+                + (function == null ? "" : " in " + function.getEntryPoint() + " " + function.getName())
+                + " first=" + firstPush
+                + (secondPush == null ? "" : " preceding=" + secondPush));
+            matches++;
+        }
+
+        println("Matched calls: " + matches);
+        if (matches == MAX_CALLS) println("Output capped at " + MAX_CALLS + " calls.");
+    }
+
+    private static boolean isPushOf(Instruction instruction, long requested) {
+        if (instruction == null || !"PUSH".equals(instruction.getMnemonicString())) return false;
+        for (Object object : instruction.getOpObjects(0)) {
+            if (object instanceof Scalar scalar
+                && scalar.getUnsignedValue() == requested) return true;
+        }
+        return false;
+    }
+}

scientific_method_engine/ghidra/ReportDataBytes.java

@@ -0,0 +1,36 @@
+// Prints a bounded byte range at an explicitly supplied virtual address.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+
+public class ReportDataBytes extends GhidraScript {
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length != 2) {
+            printerr("Supply a virtual address and byte count, for example 0x00494818 24.");
+            return;
+        }
+
+        Address address = toAddr(arguments[0]);
+        int count = Integer.decode(arguments[1]);
+        if (count < 1 || count > 256) {
+            printerr("Byte count must be between 1 and 256.");
+            return;
+        }
+
+        byte[] bytes = new byte[count];
+        currentProgram.getMemory().getBytes(address, bytes);
+        println("===== " + address + " (" + count + " bytes) =====");
+        for (int offset = 0; offset < bytes.length; offset += 16) {
+            StringBuilder line = new StringBuilder();
+            line.append(address.add(offset)).append(":");
+            int end = Math.min(offset + 16, bytes.length);
+            for (int index = offset; index < end; index++) {
+                line.append(String.format(" %02x", bytes[index] & 0xff));
+            }
+            println(line.toString());
+        }
+    }
+}

scientific_method_engine/ghidra/ReportDecompileMatches.java

@@ -0,0 +1,71 @@
+// Prints bounded context around requested text in one focused decompilation.
+// @category Restoration
+
+import ghidra.app.decompiler.DecompInterface;
+import ghidra.app.decompiler.DecompileResults;
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+
+import java.util.LinkedHashSet;
+import java.util.Set;
+
+public class ReportDecompileMatches extends GhidraScript {
+    private static final int CONTEXT_LINES = 2;
+    private static final int MAX_LINES = 240;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length < 2) {
+            printerr("Supply a virtual address followed by one or more literal text patterns.");
+            return;
+        }
+
+        Address address = toAddr(arguments[0]);
+        Function function = currentProgram.getFunctionManager().getFunctionContaining(address);
+        if (function == null) {
+            printerr(arguments[0] + ": no containing function");
+            return;
+        }
+
+        DecompInterface decompiler = new DecompInterface();
+        decompiler.openProgram(currentProgram);
+        try {
+            DecompileResults result = decompiler.decompileFunction(function, 60, monitor);
+            if (!result.decompileCompleted()) {
+                printerr("Decompiler failed: " + result.getErrorMessage());
+                return;
+            }
+
+            String[] lines = result.getDecompiledFunction().getC().split("\\R");
+            Set<Integer> selected = new LinkedHashSet<>();
+            for (int index = 0; index < lines.length; index++) {
+                for (int pattern = 1; pattern < arguments.length; pattern++) {
+                    if (lines[index].contains(arguments[pattern])) {
+                        for (int context = Math.max(0, index - CONTEXT_LINES);
+                             context <= Math.min(lines.length - 1, index + CONTEXT_LINES);
+                             context++) selected.add(context);
+                    }
+                }
+            }
+
+            println("===== " + function.getEntryPoint() + " " + function.getName() + " =====");
+            int emitted = 0;
+            int previous = -2;
+            for (int index : selected) {
+                if (emitted++ >= MAX_LINES) {
+                    println("... output capped at " + MAX_LINES + " lines");
+                    break;
+                }
+                if (index > previous + 1) println("...");
+                println((index + 1) + ": " + lines[index]);
+                previous = index;
+            }
+            if (selected.isEmpty()) println("No requested patterns matched.");
+        }
+        finally {
+            decompiler.dispose();
+        }
+    }
+}

scientific_method_engine/ghidra/ReportDecompileWindow.java

@@ -0,0 +1,61 @@
+// Prints an explicitly bounded line window from one focused decompilation.
+// @category Restoration
+
+import ghidra.app.decompiler.DecompInterface;
+import ghidra.app.decompiler.DecompileResults;
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+
+public class ReportDecompileWindow extends GhidraScript {
+    private static final int MAX_LINES = 160;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length != 3) {
+            printerr("Supply a virtual address, one-based start line, and line count.");
+            return;
+        }
+
+        Address address = toAddr(arguments[0]);
+        int requestedStart = Integer.parseInt(arguments[1]);
+        int requestedCount = Integer.parseInt(arguments[2]);
+        if (requestedStart < 1 || requestedCount < 1 || requestedCount > MAX_LINES) {
+            printerr("Start must be positive and count must be between 1 and " + MAX_LINES + ".");
+            return;
+        }
+
+        Function function = currentProgram.getFunctionManager().getFunctionContaining(address);
+        if (function == null) {
+            printerr(arguments[0] + ": no containing function");
+            return;
+        }
+
+        DecompInterface decompiler = new DecompInterface();
+        decompiler.openProgram(currentProgram);
+        try {
+            DecompileResults result = decompiler.decompileFunction(function, 60, monitor);
+            if (!result.decompileCompleted()) {
+                printerr("Decompiler failed: " + result.getErrorMessage());
+                return;
+            }
+
+            String[] lines = result.getDecompiledFunction().getC().split("\\R");
+            int start = requestedStart - 1;
+            if (start >= lines.length) {
+                printerr("Start line " + requestedStart + " exceeds " + lines.length + " lines.");
+                return;
+            }
+            int end = Math.min(lines.length, start + requestedCount);
+            println("===== " + function.getEntryPoint() + " " + function.getName()
+                + " lines " + (start + 1) + "-" + end + " of " + lines.length + " =====");
+            for (int index = start; index < end; index++) {
+                println((index + 1) + ": " + lines[index]);
+            }
+        }
+        finally {
+            decompiler.dispose();
+        }
+    }
+}

scientific_method_engine/ghidra/ReportFilePatternInMemory.java

@@ -0,0 +1,102 @@
+// Finds a file-offset byte pattern anywhere in Ghidra loaded memory.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.Instruction;
+import ghidra.program.model.listing.Listing;
+import ghidra.program.model.mem.Memory;
+import ghidra.program.model.symbol.Reference;
+import ghidra.program.model.symbol.ReferenceIterator;
+import ghidra.program.model.symbol.ReferenceManager;
+
+import java.io.File;
+import java.nio.file.Files;
+
+public class ReportFilePatternInMemory extends GhidraScript {
+    private static final int MAX_MATCHES = 8;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length < 1) {
+            printerr("Supply file offset in hex and optional pattern length.");
+            return;
+        }
+
+        File executable = new File(currentProgram.getExecutablePath());
+        if (!executable.isFile()) {
+            printerr("Executable path unavailable: " + currentProgram.getExecutablePath());
+            return;
+        }
+        byte[] fileBytes = Files.readAllBytes(executable.toPath());
+        long fileOffset = parseHex(arguments[0]);
+        int length = arguments.length > 1 ? Integer.decode(arguments[1]) : 8;
+        if (fileOffset < 0 || length < 1 || fileOffset + length > fileBytes.length) {
+            printerr("File offset out of range.");
+            return;
+        }
+
+        byte[] pattern = new byte[length];
+        System.arraycopy(fileBytes, (int) fileOffset, pattern, 0, length);
+        println("===== searching for file offset " + arguments[0] + " pattern =====");
+        println(toHex(pattern));
+
+        Memory memory = currentProgram.getMemory();
+        Listing listing = currentProgram.getListing();
+        ReferenceManager referenceManager = currentProgram.getReferenceManager();
+        Address cursor = memory.getMinAddress();
+        int matches = 0;
+        while (cursor != null && matches < MAX_MATCHES && !monitor.isCancelled()) {
+            Address found = memory.findBytes(cursor, pattern, null, true, monitor);
+            if (found == null) break;
+
+            Function function = listing.getFunctionContaining(found);
+            Instruction instruction = listing.getInstructionContaining(found);
+            println("Match " + (matches + 1) + ": " + found
+                + (function == null ? "" : " in " + function.getEntryPoint() + " " + function.getName())
+                + (instruction == null ? "" : " :: " + instruction));
+
+            ReferenceIterator references = referenceManager.getReferencesTo(found);
+            int refCount = 0;
+            while (references.hasNext() && refCount < 10) {
+                Reference reference = references.next();
+                Function fromFunction = listing.getFunctionContaining(reference.getFromAddress());
+                println("  ref from " + reference.getFromAddress()
+                    + (fromFunction == null ? "" : " in " + fromFunction.getEntryPoint() + " " + fromFunction.getName())
+                    + " " + reference.getReferenceType());
+                refCount++;
+            }
+            if (refCount == 0) {
+                println("  no incoming references");
+            }
+
+            // next() is null past the last address, which ends the search.
+            cursor = found.next();
+            matches++;
+        }
+
+        if (matches == 0) {
+            println("Pattern not found in loaded memory.");
+        }
+    }
+
+    // The offset is hex with or without 0x, as for ReportMemoryBlockForFileOffset; Long.decode alone
+    // would read a bare 76640 as decimal and a leading zero as octal.
+    private static long parseHex(String argument) {
+        String normalized = argument.trim();
+        if (normalized.startsWith("0x") || normalized.startsWith("0X")) {
+            normalized = normalized.substring(2);
+        }
+        return Long.parseLong(normalized, 16);
+    }
+
+    private static String toHex(byte[] bytes) {
+        StringBuilder builder = new StringBuilder();
+        for (byte value : bytes) {
+            builder.append(String.format("%02X ", value));
+        }
+        return builder.toString().trim();
+    }
+}