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

scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java

@@ -0,0 +1,63 @@
+// Summarizes immediate x86 cdecl first arguments at every direct call to one function.
+// Calls without an immediately preceding literal PUSH are listed for follow-up.
+// @category Restoration
+
+import java.util.Map;
+import java.util.TreeMap;
+
+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 ReportFirstArgumentCallSummary extends GhidraScript {
+    @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);
+        Map<Long, Integer> literals = new TreeMap<>();
+        int calls = 0;
+        int nonLiteral = 0;
+        while (references.hasNext() && !monitor.isCancelled()) {
+            Reference reference = references.next();
+            Instruction call = currentProgram.getListing().getInstructionAt(reference.getFromAddress());
+            if (call == null || !call.getFlowType().isCall()) continue;
+            calls++;
+
+            Instruction push = call.getPrevious();
+            Long literal = pushedLiteral(push);
+            if (literal != null) {
+                literals.merge(literal, 1, Integer::sum);
+                continue;
+            }
+
+            nonLiteral++;
+            Function function = currentProgram.getFunctionManager().getFunctionContaining(call.getAddress());
+            println("Non-literal at " + call.getAddress()
+                + (function == null ? "" : " in " + function.getEntryPoint() + " " + function.getName())
+                + " first=" + (push == null ? "<none>" : push));
+        }
+
+        println("Direct calls: " + calls);
+        for (Map.Entry<Long, Integer> entry : literals.entrySet())
+            println("Literal " + entry.getKey() + ": " + entry.getValue());
+        println("Non-literal: " + nonLiteral);
+    }
+
+    private static Long pushedLiteral(Instruction instruction) {
+        if (instruction == null || !"PUSH".equals(instruction.getMnemonicString())) return null;
+        for (Object object : instruction.getOpObjects(0)) {
+            if (object instanceof Scalar scalar) return scalar.getUnsignedValue();
+        }
+        return null;
+    }
+}

scientific_method_engine/ghidra/ReportFunctionScalarConstants.java

@@ -0,0 +1,56 @@
+// Reports instruction references to selected scalar values within one 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.scalar.Scalar;
+
+import java.util.HashSet;
+import java.util.Set;
+
+public class ReportFunctionScalarConstants extends GhidraScript {
+    private static final int MAX_MATCHES = 200;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length < 2) {
+            printerr("Supply a function address followed by one or more scalar values.");
+            return;
+        }
+
+        Address address = toAddr(arguments[0]);
+        Function function = currentProgram.getFunctionManager().getFunctionContaining(address);
+        if (function == null) {
+            printerr(arguments[0] + ": no containing function");
+            return;
+        }
+
+        Set<Long> requested = new HashSet<>();
+        for (int index = 1; index < arguments.length; index++)
+            requested.add(Long.decode(arguments[index]));
+
+        int matches = 0;
+        Instruction instruction = currentProgram.getListing()
+            .getInstructionAt(function.getEntryPoint());
+        while (instruction != null && function.getBody().contains(instruction.getAddress())
+            && !monitor.isCancelled()) {
+            for (int operand = 0; operand < instruction.getNumOperands(); operand++) {
+                for (Object object : instruction.getOpObjects(operand)) {
+                    if (!(object instanceof Scalar scalar)
+                        || !requested.contains(scalar.getUnsignedValue())) continue;
+                    println(scalar.getUnsignedValue() + " at " + instruction.getAddress()
+                        + ": " + instruction);
+                    if (++matches >= MAX_MATCHES) {
+                        println("... output capped at " + MAX_MATCHES + " matches");
+                        return;
+                    }
+                }
+            }
+            instruction = instruction.getNext();
+        }
+        if (matches == 0) println("No requested scalar constants matched.");
+    }
+}

scientific_method_engine/ghidra/ReportFunctionSummary.java

@@ -0,0 +1,64 @@
+// Prints focused decompiler output for explicitly supplied virtual addresses.
+// @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 ghidra.program.model.symbol.Reference;
+import ghidra.program.model.symbol.ReferenceIterator;
+
+import java.util.Set;
+import java.util.TreeSet;
+
+public class ReportFunctionSummary extends GhidraScript {
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length == 0) {
+            printerr("Supply one or more virtual addresses, for example 0x00478cd0.");
+            return;
+        }
+
+        DecompInterface decompiler = new DecompInterface();
+        decompiler.openProgram(currentProgram);
+        try {
+            for (String argument : arguments) {
+                Address address = toAddr(argument);
+                Function function = currentProgram.getFunctionManager().getFunctionContaining(address);
+                if (function == null) {
+                    println(argument + ": no containing function");
+                    continue;
+                }
+
+                println("===== " + function.getEntryPoint() + " " + function.getName() + " =====");
+                Set<String> callers = new TreeSet<>();
+                ReferenceIterator references = currentProgram.getReferenceManager()
+                    .getReferencesTo(function.getEntryPoint());
+                while (references.hasNext()) {
+                    Reference reference = references.next();
+                    Function caller = currentProgram.getFunctionManager()
+                        .getFunctionContaining(reference.getFromAddress());
+                    callers.add(caller == null
+                        ? reference.getFromAddress().toString()
+                        : caller.getEntryPoint() + " " + caller.getName()
+                            + " at " + reference.getFromAddress());
+                }
+                println("Incoming references:");
+                for (String caller : callers) {
+                    println("  " + caller);
+                }
+                DecompileResults result = decompiler.decompileFunction(function, 30, monitor);
+                if (!result.decompileCompleted()) {
+                    println("Decompiler failed: " + result.getErrorMessage());
+                    continue;
+                }
+                println(result.getDecompiledFunction().getC());
+            }
+        }
+        finally {
+            decompiler.dispose();
+        }
+    }
+}

scientific_method_engine/ghidra/ReportInstructionContext.java

@@ -0,0 +1,64 @@
+// Prints bounded instruction context around explicitly supplied addresses.
+// @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 java.util.ArrayList;
+import java.util.List;
+
+public class ReportInstructionContext extends GhidraScript {
+    private static final int CONTEXT_INSTRUCTIONS = 8;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length == 0) {
+            printerr("Supply one or more instruction addresses.");
+            return;
+        }
+
+        Listing listing = currentProgram.getListing();
+        for (String argument : arguments) {
+            Address address = toAddr(argument);
+            Instruction focus = listing.getInstructionContaining(address);
+            if (focus == null) {
+                printerr(argument + ": no containing instruction");
+                continue;
+            }
+
+            Function function = currentProgram.getFunctionManager()
+                .getFunctionContaining(focus.getAddress());
+            println("===== " + focus.getAddress()
+                + (function == null ? "" : " in " + function.getEntryPoint()
+                    + " " + function.getName()) + " =====");
+
+            List<Instruction> before = new ArrayList<>();
+            Instruction cursor = focus;
+            for (int count = 0; count < CONTEXT_INSTRUCTIONS; count++) {
+                cursor = cursor.getPrevious();
+                if (cursor == null || (function != null
+                    && !function.getBody().contains(cursor.getAddress()))) break;
+                before.add(0, cursor);
+            }
+            for (Instruction instruction : before) printInstruction(instruction, false);
+            printInstruction(focus, true);
+
+            cursor = focus;
+            for (int count = 0; count < CONTEXT_INSTRUCTIONS; count++) {
+                cursor = cursor.getNext();
+                if (cursor == null || (function != null
+                    && !function.getBody().contains(cursor.getAddress()))) break;
+                printInstruction(cursor, false);
+            }
+        }
+    }
+
+    private void printInstruction(Instruction instruction, boolean focus) {
+        println((focus ? "> " : "  ") + instruction.getAddress() + "  "
+            + instruction.toString());
+    }
+}

scientific_method_engine/ghidra/ReportInstructionWindow.java

@@ -0,0 +1,36 @@
+// Prints a bounded instruction window beginning at a virtual address.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.address.Address;
+import ghidra.program.model.listing.Instruction;
+
+public class ReportInstructionWindow extends GhidraScript {
+    private static final int MAX_INSTRUCTIONS = 200;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length != 2) {
+            printerr("Supply a virtual address and instruction count.");
+            return;
+        }
+
+        Address address = toAddr(arguments[0]);
+        int count = Integer.parseInt(arguments[1]);
+        if (count < 1 || count > MAX_INSTRUCTIONS) {
+            printerr("Instruction count must be between 1 and " + MAX_INSTRUCTIONS + ".");
+            return;
+        }
+
+        Instruction instruction = currentProgram.getListing().getInstructionAt(address);
+        if (instruction == null) {
+            instruction = currentProgram.getListing().getInstructionAfter(address);
+        }
+
+        for (int index = 0; instruction != null && index < count; index++) {
+            println(instruction.getAddress() + ": " + instruction);
+            instruction = instruction.getNext();
+        }
+    }
+}

scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java

@@ -0,0 +1,105 @@
+// Maps file offsets to loaded addresses and their memory blocks, and prints nearby instructions.
+// @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.mem.MemoryBlock;
+
+import java.io.File;
+import java.nio.file.Files;
+import java.util.List;
+
+public class ReportMemoryBlockForFileOffset extends GhidraScript {
+    private static final int PATTERN_BYTES = 12;
+    private static final int FOLLOW_INSTRUCTIONS = 8;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length == 0) {
+            printerr("Supply one or more file offsets in hex, for example 76640.");
+            return;
+        }
+
+        File executable = new File(currentProgram.getExecutablePath());
+        if (!executable.isFile()) {
+            printerr("Executable path unavailable: " + currentProgram.getExecutablePath());
+            return;
+        }
+
+        byte[] fileBytes = Files.readAllBytes(executable.toPath());
+        Memory memory = currentProgram.getMemory();
+        Listing listing = currentProgram.getListing();
+
+        for (String argument : arguments) {
+            long fileOffset = parseHex(argument);
+            if (fileOffset < 0 || fileOffset + PATTERN_BYTES > fileBytes.length) {
+                printerr(argument + ": file offset out of range.");
+                continue;
+            }
+
+            byte[] pattern = new byte[PATTERN_BYTES];
+            System.arraycopy(fileBytes, (int) fileOffset, pattern, 0, PATTERN_BYTES);
+            println("===== file offset " + argument + " =====");
+            println("Pattern: " + toHex(pattern));
+
+            // The loader's own file-byte mapping is exact. Without one (some loaders keep no
+            // FileBytes), fall back to the first place the bytes occur, and say when that is ambiguous.
+            List<Address> mapped = memory.locateAddressesForFileOffset(fileOffset);
+            if (mapped.isEmpty()) {
+                Address found = memory.findBytes(memory.getMinAddress(), pattern, null, true, monitor);
+                if (found == null) {
+                    println("Pattern not found in loaded memory.");
+                    continue;
+                }
+                Address after = found.next();
+                if (after != null && memory.findBytes(after, pattern, null, true, monitor) != null) {
+                    println("Pattern occurs more than once; the first match may not be this offset.");
+                }
+                mapped = List.of(found);
+            }
+
+            for (Address address : mapped) {
+                MemoryBlock block = memory.getBlock(address);
+                println("Mapped address: " + address
+                    + (block == null ? "" : " in block " + block.getName()));
+                Instruction instruction = listing.getInstructionContaining(address);
+                if (instruction == null) {
+                    println("No instruction at mapped address.");
+                    continue;
+                }
+
+                Function function = listing.getFunctionContaining(instruction.getAddress());
+                println("===== " + instruction.getAddress()
+                    + (function == null ? "" : " in " + function.getEntryPoint() + " " + function.getName())
+                    + " =====");
+                Instruction cursor = instruction;
+                for (int count = 0; count < FOLLOW_INSTRUCTIONS; count++) {
+                    if (cursor == null) break;
+                    println(cursor.getAddress() + "  " + cursor);
+                    cursor = cursor.getNext();
+                }
+            }
+        }
+    }
+
+    private static long parseHex(String argument) {
+        String normalized = argument.trim();
+        if (normalized.startsWith("0x") || normalized.startsWith("0X")) {
+            return Long.decode(normalized);
+        }
+        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();
+    }
+}

scientific_method_engine/ghidra/ReportMemoryBlocks.java

@@ -0,0 +1,52 @@
+// Reports a bounded selection of memory blocks; never bytes or instructions.
+// @category Restoration
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.mem.MemoryBlock;
+
+public class ReportMemoryBlocks extends GhidraScript {
+    private static final int MAX_BLOCKS = 512;
+    private static final int MAX_LISTED_MATCHES = 16;
+    @Override
+    protected void run() throws Exception {
+        String[] args = getScriptArgs();
+        MemoryBlock[] blocks = currentProgram.getMemory().getBlocks();
+        int start = 0, count = blocks.length;
+        String scope = "whole map", requested = "";
+        if (args.length == 3 && args[0].equals("page")) {
+            try { start = Integer.parseInt(args[1]); count = Integer.parseInt(args[2]); }
+            catch (NumberFormatException e) { printerr("Page start/count must be integers."); return; }
+            if (start < 0 || start > blocks.length || count < 1 || count > MAX_BLOCKS) {
+                printerr("Page start must be within 0.." + blocks.length + "; count within 1.." + MAX_BLOCKS + "."); return;
+            }
+            requested = " requested=" + count;
+            count = Math.min(count, blocks.length - start);
+            scope = "page; indices follow the current program's block order";
+        } else if (args.length == 2 && args[0].equals("name")) {
+            start = -1;
+            int matches = 0;
+            StringBuilder indices = new StringBuilder();
+            for (int i = 0; i < blocks.length; i++) {
+                if (!blocks[i].getName().equals(args[1])) continue;
+                if (matches++ == 0) start = i;
+                if (matches <= MAX_LISTED_MATCHES) indices.append(matches == 1 ? "" : ",").append(i);
+            }
+            if (matches == 0) { printerr("No block with that exact name."); return; }
+            if (matches > 1) {
+                printerr("Ambiguous block name: " + matches + " blocks at indices " + indices +
+                    (matches > MAX_LISTED_MATCHES ? ",..." : "") + "; select a page instead."); return;
+            }
+            count = 1; scope = "exact block name";
+        } else if (args.length != 0) {
+            printerr("Usage: ReportMemoryBlocks.java [page <start-index> <count> | name <exact-name>]"); return;
+        }
+        if (count > MAX_BLOCKS) {
+            printerr("Program has " + blocks.length + " blocks; maximum is " + MAX_BLOCKS + ". Select page or name."); return;
+        }
+        println("total=" + blocks.length + " start=" + start + " emitted=" + count +
+            " partial=" + (count != blocks.length) + requested + " scope=" + scope);
+        for (int i = start; i < start + count; i++) {
+            MemoryBlock b = blocks[i];
+            println(i + " " + b.getName() + " " + b.getStart() + "-" + b.getEnd() + " size=" + b.getSize());
+        }
+    }
+}

scientific_method_engine/ghidra/ReportRandomnessCandidates.java

@@ -0,0 +1,74 @@
+// Lists references to symbols named like C runtime or Windows random and timing functions (rand,
+// srand, time, GetTickCount, QueryPerformanceCounter and similar), with their calling functions.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.symbol.Reference;
+import ghidra.program.model.symbol.ReferenceIterator;
+import ghidra.program.model.symbol.Symbol;
+import ghidra.program.model.symbol.SymbolIterator;
+
+import java.util.Locale;
+import java.util.Set;
+import java.util.TreeSet;
+
+public class ReportRandomnessCandidates extends GhidraScript {
+    private static final int MAX_MATCHES = 100;
+    private static final int MAX_CALLERS_PER_MATCH = 100;
+    private static final String[] CANDIDATE_NAMES = {
+        "rand", "srand", "random", "randomize", "time", "gettickcount",
+        "queryperformancecounter", "timegettime", "getsystemtime"
+    };
+
+    @Override
+    protected void run() throws Exception {
+        println("Randomness/timing candidate references for " + currentProgram.getName());
+        int matches = 0;
+        SymbolIterator symbols = currentProgram.getSymbolTable().getAllSymbols(true);
+        while (symbols.hasNext() && matches < MAX_MATCHES && !monitor.isCancelled()) {
+            Symbol symbol = symbols.next();
+            if (!isCandidate(symbol.getName())) {
+                continue;
+            }
+
+            matches++;
+            Set<String> callers = new TreeSet<>();
+            ReferenceIterator references = currentProgram.getReferenceManager()
+                .getReferencesTo(symbol.getAddress());
+            while (references.hasNext() && callers.size() < MAX_CALLERS_PER_MATCH
+                && !monitor.isCancelled()) {
+                Reference reference = references.next();
+                Function caller = currentProgram.getFunctionManager()
+                    .getFunctionContaining(reference.getFromAddress());
+                callers.add(caller == null
+                    ? reference.getFromAddress().toString()
+                    : caller.getEntryPoint() + " " + caller.getName());
+            }
+
+            println(symbol.getAddress() + " " + symbol.getName(true));
+            for (String caller : callers) {
+                println("  caller " + caller);
+            }
+            if (references.hasNext()) {
+                println("  ... callers capped at " + MAX_CALLERS_PER_MATCH);
+            }
+        }
+
+        if (matches == 0) println("No randomness or timing candidates matched.");
+        else if (matches == MAX_MATCHES && symbols.hasNext()) {
+            println("Output capped at " + MAX_MATCHES + " candidate symbols; later symbols were not scanned.");
+        }
+    }
+
+    private static boolean isCandidate(String name) {
+        String lower = name.toLowerCase(Locale.ROOT);
+        for (String candidate : CANDIDATE_NAMES) {
+            if (lower.equals(candidate) || lower.endsWith("::" + candidate)
+                || lower.contains("_" + candidate)) {
+                return true;
+            }
+        }
+        return false;
+    }
+}

scientific_method_engine/ghidra/ReportReferences.java

@@ -0,0 +1,42 @@
+// Reports bounded references to explicitly supplied virtual addresses.
+// @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;
+
+public class ReportReferences extends GhidraScript {
+    private static final int MAX_REFERENCES = 200;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length == 0) {
+            printerr("Supply one or more virtual addresses.");
+            return;
+        }
+
+        for (String argument : arguments) {
+            Address target = toAddr(argument);
+            println("===== references to " + target + " =====");
+            ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(target);
+            int count = 0;
+            while (references.hasNext() && count < MAX_REFERENCES && !monitor.isCancelled()) {
+                Reference reference = references.next();
+                Instruction instruction = currentProgram.getListing().getInstructionContaining(reference.getFromAddress());
+                Function function = currentProgram.getFunctionManager().getFunctionContaining(reference.getFromAddress());
+                println(reference.getFromAddress()
+                    + (function == null ? "" : " in " + function.getEntryPoint() + " " + function.getName())
+                    + " " + reference.getReferenceType()
+                    + (instruction == null ? "" : ": " + instruction));
+                count++;
+            }
+
+            if (count == 0) println("No references found.");
+            else if (count == MAX_REFERENCES && references.hasNext()) println("Output capped at " + MAX_REFERENCES + " references.");
+        }
+    }
+}

scientific_method_engine/ghidra/ReportScalarConstants.java

@@ -0,0 +1,55 @@
+// Reports bounded instruction references to explicitly supplied scalar values.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.listing.Instruction;
+import ghidra.program.model.listing.InstructionIterator;
+import ghidra.program.model.scalar.Scalar;
+
+import java.util.HashSet;
+import java.util.Set;
+
+public class ReportScalarConstants extends GhidraScript {
+    private static final int MAX_MATCHES = 300;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length == 0) {
+            printerr("Supply one or more scalar values (decimal or 0x-prefixed). ");
+            return;
+        }
+
+        Set<Long> requested = new HashSet<>();
+        for (String argument : arguments) requested.add(Long.decode(argument));
+        int matches = 0;
+        InstructionIterator instructions = currentProgram.getListing().getInstructions(true);
+        while (instructions.hasNext() && !monitor.isCancelled()) {
+            Instruction instruction = instructions.next();
+            for (int operand = 0; operand < instruction.getNumOperands(); operand++) {
+                for (Object object : instruction.getOpObjects(operand)) {
+                    if (!(object instanceof Scalar scalar)
+                        || !matchesRequested(scalar, requested)) continue;
+                    Function function = currentProgram.getFunctionManager()
+                        .getFunctionContaining(instruction.getAddress());
+                    println(scalar.getUnsignedValue() + " at " + instruction.getAddress()
+                        + (function == null ? "" : " in " + function.getEntryPoint()
+                            + " " + function.getName()));
+                    if (++matches >= MAX_MATCHES) {
+                        println("... output capped at " + MAX_MATCHES + " matches");
+                        return;
+                    }
+                }
+            }
+        }
+        if (matches == 0) println("No requested scalar constants matched.");
+    }
+
+    // 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());
+    }
+}