scientific-method-engine 6.1.1__tar.gz → 6.2.0__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.1 → scientific_method_engine-6.2.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/argument_frames.py +27 -2
  4. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/tests/test_x86.py +43 -1
  5. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/.gitignore +0 -0
  6. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/LICENSE +0 -0
  7. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/README.md +0 -0
  8. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/__init__.py +0 -0
  9. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/__main__.py +0 -0
  10. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/cli.py +0 -0
  11. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  12. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  13. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  14. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  15. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  16. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  17. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  18. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  19. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  20. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  21. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  22. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  23. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  24. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  25. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  26. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  27. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  28. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  29. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  30. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  31. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  32. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  33. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  34. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  35. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  36. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  37. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  38. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  39. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  40. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  41. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  42. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  43. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  44. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  45. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/image.py +0 -0
  46. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/loops.py +0 -0
  47. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/machine.py +0 -0
  48. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  49. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  50. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  51. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/pe.py +0 -0
  52. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/relational.py +0 -0
  53. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/reports.py +0 -0
  54. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  55. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/trace.py +0 -0
  56. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/src/scientific_method_engine/x86/values.py +0 -0
  57. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/tests/oracle.py +0 -0
  58. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/tests/test_continuation_budget.py +0 -0
  59. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/tests/test_dispatch.py +0 -0
  60. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/tests/test_effect_order.py +0 -0
  61. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/tests/test_loops.py +0 -0
  62. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/tests/test_memory_scopes.py +0 -0
  63. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/tests/test_nested_frame_request.py +0 -0
  64. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/tests/test_oracle.py +0 -0
  65. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/tests/test_pe.py +0 -0
  66. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/tests/test_relational_controls.py +0 -0
  67. {scientific_method_engine-6.1.1 → scientific_method_engine-6.2.0}/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.1
3
+ Version: 6.2.0
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.1"
8
+ version = "6.2.0"
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"
@@ -24,6 +24,11 @@ def stack_cleanup(ins):
24
24
  return amount if 0 < amount < 1 << (bits - 1) else None
25
25
 
26
26
 
27
+ def _overlap(a, b):
28
+ """Whether the reads or intervals `a` and `b`, each starting (offset, width, ...), share a byte."""
29
+ return a[0] < b[0] + b[1] and b[0] < a[0] + a[1]
30
+
31
+
27
32
  def _covered(event, segment, base, start, width, modulus):
28
33
  """The frame offsets below `width` that a write event stored, counted from stack byte `start`."""
29
34
  interval = event.get("interval")
@@ -171,9 +176,16 @@ def _frame(image, events, index, models):
171
176
  "offsetFromEntrySP": event["argument"]["offsetFromEntrySP"], "bytes": hits})
172
177
 
173
178
  intervals = sorted({(g["offset"], g["width"]) for g in groupings})
174
- competing = [[list(a), list(b)] for i, a in enumerate(intervals) for b in intervals[i + 1:] if a[0] < b[0] + b[1] and b[0] < a[0] + a[1]]
179
+ competing = [[list(a), list(b)] for i, a in enumerate(intervals) for b in intervals[i + 1:] if _overlap(a, b)]
175
180
  if competing:
176
181
  open_reasons.append("reads of different widths overlap")
182
+ # A far-pointer load and a plain dword of the same bytes do not settle one grouping either.
183
+ grouped_as = {}
184
+ for g in groupings:
185
+ grouped_as.setdefault((g["offset"], g["width"]), set()).add(g["grouping"])
186
+ for (offset, read_width), kinds in sorted(grouped_as.items()):
187
+ if len(kinds) > 1:
188
+ open_reasons.append(f"the {read_width} bytes at {offset} are read with more than one grouping")
177
189
  for slot in slots:
178
190
  if slot["writerSite"] is not None and not slot["consumedBy"]:
179
191
  open_reasons.append(f"the slot at {slot['offset']} was not read by the callee on this path")
@@ -190,7 +202,9 @@ def argument_frames(report, image):
190
202
 
191
203
  A path gets one map per traced call, from caller-written slots to callee reads. A site's
192
204
  groupings agree only when every path that traced a call there settled on the same read widths
193
- and groupings.
205
+ and groupings. Separately, a site's widths are consistent when its paths made at least one read
206
+ and no two reads on any of them cover the same byte with a different offset, width or grouping;
207
+ a path that skipped a read leaves the site consistent but not agreed.
194
208
  """
195
209
  sites = {}
196
210
  for path_index, path in enumerate(report["paths"]):
@@ -203,10 +217,21 @@ def argument_frames(report, image):
203
217
  for site, rows in sorted(sites.items()):
204
218
  # A set holds each read's grouping too: a far-pointer load and a plain dword over the same bytes disagree.
205
219
  widths = sorted({tuple(sorted({(g["offset"], g["width"], g["grouping"]) for g in f["groupings"]})) for _, f in rows})
220
+ read_on = {}
221
+ for i, f in rows:
222
+ for g in f["groupings"]:
223
+ read_on.setdefault((g["offset"], g["width"], g["grouping"]), set()).add(i)
224
+ reads = sorted(read_on)
225
+ # Distinct reads that share a byte conflict: different intervals, or one interval grouped two ways.
226
+ conflicting = [[{"offset": o, "width": w, "grouping": k} for o, w, k in (a, b)]
227
+ for n, a in enumerate(reads) for b in reads[n + 1:] if _overlap(a, b)]
206
228
  report["argumentFrameSites"].append({
207
229
  "callSite": site, "paths": sorted({i for i, _ in rows}), "frames": len(rows),
208
230
  "unsettledPaths": sorted({i for i, f in rows if not f["settledOnThisPath"]}),
209
231
  "readWidthSets": [[{"offset": o, "width": w, "grouping": k} for o, w, k in group] for group in widths],
232
+ "readWidths": [{"offset": o, "width": w, "grouping": k, "paths": sorted(read_on[(o, w, k)])} for o, w, k in reads],
233
+ "conflictingWidths": conflicting,
234
+ "widthsConsistent": bool(reads) and not conflicting,
210
235
  "agreed": len(widths) == 1 and all(f["settledOnThisPath"] for _, f in rows),
211
236
  "interpretation": "read widths per traced path; paths that never reached this call are not represented"})
212
237
  return report
@@ -421,7 +421,7 @@ class ArgumentFrameTests(unittest.TestCase):
421
421
  self.assertEqual(r["argumentFrameSites"][0]["readWidthSets"], [[{"offset": 0, "width": 2, "grouping": "consumed width only"},
422
422
  {"offset": 2, "width": 4, "grouping": "far-pointer"},
423
423
  {"offset": 6, "width": 2, "grouping": "consumed width only"}]])
424
- self.assertTrue(all(site["agreed"] for site in r["argumentFrameSites"]))
424
+ self.assertTrue(all(site["agreed"] and site["widthsConsistent"] for site in r["argumentFrameSites"]))
425
425
 
426
426
  def test_the_report_keeps_the_writes_its_slots_cite(self):
427
427
  c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3").label("callee").emit("55 89 e5 8b 46 04 8b 46 06 5d c3")
@@ -586,6 +586,25 @@ class ArgumentFrameTests(unittest.TestCase):
586
586
  [{"offset": 0, "width": 4, "grouping": "far-pointer"}]])
587
587
  self.assertFalse(site["agreed"])
588
588
  self.assertEqual(len(site["unsettledPaths"]), 1)
589
+ self.assertFalse(site["widthsConsistent"])
590
+ self.assertEqual(site["conflictingWidths"], [[{"offset": 0, "width": 2, "grouping": "consumed width only"},
591
+ {"offset": 0, "width": 4, "grouping": "far-pointer"}]])
592
+
593
+ def test_a_path_that_skips_a_read_leaves_the_site_consistent_but_not_agreed(self):
594
+ # The callee always reads the first word and reads the second only when SI is nonzero.
595
+ c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3")
596
+ c.label("callee").emit("55 89 e5 8b 46 04 85 f6").branch("74", "skip").emit("8b 5e 06").label("skip").emit("5d c3")
597
+ r, frames = self.frames(c)
598
+ self.assertEqual(len(frames), 2)
599
+ site = r["argumentFrameSites"][0]
600
+ self.assertFalse(site["agreed"])
601
+ bypass = next(i for i, path in enumerate(r["paths"]) if not path["argumentFrames"][0]["settledOnThisPath"])
602
+ self.assertEqual(site["unsettledPaths"], [bypass])
603
+ self.assertIn("the slot at 2 was not read by the callee on this path", r["paths"][bypass]["argumentFrames"][0]["openReasons"])
604
+ self.assertTrue(site["widthsConsistent"])
605
+ self.assertEqual(site["conflictingWidths"], [])
606
+ self.assertEqual(site["readWidths"], [{"offset": 0, "width": 2, "grouping": "consumed width only", "paths": [0, 1]},
607
+ {"offset": 2, "width": 2, "grouping": "consumed width only", "paths": [1 - bypass]}])
589
608
 
590
609
  def test_paths_that_group_the_same_bytes_differently_keep_the_site_open(self):
591
610
  # Both paths read four bytes at offset 0: one as a far pointer with LES, one as a 32-bit dword.
@@ -599,6 +618,29 @@ class ArgumentFrameTests(unittest.TestCase):
599
618
  self.assertEqual(site["readWidthSets"], [[{"offset": 0, "width": 4, "grouping": "consumed width only"}],
600
619
  [{"offset": 0, "width": 4, "grouping": "far-pointer"}]])
601
620
  self.assertFalse(site["agreed"])
621
+ self.assertFalse(site["widthsConsistent"])
622
+ self.assertEqual(len(site["conflictingWidths"]), 1)
623
+
624
+ def test_one_path_that_groups_the_same_bytes_two_ways_stays_open(self):
625
+ # The callee loads the first four bytes with LES and then reads them again as a 32-bit dword.
626
+ c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3")
627
+ c.label("callee").emit("55 89 e5 c4 5e 04 66 8b 46 04 5d c3")
628
+ r, frames = self.frames(c)
629
+ self.assertEqual(frames[0]["competingWidths"], [])
630
+ self.assertFalse(frames[0]["settledOnThisPath"])
631
+ self.assertIn("the 4 bytes at 0 are read with more than one grouping", frames[0]["openReasons"])
632
+ site = r["argumentFrameSites"][0]
633
+ self.assertFalse(site["agreed"])
634
+ self.assertFalse(site["widthsConsistent"])
635
+
636
+ def test_a_site_whose_callee_reads_nothing_is_not_consistent(self):
637
+ # A pushed word the callee never reads leaves no read to be consistent with.
638
+ c = Code().emit("6a 01").branch("e8", "callee").emit("83 c4 02 c3").label("callee").emit("c3")
639
+ r, _ = self.frames(c)
640
+ site = r["argumentFrameSites"][0]
641
+ self.assertEqual(site["readWidths"], [])
642
+ self.assertFalse(site["widthsConsistent"])
643
+ self.assertFalse(site["agreed"])
602
644
 
603
645
  def test_a_write_through_another_address_drops_the_slot_writer(self):
604
646
  # A DS write between the push and the call may alias the symbolic stack, so the pushed word