scientific-method-engine 6.1.0__tar.gz → 6.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/PKG-INFO +1 -1
  2. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/pyproject.toml +1 -1
  3. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/argument_frames.py +7 -6
  4. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/machine.py +7 -2
  5. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/tests/test_relational_controls.py +31 -0
  6. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/tests/test_x86.py +24 -0
  7. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/.gitignore +0 -0
  8. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/LICENSE +0 -0
  9. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/README.md +0 -0
  10. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/__init__.py +0 -0
  11. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/__main__.py +0 -0
  12. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/cli.py +0 -0
  13. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  14. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  15. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  16. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  17. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  18. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  19. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  20. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  21. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  22. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  23. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  24. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  25. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  26. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  27. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  28. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  29. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  30. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  31. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  32. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  33. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  34. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  35. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  36. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  37. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  38. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  39. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  40. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  41. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  42. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  43. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  44. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/__init__.py +0 -0
  45. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/dispatch.py +0 -0
  46. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/effect_order.py +0 -0
  47. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/image.py +0 -0
  48. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/loops.py +0 -0
  49. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  50. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/pcode.py +0 -0
  51. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  52. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/pe.py +0 -0
  53. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/relational.py +0 -0
  54. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/reports.py +0 -0
  55. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/result_flow.py +0 -0
  56. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/trace.py +0 -0
  57. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/src/scientific_method_engine/x86/values.py +0 -0
  58. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/tests/oracle.py +0 -0
  59. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/tests/test_continuation_budget.py +0 -0
  60. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/tests/test_dispatch.py +0 -0
  61. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/tests/test_effect_order.py +0 -0
  62. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/tests/test_loops.py +0 -0
  63. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/tests/test_memory_scopes.py +0 -0
  64. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/tests/test_nested_frame_request.py +0 -0
  65. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/tests/test_oracle.py +0 -0
  66. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/tests/test_pe.py +0 -0
  67. {scientific_method_engine-6.1.0 → scientific_method_engine-6.1.1}/tests/test_table_continuations.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 6.1.0
3
+ Version: 6.1.1
4
4
  Summary: Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code.
5
5
  Project-URL: Source, https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine
6
6
  Author: kibertoad
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  name = "scientific-method-engine"
7
7
  # The release workflow writes the published version from the package's release tag.
8
- version = "6.1.0"
8
+ version = "6.1.1"
9
9
  description = "Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code."
10
10
  readme = "README.md"
11
11
  requires-python = ">=3.12"
@@ -39,19 +39,20 @@ def _writers(events, before, segment, base, start, width, modulus, image, models
39
39
 
40
40
  A modeled call drops every byte outside its `preservesMemory` scopes. Scopes name linear bytes,
41
41
  so they keep only frame bytes of a linear stack; the search goes on past the call for those.
42
- A write through another segment or base drops every frame byte it may alias, by the same rule
43
- the machine applies when it stores.
42
+ A write through another segment or base may have stored every frame byte it may alias, whether
43
+ or not it dropped a cached byte. The rule is the one the machine's ``unwritten`` applies, so a
44
+ slot and a callee read of it that runs before any callee write through another segment or base
45
+ name the same write.
44
46
  """
45
47
  writers, invalidated = {}, {}
48
+ keys = [(segment, base, (start + at) % modulus if modulus else start + at) for at in range(width)]
46
49
  for j in range(before - 1, -1, -1):
47
50
  event = events[j]
48
51
  interval = event.get("interval")
49
- if (event["kind"] == "write" and (event.get("uncertainAliasesInvalidated") or event.get("uncertainScopeBytesInvalidated")) and interval
50
- and (interval["segment"], interval["base"]) != (segment, base)):
52
+ if event["kind"] == "write" and interval and (interval["segment"], interval["base"]) != (segment, base):
51
53
  written = written_domain(interval["segment"], interval["base"], interval["start"],
52
54
  interval["end"] - interval["start"], image.bits, image.flat)
53
- for at in range(width):
54
- key = (segment, base, (start + at) % modulus if modulus else start + at)
55
+ for at, key in enumerate(keys):
55
56
  if at not in writers and at not in invalidated and may_alias(key, written, image.bits, image.flat):
56
57
  invalidated[at] = f"memory possibly overwritten through another address by the write at {event['site']}"
57
58
  if event["kind"] == "call-return" and event.get("unknownMemoryEffects"):
@@ -338,14 +338,19 @@ class State:
338
338
  continue
339
339
  for key in list(members):
340
340
  if may_alias(key, written, self.bits, self.flat):
341
+ # A byte with a value loses it. A scope byte kept without one loses no value,
342
+ # and the write may have stored it.
341
343
  if key in self.memory:
342
344
  dropped_values += 1
343
- elif key in self.unread_memory:
345
+ cause = "dropped by a possibly aliasing write"
346
+ else:
347
+ # Group members without a value are exactly the scope's unread bytes.
344
348
  dropped_unread += 1
349
+ cause = "possibly written by an aliasing write"
345
350
  self.write_log.append((key, self.memory.pop(key, None)))
346
351
  self.unread_memory.pop(key, None)
347
352
  self.memory_writers.pop(key, None)
348
- self.lost_memory[key] = {"cause": "dropped by a possibly aliasing write", "order": len(self.events)}
353
+ self.lost_memory[key] = {"cause": cause, "order": len(self.events)}
349
354
  members.discard(key)
350
355
  if not members:
351
356
  del self.memory_groups[group]
@@ -200,6 +200,37 @@ class LastWriterTests(unittest.TestCase):
200
200
  store = occurrence["order"] - 1
201
201
  self.assertEqual(occurrence["bytes"][0]["unwritten"], {"cause": "dropped by a possibly aliasing write", "order": store})
202
202
 
203
+ def test_an_aliasing_write_drops_a_kept_value_and_may_write_an_unread_scope_byte(self):
204
+ # The model keeps [22h] with its value and [40h] without one. The store through DS:SI (SI
205
+ # unknown) after the call may alias both: [22h] loses its value, while [40h] had none to lose.
206
+ c = (Code().label("assign").emit("c7 06 22 00 05 00").label("service").branch("e8", "external")
207
+ .label("store").emit("89 04").label("read").emit("a1 22 00").label("other").emit("a1 40 00 c3")
208
+ .label("external").emit("c3"))
209
+ model = [{"site": c.labels["service"], "preserves": ["ds", "ebx"], "evidence": "synthetic service",
210
+ "preservesMemory": [{"segment": "ds", "base": "bx", "bytes": 2, "evidence": "synthetic kept slot"},
211
+ {"segment": "ds", "base": "bx", "displacement": 0x1e, "bytes": 2, "evidence": "synthetic kept slot"}],
212
+ "cases": [{}]}]
213
+ regs = {**FRAME, "bx": 0x22}
214
+ controls = [control("slot", "lastWriter", at={"site": c.labels["read"], "event": "read"}, writers=[c.labels["assign"]]),
215
+ control("uncached", "lastWriter", at={"site": c.labels["other"], "event": "read"}, writers=["entryState"]),
216
+ control("producer", "origin", at={"site": c.labels["other"], "event": "read"}, value={"field": "value"},
217
+ expect={"producers": {"exclude": [c.labels["store"]]}})]
218
+ r = run(c, controls, registers=regs, callModels=model)
219
+ events = r["paths"][0]["events"]
220
+ store = next(e for e in events if e["kind"] == "write" and e["site"] == c.labels["store"])
221
+ self.assertEqual((store["uncertainAliasesInvalidated"], store["uncertainScopeBytesInvalidated"]), (2, 2))
222
+ kept = next(e for e in events if e["kind"] == "read" and e["site"] == c.labels["read"])
223
+ self.assertEqual([b["unwritten"] for b in kept["byteProducers"]],
224
+ [{"cause": "dropped by a possibly aliasing write", "order": store["order"]}] * 2)
225
+ unread = next(e for e in events if e["kind"] == "read" and e["site"] == c.labels["other"])
226
+ self.assertEqual([b["unwritten"] for b in unread["byteProducers"]],
227
+ [{"cause": "possibly written by an aliasing write", "order": store["order"]}] * 2)
228
+ # Neither byte has a known writer, and the store stays a possible producer of the unread one.
229
+ for name in ("slot", "uncached", "producer"):
230
+ self.assertEqual(verdict(r, name)["verdict"], "undecided", name)
231
+ self.assertEqual(verdict(r, "uncached")["paths"][0]["occurrences"][0]["bytes"][0]["unwritten"]["cause"],
232
+ "possibly written by an aliasing write")
233
+
203
234
  def test_a_preserved_scope_keeps_the_write_before_the_service(self):
204
235
  c = (Code().label("assign").emit("c7 06 22 00 05 00").label("service").branch("e8", "external")
205
236
  .label("read").emit("a1 22 00").label("other").emit("a1 40 00 c3").label("external").emit("c3"))
@@ -534,6 +534,30 @@ class ArgumentFrameTests(unittest.TestCase):
534
534
  self.assertEqual([(s["offset"], s["width"], s["writerSite"], s.get("reason")) for s in frames[0]["slots"]],
535
535
  [(0, 2, None, "memory possibly overwritten through another address by the write at 6")])
536
536
 
537
+ def test_a_write_that_drops_nothing_still_explains_the_slot(self):
538
+ # sub sp,2 reserves a slot nothing writes. The DS:[BX] store (DS and BX unknown) runs when
539
+ # nothing is cached, so it drops nothing, but it may still have stored the slot.
540
+ c = Code().emit("83 ec 02 88 07").branch("e8", "callee").emit("83 c4 02 c3")
541
+ c.label("callee").emit("55 89 e5 8b 46 04 5d c3")
542
+ frames = self.frames(c)[1]
543
+ traced = report(c, "trace")
544
+ store = next(e for e in events(traced, "write") if e["site"] == 3)
545
+ self.assertEqual((store["uncertainAliasesInvalidated"], store["uncertainScopeBytesInvalidated"]), (0, 0))
546
+ self.assertEqual([(s["offset"], s["width"], s["writerSite"], s.get("reason")) for s in frames[0]["slots"]],
547
+ [(0, 2, None, "memory possibly overwritten through another address by the write at 3")])
548
+ self.assertFalse(frames[0]["settledOnThisPath"])
549
+ # The callee's read of the same bytes names the same store.
550
+ read = next(e for e in events(traced, "read") if e.get("argument"))
551
+ self.assertEqual([b["unwritten"] for b in read["byteProducers"]],
552
+ [{"cause": "possibly written by an aliasing write", "order": store["order"]}] * 2)
553
+ # On a concrete stack the store cannot reach, both reports say no write on this path.
554
+ regs = {"ss": 0x2000, "sp": 0x100, "ds": 0x3000}
555
+ frames = self.frames(c, registers=regs)[1]
556
+ self.assertEqual([(s["offset"], s["width"], s["writerSite"], s.get("reason")) for s in frames[0]["slots"]],
557
+ [(0, 2, None, "no write on this path")])
558
+ read = next(e for e in events(report(c, "trace", registers=regs), "read") if e.get("argument"))
559
+ self.assertEqual([b["unwritten"]["cause"] for b in read["byteProducers"]], ["no write on this path"] * 2)
560
+
537
561
  def test_a_callee_that_stops_leaves_its_frame_open(self):
538
562
  c = Code().emit("6a 01").branch("e8", "callee").emit("83 c4 02 c3").label("callee").emit("55 89 e5 8b 46 04 ff d3")
539
563
  r, frames = self.frames(c)