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

scientific_method_engine/ghidra/ReportStringReferences.java

@@ -0,0 +1,102 @@
+// Finds bounded references to explicitly requested string fragments.
+// @category Restoration
+
+import ghidra.app.script.GhidraScript;
+import ghidra.program.model.listing.Data;
+import ghidra.program.model.listing.DataIterator;
+import ghidra.program.model.listing.Function;
+import ghidra.program.model.mem.Memory;
+import ghidra.program.model.mem.MemoryBlock;
+import ghidra.program.model.symbol.Reference;
+import ghidra.program.model.symbol.ReferenceIterator;
+
+import java.util.Locale;
+
+public class ReportStringReferences extends GhidraScript {
+    private static final int MAX_MATCHES = 100;
+    private static final int MAX_REFERENCES_PER_MATCH = 100;
+    private static final int MAX_POINTERS_PER_MATCH = 100;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length == 0) {
+            printerr("Supply one or more literal string fragments.");
+            return;
+        }
+
+        var needles = new String[arguments.length];
+        for (var index = 0; index < arguments.length; index++)
+            needles[index] = arguments[index].toUpperCase(Locale.ROOT);
+
+        var matches = 0;
+        DataIterator data = currentProgram.getListing().getDefinedData(true);
+        while (data.hasNext() && matches < MAX_MATCHES && !monitor.isCancelled()) {
+            Data candidate = data.next();
+            Object value = candidate.getValue();
+            if (!(value instanceof String text)) continue;
+            String upper = text.toUpperCase(Locale.ROOT);
+            var requested = false;
+            for (String needle : needles) {
+                if (!upper.contains(needle)) continue;
+                requested = true;
+                break;
+            }
+            if (!requested) continue;
+
+            matches++;
+            println("===== " + candidate.getAddress() + " \"" + text + "\" =====");
+            ReferenceIterator references = currentProgram.getReferenceManager()
+                .getReferencesTo(candidate.getAddress());
+            var emitted = 0;
+            while (references.hasNext() && emitted < MAX_REFERENCES_PER_MATCH) {
+                Reference reference = references.next();
+                Function function = currentProgram.getFunctionManager()
+                    .getFunctionContaining(reference.getFromAddress());
+                println("  " + reference.getFromAddress() + " " + reference.getReferenceType()
+                    + (function == null ? "" : " in " + function.getEntryPoint() + " " + function.getName()));
+                emitted++;
+            }
+            if (references.hasNext())
+                println("  ... references capped at " + MAX_REFERENCES_PER_MATCH);
+            reportRawPointers(candidate);
+        }
+
+        if (matches == 0) println("No requested strings matched.");
+        else if (matches == MAX_MATCHES) println("Output capped at " + MAX_MATCHES + " matching strings.");
+    }
+
+    private void reportRawPointers(Data candidate) throws Exception {
+        long offset = candidate.getAddress().getOffset();
+        byte[] pointer = new byte[] {
+            (byte) offset,
+            (byte) (offset >>> 8),
+            (byte) (offset >>> 16),
+            (byte) (offset >>> 24)
+        };
+        Memory memory = currentProgram.getMemory();
+        var emitted = 0;
+        for (MemoryBlock block : memory.getBlocks()) {
+            var cursor = block.getStart();
+            while (cursor.compareTo(block.getEnd()) <= 0 && emitted < MAX_POINTERS_PER_MATCH) {
+                var found = memory.findBytes(cursor, pointer, null, true, monitor);
+                if (found == null || !block.contains(found)) break;
+                println("  raw pointer at " + found + " in " + block.getName());
+                ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(found);
+                while (references.hasNext() && emitted < MAX_POINTERS_PER_MATCH) {
+                    Reference reference = references.next();
+                    Function function = currentProgram.getFunctionManager()
+                        .getFunctionContaining(reference.getFromAddress());
+                    println("    used at " + reference.getFromAddress()
+                        + (function == null ? "" : " in " + function.getEntryPoint() + " " + function.getName()));
+                    emitted++;
+                }
+                emitted++;
+                cursor = found.add(1);
+            }
+            if (emitted >= MAX_POINTERS_PER_MATCH) break;
+        }
+        if (emitted >= MAX_POINTERS_PER_MATCH)
+            println("  ... raw pointer output capped at " + MAX_POINTERS_PER_MATCH);
+    }
+}

scientific_method_engine/ghidra/ReportSymbolReferences.java

@@ -0,0 +1,72 @@
+// Reports bounded references to explicitly requested symbol-name fragments.
+// @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;
+
+public class ReportSymbolReferences extends GhidraScript {
+    private static final int MAX_MATCHES = 100;
+    private static final int MAX_REFERENCES_PER_MATCH = 100;
+
+    @Override
+    protected void run() throws Exception {
+        String[] arguments = getScriptArgs();
+        if (arguments.length == 0) {
+            printerr("Supply one or more literal symbol-name fragments.");
+            return;
+        }
+
+        String[] needles = new String[arguments.length];
+        for (int index = 0; index < arguments.length; index++) {
+            if (arguments[index].isBlank()) {
+                printerr("Symbol-name fragments must not be blank.");
+                return;
+            }
+            needles[index] = arguments[index].toUpperCase(Locale.ROOT);
+        }
+
+        int matches = 0;
+        SymbolIterator symbols = currentProgram.getSymbolTable().getAllSymbols(true);
+        while (symbols.hasNext() && matches < MAX_MATCHES && !monitor.isCancelled()) {
+            Symbol symbol = symbols.next();
+            String name = symbol.getName(true);
+            if (!matchesAny(name.toUpperCase(Locale.ROOT), needles)) continue;
+
+            matches++;
+            println("===== " + symbol.getAddress() + " " + name + " =====");
+            ReferenceIterator references = currentProgram.getReferenceManager()
+                .getReferencesTo(symbol.getAddress());
+            int emitted = 0;
+            while (references.hasNext() && emitted < MAX_REFERENCES_PER_MATCH) {
+                Reference reference = references.next();
+                Function function = currentProgram.getFunctionManager()
+                    .getFunctionContaining(reference.getFromAddress());
+                println("  " + reference.getFromAddress() + " " + reference.getReferenceType()
+                    + (function == null ? "" : " in " + function.getEntryPoint()
+                        + " " + function.getName()));
+                emitted++;
+            }
+            if (references.hasNext()) {
+                println("  ... references capped at " + MAX_REFERENCES_PER_MATCH);
+            }
+        }
+
+        if (matches == 0) println("No requested symbols matched.");
+        else if (matches == MAX_MATCHES) {
+            println("Output capped at " + MAX_MATCHES + " matching symbols.");
+        }
+    }
+
+    private static boolean matchesAny(String name, String[] needles) {
+        for (String needle : needles) {
+            if (name.contains(needle)) return true;
+        }
+        return false;
+    }
+}

scientific_method_engine/x86/dispatch.py

@@ -0,0 +1,51 @@
+"""Explicit, source-derived indirect jump tables for CFG discovery only."""
+from capstone.x86 import X86_OP_IMM
+from .image import integer
+
+
+def read_indirect_jumps(image):
+    declarations = image.config.get("indirectJumps", [])
+    if not isinstance(declarations, list) or len(declarations) > 256:
+        raise ValueError("indirectJumps must contain at most 256 declarations")
+    if declarations and image.flat:
+        raise ValueError("indirectJumps currently requires segmented16")
+    result = {}
+    for claim in declarations:
+        if not isinstance(claim, dict):
+            raise ValueError("Each indirect jump needs an object")
+        site = integer(claim.get("site"), 0, len(image.data) - 1, "indirect jump site")
+        if site in result:
+            raise ValueError("Duplicate indirect jump site")
+        if not isinstance(claim.get("evidence"), str) or not claim["evidence"].strip():
+            raise ValueError("An indirect jump needs consumer/mapping evidence")
+        if type(claim.get("exhaustive")) is not bool:
+            raise ValueError("An indirect jump needs explicit exhaustive true or false")
+        ins = image.decode(site)
+        if (ins is None or ins.mnemonic != "jmp" or len(ins.operands) != 1
+                or ins.operands[0].type == X86_OP_IMM or ins.operands[0].size != 2
+                or 0x66 in ins.prefix or 0x67 in ins.prefix):
+            raise ValueError("indirectJumps site must decode as an unprefixed computed near word jump")
+        table = claim.get("table")
+        if not isinstance(table, dict) or not isinstance(table.get("evidence"), str) or not table["evidence"].strip():
+            raise ValueError("Indirect table needs layout/count evidence")
+        if type(table.get("width", 2)) is not int or table.get("width", 2) != 2:
+            raise ValueError("Indirect table targets must be word width 2")
+        start = integer(table.get("start"), 0, len(image.data) - 1, "indirect table start")
+        count = integer(table.get("count"), 1, 256, "indirect table count")
+        stride = integer(table.get("stride"), 2, 65536, "indirect table stride")
+        field = integer(table.get("fieldOffset", 0), 0, stride - 2, "indirect target field offset")
+        if start + (count - 1) * stride + field + 2 > len(image.data):
+            raise ValueError("Indirect table leaves source bounds")
+        rows = []
+        for index in range(count):
+            operand = start + index * stride + field
+            raw = int.from_bytes(image.data[operand:operand + 2], "little")
+            target = image.near_target(site, raw)
+            if target is None:
+                raise ValueError("Indirect table target leaves declared code mappings")
+            rows.append({"index": index, "operandSite": operand, "rawOffset": raw, "target": target})
+        result[site] = {"site": site, "evidence": claim["evidence"], "table": table,
+                        "exhaustive": claim["exhaustive"], "rows": rows,
+                        "interpretation": "source words under supplied consumer, mapping and exhaustiveness evidence; "
+                                          "not executed dispatch or an overlap-boundary proof"}
+    return result

scientific_method_engine/x86/image.py

@@ -0,0 +1,172 @@
+"""Bounded explicit code mappings. No guessed linear disassembly domains."""
+import hashlib
+from pathlib import Path
+from capstone import Cs, CS_ARCH_X86, CS_MODE_16, CS_MODE_32
+from .pe import prepare_pe
+import capstone
+
+MAX_SOURCE = 256 * 1024 * 1024
+
+
+def integer(value, low, high, label):
+    if type(value) is not int or not low <= value <= high:
+        raise ValueError(f"{label} must be an integer in {low}..{high}")
+    return value
+
+
+def read_source(config, base):
+    """Read the source a report config names and check its hash.
+
+    ``config["source"]`` is a path relative to ``base``; the file must be at most 256 MiB and hash to
+    ``config["sha256"]``. Returns ``(data, identity)`` where ``identity`` is
+    ``{"size": ..., "sha256": ...}``. Raises ``ValueError`` otherwise.
+    """
+    path = config.get("source")
+    if not isinstance(path, str) or not path:
+        raise ValueError("source path required")
+    path = Path(base) / path
+    if not path.is_file() or path.stat().st_size > MAX_SOURCE:
+        raise ValueError("source must be a regular file of at most 256 MiB")
+    data = path.read_bytes()
+    digest = hashlib.sha256(data).hexdigest()
+    if digest != config.get("sha256"):
+        raise ValueError("Source SHA-256 differs from the supplied baseline")
+    return data, {"size": len(data), "sha256": digest}
+
+
+class Image:
+    def __init__(self, data, config):
+        if capstone.__version__ != "5.0.7":
+            raise ValueError("This reporter requires capstone==5.0.7")
+        if config.get("sourceKind") == "pe32":
+            config = prepare_pe(data, config)
+        self.config = config
+        if config.get("addressModel", "segmented16") not in ("segmented16", "flat32"):
+            raise ValueError("Unknown address model")
+        self.bits = config.get("bits", 16)
+        self.flat = config.get("addressModel", "segmented16") == "flat32"
+        if (self.bits, self.flat) not in ((16, False), (32, True)):
+            raise ValueError("Only segmented16 and flat32 instruction models are supported")
+        if self.flat and config.get("sourceKind") not in ("pe32", "synthetic-raw"):
+            raise ValueError("flat32 requires pe32 or explicit synthetic-raw input")
+        self.mask = (1 << self.bits) - 1
+        self.data = data
+        self.regions = config.get("regions", [])
+        if not isinstance(self.regions, list) or not 1 <= len(self.regions) <= 256:
+            raise ValueError("Declare 1..256 code regions")
+        names = set()
+        for r in self.regions:
+            if not isinstance(r, dict):
+                raise ValueError("Each region must be an object")
+            name = r.get("name")
+            if not isinstance(name, str) or not name or name in names:
+                raise ValueError("Region names must be unique")
+            names.add(name)
+            integer(r.get("start"), 0, len(data), "region start")
+            integer(r.get("end"), r["start"] + 1, len(data), "region end")
+            integer(r.get("ip"), 0, self.mask, "region IP")
+            integer(r.get("segment"), 0, 65535, "region segment")
+            if r["ip"] + r["end"] - r["start"] > 1 << self.bits:
+                raise ValueError("Code region crosses the instruction address boundary")
+            if not isinstance(r.get("evidence"), str) or not r["evidence"].strip():
+                raise ValueError("Each region needs mapping/bounds evidence")
+            entries = r.get("entries")
+            if not isinstance(entries, list) or not entries or len(entries) > 4096:
+                raise ValueError("Each region needs 1..4096 established entry offsets")
+            for at in entries:
+                integer(at, r["start"], r["end"] - 1, "entry")
+            container = r.get("container")
+            if container is not None:
+                # The complete overlay or segment that holds this region, as the Node loader supplies it.
+                if not isinstance(container, dict) or not isinstance(container.get("view"), str) or not container["view"]:
+                    raise ValueError("A region container needs view, start and end")
+                integer(container.get("start"), 0, r["start"], "container start")
+                integer(container.get("end"), r["end"], len(data), "container end")
+        self.segments = config.get("segments", [])
+        if not isinstance(self.segments, list) or len(self.segments) > 256:
+            raise ValueError("segments must be a list of at most 256 declared segment bounds")
+        for d in self.segments:
+            if (not isinstance(d, dict) or not isinstance(d.get("name"), str) or not d["name"]
+                    or not isinstance(d.get("evidence"), str) or not d["evidence"].strip()):
+                raise ValueError("Each declared segment needs name, start, end and evidence")
+            integer(d.get("start"), 0, len(data), "segment start")
+            integer(d.get("end"), d["start"] + 1, len(data), "segment end")
+        for i, r in enumerate(self.regions):
+            for s in self.regions[i + 1:]:
+                if max(r["start"], s["start"]) < min(r["end"], s["end"]):
+                    raise ValueError("Overlapping source regions")
+                if r["segment"] == s["segment"] and max(r["ip"], s["ip"]) < min(r["ip"] + r["end"] - r["start"], s["ip"] + s["end"] - s["start"]):
+                    raise ValueError("Ambiguous loaded region mapping")
+        self.decoder = Cs(CS_ARCH_X86, CS_MODE_32 if self.flat else CS_MODE_16)
+        self.decoder.detail = True
+        self.cache = {}
+        self.relocations = config.get("relocations", [])
+        if not isinstance(self.relocations, list) or len(self.relocations) > 100000:
+            raise ValueError("Invalid relocation metadata")
+        self.fixups = {}
+        for f in self.relocations:
+            integer(f.get("site"), 0, len(data) - 2, "relocation site")
+            integer(f.get("segment"), 0, 65535, "resolved segment")
+            if f["site"] in self.fixups or not f.get("evidence"):
+                raise ValueError("Duplicate relocation or missing provenance")
+            self.fixups[f["site"]] = f
+        from .dispatch import read_indirect_jumps
+        self.indirect_jumps = read_indirect_jumps(self)
+
+    def region(self, site):
+        return next((r for r in self.regions if r["start"] <= site < r["end"]), None)
+
+    def offset(self, segment, ip):
+        exact = [r for r in self.regions if r["segment"] == segment and r["ip"] <= ip < r["ip"] + r["end"] - r["start"]]
+        if exact:
+            r = exact[0]
+            return r["start"] + ip - r["ip"]
+        if self.flat:
+            return None
+        linear = segment * 16 + ip
+        aliases = [r for r in self.regions if r.get("resident", False) and r["segment"] * 16 + r["ip"] <= linear < r["segment"] * 16 + r["ip"] + r["end"] - r["start"]]
+        if len(aliases) == 1:
+            r = aliases[0]
+            return r["start"] + linear - r["segment"] * 16 - r["ip"]
+        return None
+
+    def decode(self, site):
+        if site in self.cache:
+            return self.cache[site]
+        r = self.region(site)
+        if r is None:
+            return None
+        ip = r["ip"] + site - r["start"]
+        instruction = next(self.decoder.disasm(self.data[site:min(site + 15, r["end"])], ip, count=1), None)
+        self.cache[site] = instruction
+        return instruction
+
+    def near_target(self, site, ip):
+        r = self.region(site)
+        return self.offset(r["segment"], ip & self.mask)
+
+    def far_target(self, site, ins):
+        if self.flat:
+            return None, {"reason": "far transfer is outside the PE32 flat model"}
+        # ptr16:16 immediate only. Operand-size-prefixed far calls are unsupported.
+        if ins.size != 5 or self.data[site] not in (0x9a, 0xea):
+            return None, {"reason": "unsupported far transfer encoding"}
+        raw = int.from_bytes(self.data[site + 3:site + 5], "little")
+        ip = int.from_bytes(self.data[site + 1:site + 3], "little")
+        fixup = self.fixups.get(site + 3)
+        if not fixup:
+            return None, {"rawSegment": raw, "offset": ip, "reason": "no declared relocation/fixup"}
+        target = self.offset(fixup["segment"], ip)
+        if "target" in fixup:
+            target = integer(fixup["target"], 0, len(self.data) - 1, "canonical target")
+        return target, {"rawSegment": raw, "offset": ip, "resolvedSegment": fixup["segment"], "relocation": fixup}
+
+    def file_offset(self, va, width=1):
+        """Only loaded raw PE bytes; zero-fill and alignment padding are not source extents."""
+        metadata = self.config.get("peMetadata")
+        if not metadata:
+            return None
+        for section in metadata["sections"]:
+            if section["va"] <= va and va + width <= section["va"] + section["loadedRawSize"]:
+                return section["rawStart"] + va - section["va"]
+        return None