scientific-method-engine 10.0.0__tar.gz → 10.1.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 (72) hide show
  1. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/relational.py +51 -3
  4. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_relational_controls.py +89 -0
  5. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/.gitignore +0 -0
  6. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/LICENSE +0 -0
  7. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/README.md +0 -0
  8. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/__init__.py +0 -0
  9. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/__main__.py +0 -0
  10. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/cli.py +0 -0
  11. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  12. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  13. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  14. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  15. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  16. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  17. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  18. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  19. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  20. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  21. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  22. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  23. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  24. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  25. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  26. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  27. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  28. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  29. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  30. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  31. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  32. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  33. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  34. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  35. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  36. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  37. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  38. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  39. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  40. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  41. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  42. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  43. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  44. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  45. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  46. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  47. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/image.py +0 -0
  48. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/loops.py +0 -0
  49. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/machine.py +0 -0
  50. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  51. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  52. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  53. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
  54. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/reports.py +0 -0
  55. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  56. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/trace.py +0 -0
  57. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/values.py +0 -0
  58. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/oracle.py +0 -0
  59. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_continuation_budget.py +0 -0
  60. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_dispatch.py +0 -0
  61. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_effect_order.py +0 -0
  62. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_entry_frame.py +0 -0
  63. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_indirect_far_transfers.py +0 -0
  64. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_interrupt_models.py +0 -0
  65. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_loops.py +0 -0
  66. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_memory_scopes.py +0 -0
  67. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_nested_frame_request.py +0 -0
  68. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_oracle.py +0 -0
  69. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_pe.py +0 -0
  70. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_successor_rule.py +0 -0
  71. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_table_continuations.py +0 -0
  72. {scientific_method_engine-10.0.0 → scientific_method_engine-10.1.0}/tests/test_x86.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 10.0.0
3
+ Version: 10.1.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 = "10.0.0"
8
+ version = "10.1.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"
@@ -293,14 +293,55 @@ HIDDEN = "hidden-occurrences"
293
293
 
294
294
 
295
295
  def _atom_range(atom, ranges):
296
- if atom in ranges:
297
- return ranges[atom]
298
296
  if atom[0] == HIDDEN:
299
297
  return 0, inf
300
298
  if atom[0] == "signed":
301
299
  half = 1 << (atom[2] - 1)
302
300
  return -half, half - 1
303
- return 0, (1 << atom[1]) - 1
301
+ return _unsigned(atom[0], atom[1], ranges)
302
+
303
+
304
+ def _unsigned(term, bits, ranges):
305
+ """Bounds on the term's unsigned value at its width, read from bitwise structure and assumptions.
306
+
307
+ An assumed range, a constant, ``and``, ``or``, ``xor``, a shift right or division by a constant
308
+ (an arithmetic shift only when its operand's sign bit is clear), a remainder by a constant, a zero extension or an extracted field narrows the width's full
309
+ range; any other term keeps it.
310
+ """
311
+ if (term, bits) in ranges:
312
+ return ranges[(term, bits)]
313
+ top = (1 << bits) - 1
314
+ tag = term[0]
315
+ if tag == "constant":
316
+ return term[1] & top, term[1] & top
317
+ if tag in ("and", "or", "xor"):
318
+ (alo, ahi), (blo, bhi) = _unsigned(term[1], bits, ranges), _unsigned(term[2], bits, ranges)
319
+ if tag == "and":
320
+ return 0, min(ahi, bhi)
321
+ # Neither operand sets a bit above its own highest bit; OR keeps every bit of each operand.
322
+ return max(alo, blo) if tag == "or" else 0, (1 << max(ahi, bhi).bit_length()) - 1
323
+ if tag in ("shr", "sar", "udiv", "umod") and term[2][0] == "constant":
324
+ lo, hi = _unsigned(term[1], bits, ranges)
325
+ k = term[2][1] & top
326
+ if tag == "sar" and hi >> (bits - 1):
327
+ # An operand that may have its sign bit set shifts ones in from the top.
328
+ return 0, top
329
+ if tag in ("shr", "sar"):
330
+ # With the sign bit clear, an arithmetic shift right is the logical one.
331
+ # Shift terms carry x86's five-bit count mask; a count the mask changes keeps only the upper bound.
332
+ s = k & 31
333
+ return lo >> s if s == k else 0, hi >> s
334
+ if k == 0:
335
+ return 0, top
336
+ return (lo // k, hi // k) if tag == "udiv" else (0, min(hi, k - 1))
337
+ if tag == "zeroExtend" and term[3] == bits:
338
+ return _unsigned(term[1], term[2], ranges)
339
+ if tag == "extract" and term[3] == bits:
340
+ lo, hi = _unsigned(term[1], term[4], ranges)
341
+ low = term[2]
342
+ if hi >> low <= top:
343
+ return lo >> low, hi >> low
344
+ return 0, top
304
345
 
305
346
 
306
347
  def _interval(form, ranges):
@@ -529,6 +570,13 @@ def _ranges(control, path, anchor):
529
570
  if a["max"] >= 1 << atom[1]:
530
571
  raise ValueError(f"Relational control {control['name']} assumption range exceeds the value's width")
531
572
  ranges[atom] = (a["min"], a["max"])
573
+ # The assumed value's own expression may bound it too: keep the narrower range, and refuse an
574
+ # assumption the expression rules out, since a relation would hold over an empty range.
575
+ for atom, (lo, hi) in list(ranges.items()):
576
+ slo, shi = _unsigned(atom[0], atom[1], {k: v for k, v in ranges.items() if k != atom})
577
+ if lo > shi or hi < slo:
578
+ raise _Unresolved(f"the assumed range {lo}..{hi} is outside the range {slo}..{shi} the value's expression allows here")
579
+ ranges[atom] = max(lo, slo), min(hi, shi)
532
580
  return ranges
533
581
 
534
582
 
@@ -594,6 +594,95 @@ class RelationTests(unittest.TestCase):
594
594
  self.assertEqual(verdict(run(c, [bounded], registers=FRAME), "byte")["verdict"], "held")
595
595
 
596
596
 
597
+ class BitwiseBoundTests(unittest.TestCase):
598
+ """Unsigned bounds read from masks, shifts, division and extracted fields of an unknown loaded word."""
599
+
600
+ def check(self, body, op, right, signed=False, before=""):
601
+ # mov bx,[0200h] (or the body's own load), then the body, then a checkpoint at the return.
602
+ self.c = Code().emit(before).emit(body).label("return").emit("c3")
603
+ left = {"field": "registers.bx", **({"signed": True} if signed else {})}
604
+ rule = control("bound", "relation", at={"site": self.c.labels["return"], "event": "checkpoint"}, op=op, left=left, right=right)
605
+ return verdict(run(self.c, [rule], registers=FRAME), "bound")
606
+
607
+ def test_a_constant_mask_bounds_an_unknown_word(self):
608
+ # and bx,3
609
+ held = self.check("8b 1e 00 02 81 e3 03 00", "le", 3)
610
+ self.assertEqual(held["verdict"], "held")
611
+ self.assertEqual(held["paths"][0]["occurrences"][0]["leftMinusRight"], {"min": -3, "max": 0})
612
+ self.assertEqual(self.check("8b 1e 00 02 81 e3 03 00", "le", 2)["verdict"], "undecided")
613
+ with self.assertRaisesRegex(ValueError, "bound violated"):
614
+ self.check("8b 1e 00 02 81 e3 03 00", "gt", 3)
615
+
616
+ def test_an_unmasked_word_stays_undecided(self):
617
+ self.assertEqual(self.check("8b 1e 00 02", "le", 3)["verdict"], "undecided")
618
+
619
+ def test_a_mask_with_the_sign_bit_leaves_the_signed_value_undecided(self):
620
+ # and bx,8003h: the unsigned value is at most 8003h, while the signed value may be negative.
621
+ self.assertEqual(self.check("8b 1e 00 02 81 e3 03 80", "le", 0x8003)["verdict"], "held")
622
+ self.assertEqual(self.check("8b 1e 00 02 81 e3 03 80", "ge", 0, signed=True)["verdict"], "undecided")
623
+ # With the sign bit masked off, the signed value is the unsigned one.
624
+ self.assertEqual(self.check("8b 1e 00 02 81 e3 03 00", "ge", 0, signed=True)["verdict"], "held")
625
+
626
+ def test_shifts_extracted_fields_and_division_by_constants_bound_the_value(self):
627
+ # shr bx,4
628
+ self.assertEqual(self.check("8b 1e 00 02 c1 eb 04", "le", 0x0fff)["verdict"], "held")
629
+ self.assertEqual(self.check("8b 1e 00 02 c1 eb 04", "le", 0x0ffe)["verdict"], "undecided")
630
+ # mov ax,[0200h]; and ax,0FF0h; movzx bx,ah: the high byte of the masked word is at most 0Fh.
631
+ self.assertEqual(self.check("a1 00 02 25 f0 0f 0f b6 dc", "le", 0x0f)["verdict"], "held")
632
+ self.assertEqual(self.check("a1 00 02 25 f0 0f 0f b6 dc", "le", 0x0e)["verdict"], "undecided")
633
+ # xor dx,dx; mov ax,[0200h]; mov cx,10; div cx; then the remainder or the quotient into BX.
634
+ divide = "31 d2 a1 00 02 b9 0a 00 f7 f1"
635
+ self.assertEqual(self.check(divide + " 89 d3", "le", 9)["verdict"], "held")
636
+ self.assertEqual(self.check(divide + " 89 d3", "le", 8)["verdict"], "undecided")
637
+ self.assertEqual(self.check(divide + " 89 c3", "le", 0xffff // 10)["verdict"], "held")
638
+ self.assertEqual(self.check(divide + " 89 c3", "le", 0xffff // 10 - 1)["verdict"], "undecided")
639
+
640
+ def test_an_arithmetic_shift_is_bounded_only_when_the_sign_bit_is_clear(self):
641
+ # and bx,7FFFh; sar bx,4: the sign bit is clear, so the shift is a logical one.
642
+ self.assertEqual(self.check("8b 1e 00 02 81 e3 ff 7f c1 fb 04", "le", 0x07ff)["verdict"], "held")
643
+ self.assertEqual(self.check("8b 1e 00 02 81 e3 ff 7f c1 fb 04", "le", 0x07fe)["verdict"], "undecided")
644
+ # sar bx,4 of an unmasked word may shift ones in from the top.
645
+ self.assertEqual(self.check("8b 1e 00 02 c1 fb 04", "le", 0xfffe)["verdict"], "undecided")
646
+
647
+ def test_or_keeps_its_constant_bits_and_the_operands_highest_bit(self):
648
+ # movzx bx,byte [0200h]; or bx,10h
649
+ self.assertEqual(self.check("0f b6 1e 00 02 83 cb 10", "ge", 0x10)["verdict"], "held")
650
+ self.assertEqual(self.check("0f b6 1e 00 02 83 cb 10", "le", 0xff)["verdict"], "held")
651
+ self.assertEqual(self.check("0f b6 1e 00 02 83 cb 10", "le", 0xfe)["verdict"], "undecided")
652
+
653
+ def test_an_assumed_range_bounds_the_masked_operand(self):
654
+ # mov bx,cx; and bx,0FFh, with CX assumed at most 7.
655
+ c = Code().emit("89 cb 81 e3 ff 00").label("return").emit("c3")
656
+ rule = control("bound", "relation", at={"site": c.labels["return"], "event": "checkpoint"}, op="le",
657
+ left={"field": "registers.bx"}, right=7)
658
+ self.assertEqual(verdict(run(c, [rule], registers=FRAME), "bound")["verdict"], "undecided")
659
+ assumed = {**rule, "assume": [{"value": {"entryRegister": "cx"}, "min": 0, "max": 7, "evidence": "synthetic caller range"}]}
660
+ self.assertEqual(verdict(run(c, [assumed], registers=FRAME), "bound")["verdict"], "held")
661
+
662
+ def test_an_assumption_on_a_masked_value_keeps_the_narrower_range(self):
663
+ # mov bx,[0200h]; and bx,3, with BX itself assumed at most 100: the mask still bounds it by 3.
664
+ c = Code().emit("8b 1e 00 02 81 e3 03 00").label("return").emit("c3")
665
+
666
+ def bound(op, right, lo, hi):
667
+ rule = control("bound", "relation", at={"site": c.labels["return"], "event": "checkpoint"}, op=op,
668
+ left={"field": "registers.bx"}, right=right,
669
+ assume=[{"value": {"field": "registers.bx"}, "min": lo, "max": hi, "evidence": "synthetic range"}])
670
+ return verdict(run(c, [rule], registers=FRAME), "bound")
671
+
672
+ self.assertEqual(bound("le", 3, 0, 100)["verdict"], "held")
673
+ self.assertEqual(bound("le", 1, 0, 1)["verdict"], "held")
674
+ # A range the mask rules out would make any relation hold, so the occurrence is undecided.
675
+ excluded = bound("ge", 5, 5, 10)
676
+ self.assertEqual(excluded["verdict"], "undecided")
677
+ self.assertIn("outside the range 0..3", excluded["paths"][0]["occurrences"][0]["reason"])
678
+
679
+ def test_a_stopped_path_leaves_a_masked_bound_undecided(self):
680
+ # One path calls through BX and stops before the masked load.
681
+ result = self.check("8b 1e 00 02 81 e3 03 00", "le", 3, before="85 c0 74 02 ff d3")
682
+ self.assertEqual(result["verdict"], "undecided")
683
+ self.assertIn("stopped", " ".join(result["reasons"]))
684
+
685
+
597
686
  class OriginTests(unittest.TestCase):
598
687
  def recursion(self, local=""):
599
688
  # The helper counts AX down and returns FFFF from its base case; the root tests the result.