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

scientific_method_engine/x86/values.py

@@ -0,0 +1,123 @@
+"""Small bit-vector expressions; unknown values retain their producers."""
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class Value:
+    bits: int
+    term: tuple
+    sources: tuple = ()
+
+    def __post_init__(self):
+        pending, count = [self.term], 0
+        while pending:
+            term = pending.pop()
+            count += 1
+            if count > 1024:
+                raise ValueError("Symbolic expression complexity limit reached; narrow the query")
+            if isinstance(term, tuple):
+                pending.extend(item for item in term if isinstance(item, tuple))
+
+    @property
+    def number(self):
+        return self.term[1] if self.term[0] == "constant" else None
+
+    def report(self):
+        return {"bits": self.bits, "expression": self.term, "value": self.number,
+                "producers": list(self.sources)}
+
+
+def const(n, bits, site=None):
+    return Value(bits, ("constant", n % (1 << bits)), () if site is None else (site,))
+
+
+def unknown(name, bits, site=None):
+    return Value(bits, ("unknown", name), () if site is None else (site,))
+
+
+def sources(*values, site=None):
+    return tuple(sorted(set(x for v in values for x in v.sources) | ({site} if site is not None else set())))
+
+
+def extract(v, low, bits):
+    if v.number is not None:
+        return Value(bits, const(v.number >> low, bits).term, v.sources)
+    if low == 0 and bits == v.bits:
+        return v
+    if v.term[0] == "join":
+        parts = v.term[1]
+        if low % 8 == 0 and bits % 8 == 0:
+            selected = parts[low // 8:(low + bits) // 8]
+            return join([Value(8, term, v.sources) for term in selected])
+    if v.term[0] == "extract":
+        original, previous_low, _, original_bits = v.term[1:]
+        return Value(bits, ("extract", original, previous_low + low, bits, original_bits), v.sources)
+    return Value(bits, ("extract", v.term, low, bits, v.bits), v.sources)
+
+
+def join(parts):
+    bits = sum(v.bits for v in parts)
+    if len(parts) == 1:
+        # A single part is already its own value; wrapping it would nest on every partial register write.
+        return Value(bits, parts[0].term, sources(*parts))
+    if all(v.number is not None for v in parts):
+        n, shift = 0, 0
+        for v in parts:
+            n |= v.number << shift
+            shift += v.bits
+        return Value(bits, const(n, bits).term, sources(*parts))
+    if all(v.term[0] == "extract" and v.term[1] == parts[0].term[1]
+           and v.term[2] == i * 8 and v.bits == 8 for i, v in enumerate(parts)):
+        original_bits = parts[0].term[4]
+        term = parts[0].term[1] if bits == original_bits else ("extract", parts[0].term[1], 0, bits, original_bits)
+        return Value(bits, term, sources(*parts))
+    return Value(bits, ("join", tuple(v.term for v in parts)), sources(*parts))
+
+
+def resize(v, bits, signed=False):
+    if bits <= v.bits:
+        return extract(v, 0, bits)
+    if v.number is not None:
+        n = v.number
+        if signed and n & (1 << (v.bits - 1)):
+            n -= 1 << v.bits
+        return Value(bits, const(n, bits).term, v.sources)
+    return Value(bits, ("signExtend" if signed else "zeroExtend", v.term, v.bits, bits), v.sources)
+
+
+def op(name, a, b, site=None):
+    bits = a.bits
+    if b.bits != bits:
+        b = resize(b, bits)
+    origin = sources(a, b, site=site)
+    if a.number is not None and b.number is not None:
+        x, y = a.number, b.number
+        if name == "add": n = x + y
+        elif name == "sub": n = x - y
+        elif name == "and": n = x & y
+        elif name == "or": n = x | y
+        elif name == "xor": n = x ^ y
+        elif name == "shl": n = x << (y & 31)
+        elif name == "shr": n = x >> (y & 31)
+        elif name == "sar": n = (x - (1 << bits) if x & (1 << (bits - 1)) else x) >> (y & 31)
+        elif name == "mul": n = x * y
+        else: raise ValueError("Unsupported expression operation: " + name)
+        return Value(bits, const(n, bits).term, origin)
+    if name in ("sub", "xor") and a.term == b.term:
+        return Value(bits, const(0, bits).term, origin)
+    if name in ("add", "sub") and b.number is not None:
+        delta = b.number if name == "add" else -b.number
+        base = a.term
+        if base[0] == "offset":
+            delta += base[2]
+            base = base[1]
+        delta %= 1 << bits
+        return Value(bits, base if delta == 0 else ("offset", base, delta), origin)
+    return Value(bits, (name, a.term, b.term), origin)
+
+
+def address_parts(v):
+    if v.number is not None:
+        return ("absolute",), v.number
+    if v.term[0] == "offset":
+        return v.term[1], v.term[2]
+    return v.term, 0

scientific_method_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.5
+Name: scientific-method-engine
+Version: 0.1.0
+Summary: Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code.
+Project-URL: Source, https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine
+Author: kibertoad
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: capstone==5.0.7
+Description-Content-Type: text/markdown
+
+# scientific-method-engine
+
+Bounded instruction-derived x86 evidence reports for segmented 16-bit MZ/FBOV code and
+PE32/i386 code. The engine decodes instructions with Capstone, follows bounded paths and emits
+`bounded-x86-v1` JSON. It never runs the original program.
+
+```sh
+uv add --group research scientific-method-engine     # or: pip install scientific-method-engine
+```
+
+For original MZ/FBOV executables, run reports through
+[`@scientific-method/executable-reader`](https://www.npmjs.com/package/@scientific-method/executable-reader). The
+reader derives relocation, fixup and trampoline data from the hash-checked source and pipes a
+prepared config to this engine. Running the engine directly trusts whatever relocation data the
+config supplies, so use it directly only for synthetic inputs, PE32 sources and checked mappings:
+
+```sh
+scientific-method-engine trace analysis/query.json
+python -m scientific_method_engine trace analysis/query.json
+```
+
+The package also carries the shared Ghidra headless scripts. `scientific-method-engine
+ghidra-scripts` prints their directory, for Ghidra's `-scriptPath`:
+
+```powershell
+& "$env:GHIDRA_HOME/support/analyzeHeadless.bat" $project $name -process GAME.EXE -noanalysis `
+  -scriptPath (scientific-method-engine ghidra-scripts) -postScript ReportReferences.java 0x1234
+```
+
+Addresses are Ghidra addresses (`0x00401000`, or `1028:d820` for segmented programs). Report scripts
+print to the analyzer log and cap their output. The scripts compile against Ghidra 12.1.
+
+Reading code and data:
+
+| Script | Arguments | Prints |
+|---|---|---|
+| `ReportInstructionContext` | one or more instruction addresses | a bounded instruction window around each |
+| `ReportInstructionWindow` | address, instruction count | instructions from the address onward |
+| `ReportDataBytes` | address, byte count (1..256) | the bytes at the address |
+| `ReportFunctionSummary` | one or more addresses | focused decompiler output of each containing function |
+| `ReportDecompileWindow` | address, first line (1-based), line count | a window of one function's decompilation |
+| `ReportDecompileMatches` | address, one or more literal text patterns | decompilation lines around each match |
+| `ReportMemoryBlocks` | nothing, `page <start> <count>`, or `name <exact-name>` | memory block indexes, names, ranges and sizes, never bytes |
+| `ReportFilePatternInMemory` | file offset (hex), optional pattern length (default 8) | where the bytes at that file offset occur in loaded memory |
+| `ReportMemoryBlockForFileOffset` | one or more file offsets (hex) | the memory block and instructions where each offset's bytes are loaded |
+
+Finding references and calls:
+
+| Script | Arguments | Prints |
+|---|---|---|
+| `ReportReferences` | one or more addresses | references to each, with the referring instruction and function |
+| `ReportStringReferences` | one or more literal string fragments | strings containing a fragment and their references |
+| `ReportSymbolReferences` | one or more symbol-name fragments | matching symbols and their references |
+| `ReportScalarConstants` | one or more scalar values | instructions using any of them, unsigned or signed |
+| `ReportFunctionScalarConstants` | function address, one or more scalar values | instructions inside one function using any of them, compared unsigned |
+| `ReportCallArguments` | callee address | the three nearest pushed arguments at every direct call |
+| `ReportCallSitesWithScalars` | callee address, one or more scalar values | calls whose argument setup contains a requested value |
+| `ReportConstantFirstArgumentCalls` | callee address, constant | cdecl calls whose first argument is the constant |
+| `ReportFirstArgumentCallSummary` | callee address | the literal first argument of every call, and calls without one |
+| `ReportCallsToRange` | start address, end address (inclusive) | calls and jumps whose target lies in the range |
+| `ReportCallPaths` | start function, target function, maximum depth | direct-call paths between the two |
+| `ReportRandomnessCandidates` | none | references to C runtime and Windows random and timing functions |
+
+Exporting for comparison (each writes one file and refuses to overwrite where noted):
+
+| Script | Arguments | Writes |
+|---|---|---|
+| `ExportBoundedFlow` | entry, instruction limit (1..10000), output path under `analysis/original/` | instruction metadata of one bounded flow as JSON |
+| `ExportFunctionInventory` | output TSV path (must not exist) | every function's start and body size |
+| `ExportFunctionFingerprints` | output TSV path | per-function and per-instruction fingerprints with addresses normalized, for matching functions across versions |
+
+Repairing the analysis (these change the Ghidra program, so run them before reports and keep the
+argument lists with the evidence that justifies them):
+
+| Script | Arguments | Changes |
+|---|---|---|
+| `CreateFunctions` | one or more entry addresses | creates functions at indirect-call targets Ghidra missed |
+| `RecoverCitedFunctions` | file of 8-digit hex addresses, optional CSV column | disassembles and creates a function at each address inside executable memory |
+| `ClearNoReturnFunctions` | one or more addresses | clears a wrong no-return flag on each containing function |
+| `RepairReturningCallers` | callee entry, caller entry, verified call addresses | checks each call targets the callee from inside the caller, clears the callee's no-return flag and the calls' flow overrides, disassembles each continuation and recomputes the caller's body |
+| `MergeFallThroughFragment` | parent entry, fragment entry | merges an orphan fragment reached by the parent's fall-through into the parent |
+
+Restoration tools that build report configs can import the parsers directly, for example to
+derive a PE32 source's executable sections:
+
+```python
+from scientific_method_engine.x86.pe import pe32
+
+sections = [s for s in pe32(data)["sections"] if s["executable"]]
+```
+
+`scientific_method_engine.x86.pe.pe32` and `scientific_method_engine.x86.image.read_source` are
+supported imports and change only in a major release. Other modules are internal.
+
+Commands, inputs, limits and acceptance rules are in
+[the bounded evidence reporter guide](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md).
+The reader and engine check that they speak the same prepared-config protocol and refuse to run
+otherwise.

scientific_method_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,45 @@
+scientific_method_engine/__init__.py,sha256=8Kee68O-FZ_rmBXLQEZoGFgNVvHdhFjs-QVYcAFJMlk,274
+scientific_method_engine/__main__.py,sha256=yQP0sf-rkTO-3MOotv4blvukvNGwbJFz10hQhMsxcJM,28
+scientific_method_engine/cli.py,sha256=h61KXKOdSkkXce8r-XzRkQFacoibhjsP0qI4otFR_AU,3225
+scientific_method_engine/ghidra/ClearNoReturnFunctions.java,sha256=K3IaHtlz2DyvAqo1eHR9uioM3qJVbC1FiyUMMm1OLMU,817
+scientific_method_engine/ghidra/CreateFunctions.java,sha256=xQ0rHDxPRaAEpOyL083946RPgVZCdBtyWgueqYyzOvk,990
+scientific_method_engine/ghidra/ExportBoundedFlow.java,sha256=l4cyCnwlUYCy7vZd7ZvI2ijVDI1w5UCNSHajXlGhEjY,3868
+scientific_method_engine/ghidra/ExportFunctionFingerprints.java,sha256=sRhFDbHzqHjcOiQ9uJtGc-9HHsp-dmJ_qxWnABfIeoQ,6163
+scientific_method_engine/ghidra/ExportFunctionInventory.java,sha256=y5dIGUzA5AKMMqr8GVNojyJPUMXsYOlUO3_ljSKDoLU,2092
+scientific_method_engine/ghidra/MergeFallThroughFragment.java,sha256=XXJ2lxkrfrJQUJqYXRgXtwBjyIm4ScpXoaoqz3dkfrY,3710
+scientific_method_engine/ghidra/RecoverCitedFunctions.java,sha256=yn45v-aZIs25etm2kq3NP_HgPaTGYhWIDnDvydqjpaE,4008
+scientific_method_engine/ghidra/RepairReturningCallers.java,sha256=CD7eiCHaQKXNh6fErLgjokG3hjzH5_0FyoeozmdOjmo,4038
+scientific_method_engine/ghidra/ReportCallArguments.java,sha256=041GllfLHnpf_C2tu00lhJ7wMkHYSCjR1W3FitPJToU,2728
+scientific_method_engine/ghidra/ReportCallPaths.java,sha256=lyAQ23bV7c0srAmZ4fm3tzOOBQ02_2uTQdjiFuuY3Ok,4418
+scientific_method_engine/ghidra/ReportCallSitesWithScalars.java,sha256=77l3gylbz5D_JY3EfW9AbAcyXH_YADisBBrxlyym2-g,4237
+scientific_method_engine/ghidra/ReportCallsToRange.java,sha256=Dx2zuvZZCpUAWPq5ECLAtSToZFpJRQzMoxjVMJIRvNE,2672
+scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java,sha256=vrg9UU2tPAV-pP0EaNKF56szTvkwY3jDcy-1VtP6TLk,2466
+scientific_method_engine/ghidra/ReportDataBytes.java,sha256=PhspNsYKKKQL-Z9wPQUM2T1-AjaJYN5c6yhMl6XHo94,1349
+scientific_method_engine/ghidra/ReportDecompileMatches.java,sha256=Rf7eDZ7SXaToB-zqGfXZo2_U1zoVk2aTvVcM2YJNj1g,2784
+scientific_method_engine/ghidra/ReportDecompileWindow.java,sha256=5KHBjg07AUEyc4hkM5yiwuemqANc5dtl3MLV6OSnygk,2439
+scientific_method_engine/ghidra/ReportFilePatternInMemory.java,sha256=YKxrG7ltjlls1Gk6cHTUpsq_HwUElXKbmPo2aRPuB9Q,4295
+scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java,sha256=sS7vKGsYhdbUPWhFTtOBpk9kALSIlB9yyrR0mzVBe14,2629
+scientific_method_engine/ghidra/ReportFunctionScalarConstants.java,sha256=7owEme1wSYRiAsiwj7DQVWEix4xgz_kKjSbuAFLv1H4,2282
+scientific_method_engine/ghidra/ReportFunctionSummary.java,sha256=sVmHZ9oLJBqXjJqI8jr5WujssI9We4eFo3-AQEFFRUs,2701
+scientific_method_engine/ghidra/ReportInstructionContext.java,sha256=d3OiBGzEY0RgzqDhchDWG4XUlw2zBp6y7Dv35evjLPs,2515
+scientific_method_engine/ghidra/ReportInstructionWindow.java,sha256=36eIlhxsd6NWk83r5TSgRpNIw5zknE7eBha-574nLtw,1296
+scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java,sha256=_ZRBp1aJGJtmBn8P6zD_uUDfMwpCQEl5aeYo31cEkxw,4430
+scientific_method_engine/ghidra/ReportMemoryBlocks.java,sha256=vopnvVO6fDRJNce3m995cX0TMu14L0Ttt3SgP6hjD5Q,2842
+scientific_method_engine/ghidra/ReportRandomnessCandidates.java,sha256=IkY4U8W7AyM9lWS4ACdN2swaSnkUGaQKzlooxnE8y1U,3117
+scientific_method_engine/ghidra/ReportReferences.java,sha256=wOAJDXla5F0kSo5AQkLa6uHsAb-JrwvWe9wAi19ct2I,1947
+scientific_method_engine/ghidra/ReportScalarConstants.java,sha256=hjMqf5uxzpcuG-0p1EKQYj8MIPNnZhuQYcy523RFHIs,2520
+scientific_method_engine/ghidra/ReportStringReferences.java,sha256=PIGT6OejS_Wuf7BdOAL7FaDmehsH1N0Gx9KEO3QYZgI,4684
+scientific_method_engine/ghidra/ReportSymbolReferences.java,sha256=wFsOQ-CYKOH1UFS96vRWb0poKTZtCiqKQXA8di1S8NM,2929
+scientific_method_engine/x86/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scientific_method_engine/x86/dispatch.py,sha256=APeUDstQqFEeVurVtByDPb9N_ITD1CkAmmUOYyk8CYQ,3207
+scientific_method_engine/x86/image.py,sha256=TV5FeVlsXi5j-AN_O-q6PFAj69P1V78Evo0piINBP6Q,8920
+scientific_method_engine/x86/machine.py,sha256=kIbqwFILLyRW_LpEFxqkIFQfKZBs8tAlyNh8yQj40iA,34914
+scientific_method_engine/x86/pe.py,sha256=NjidW638sIsmgaQONYLJOxOxDMCuIG97jxWDnIk0BCM,5494
+scientific_method_engine/x86/reports.py,sha256=Jy1xsLe_j-x5VzBEnl-aZJ8GIjwUPJ2GNgU1X9t33UY,79926
+scientific_method_engine/x86/trace.py,sha256=KlFl4iyHg5u-yh4JdOjjB5ZA0XV-dCQYRY-OIKymxl8,33097
+scientific_method_engine/x86/values.py,sha256=Xg5eqn7Vl_7ObF9DfachLJEUg4q1WVU5RnVoMMgIaoQ,4651
+scientific_method_engine-0.1.0.dist-info/METADATA,sha256=VgTTmuk-J2zId48ivIrY9axmSXtiU0x0Zlw7J20T7VA,6890
+scientific_method_engine-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+scientific_method_engine-0.1.0.dist-info/entry_points.txt,sha256=KHEiOeVElyBYmlHv1eyUaFDwB2QtzonGotyoexDMe2g,78
+scientific_method_engine-0.1.0.dist-info/licenses/LICENSE,sha256=9vHEhTyO3xblGldAc8euUUpxX-jF_M6k6OQ9dPlu7WU,1067
+scientific_method_engine-0.1.0.dist-info/RECORD,,

scientific_method_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

scientific_method_engine-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+scientific-method-engine = scientific_method_engine.cli:run

scientific_method_engine-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.