scientific-method-engine 4.0.1__tar.gz → 4.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 (66) hide show
  1. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/argument_frames.py +1 -1
  4. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/machine.py +8 -3
  5. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/tests/test_continuation_budget.py +12 -2
  6. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/tests/test_memory_scopes.py +28 -0
  7. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/tests/test_x86.py +14 -0
  8. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/.gitignore +0 -0
  9. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/LICENSE +0 -0
  10. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/README.md +0 -0
  11. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/__init__.py +0 -0
  12. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/__main__.py +0 -0
  13. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/cli.py +0 -0
  14. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  15. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  16. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  17. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  18. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  19. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  20. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  21. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  22. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  23. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  24. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  25. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  26. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  27. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  28. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  29. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  30. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  31. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  32. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  33. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  34. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  35. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  36. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  37. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  38. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  39. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  40. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  41. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  42. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  43. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  44. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  45. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  46. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  47. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/image.py +0 -0
  48. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/loops.py +0 -0
  49. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  50. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  51. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  52. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
  53. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/relational.py +0 -0
  54. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/reports.py +0 -0
  55. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  56. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/trace.py +0 -0
  57. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/src/scientific_method_engine/x86/values.py +0 -0
  58. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/tests/oracle.py +0 -0
  59. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/tests/test_dispatch.py +0 -0
  60. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/tests/test_effect_order.py +0 -0
  61. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/tests/test_loops.py +0 -0
  62. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/tests/test_nested_frame_request.py +0 -0
  63. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/tests/test_oracle.py +0 -0
  64. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/tests/test_pe.py +0 -0
  65. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.0}/tests/test_relational_controls.py +0 -0
  66. {scientific_method_engine-4.0.1 → scientific_method_engine-4.1.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: 4.0.1
3
+ Version: 4.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 = "4.0.1"
8
+ version = "4.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"
@@ -45,7 +45,7 @@ def _writers(events, before, segment, base, start, width, modulus, image):
45
45
  for j in range(before - 1, -1, -1):
46
46
  event = events[j]
47
47
  interval = event.get("interval")
48
- if (event["kind"] == "write" and event.get("uncertainAliasesInvalidated") and interval
48
+ if (event["kind"] == "write" and (event.get("uncertainAliasesInvalidated") or event.get("uncertainScopeBytesInvalidated")) and interval
49
49
  and (interval["segment"], interval["base"]) != (segment, base)):
50
50
  written = written_domain(interval["segment"], interval["base"], interval["start"],
51
51
  interval["end"] - interval["start"], image.bits, image.flat)
@@ -320,7 +320,9 @@ class State:
320
320
 
321
321
  def access(self, segment, offset, width, write=None, role=None, addressing_register=None):
322
322
  seg, base, delta, keys = self.keys(segment, offset, width)
323
- uncertain = []
323
+ # Bytes a possibly aliasing write drops: those with a modeled value, and those a
324
+ # preservesMemory scope kept without one (counted apart, since they lose no value).
325
+ dropped_values = dropped_unread = 0
324
326
  if write is not None:
325
327
  write = Value(write.bits, write.term, sources(write, site=self.at))
326
328
  self.memory_epoch += 1
@@ -332,7 +334,10 @@ class State:
332
334
  continue
333
335
  for key in list(members):
334
336
  if may_alias(key, written, self.bits, self.flat):
335
- uncertain.append(key)
337
+ if key in self.memory:
338
+ dropped_values += 1
339
+ elif key in self.unread_memory:
340
+ dropped_unread += 1
336
341
  self.write_log.append((key, self.memory.pop(key, None)))
337
342
  self.unread_memory.pop(key, None)
338
343
  self.memory_writers.pop(key, None)
@@ -366,7 +371,7 @@ class State:
366
371
  value=value.report(), missingByteProducers=missing,
367
372
  byteProducers=[self.byte_writer(i, key) for i, key in enumerate(keys)],
368
373
  guards=deepcopy(relevant), role=role,
369
- uncertainAliasesInvalidated=len(uncertain))
374
+ uncertainAliasesInvalidated=dropped_values, uncertainScopeBytesInvalidated=dropped_unread)
370
375
  f = self.frames[-1]
371
376
  stack_base, stack_delta = address_parts(f["sp"])
372
377
  mem_base, mem_delta = address_parts(offset)
@@ -4,7 +4,7 @@ import unittest
4
4
  import test_dispatch # noqa: F401 (puts the engine sources on sys.path)
5
5
  from scientific_method_engine.x86.image import Image
6
6
  from scientific_method_engine.x86.reports import run_report
7
- from scientific_method_engine.x86.trace import trace
7
+ from scientific_method_engine.x86.trace import trace, PATH_BUDGET_INPUTS
8
8
 
9
9
  RETURN_ONE = bytes.fromhex("b8 01 00 c3")
10
10
  SPIN = bytes.fromhex("eb fe")
@@ -186,13 +186,23 @@ class ContinuationBudgetTests(unittest.TestCase):
186
186
 
187
187
  fields = {"paths": "maxPaths", "totalSteps": "totalSteps", "maxSteps": "maxSteps",
188
188
  "visitLimit": "visitLimit", "stringIterations": "stringIterations"}
189
+ # Both sides of every input's range boundaries, so a changed range is still probed at its edges.
190
+ values = sorted({v for low, high, _ in PATH_BUDGET_INPUTS.values() for v in (low - 1, low, high, high + 1)})
189
191
  for field, ordinary in fields.items():
190
- for value in (-1, 0, 1, 2, 256, 257, 4096, 4097, 10000, 10001, 65536, 65537, 100000, 100001):
192
+ for value in values:
191
193
  expected = accepted({ordinary: value}) or (field == "paths" and value == 0)
192
194
  self.assertEqual(accepted({"continuationBudget": {field: value}}), expected, (field, value))
193
195
  self.assertFalse(accepted({"maxPaths": 0}))
194
196
  self.assertTrue(accepted({"continuationBudget": {"paths": 0}}))
195
197
 
198
+ def test_out_of_range_budget_inputs_name_the_input(self):
199
+ data, config, _ = fan_out(1)
200
+ for name in ("stringIterations", "totalSteps"):
201
+ for command in ("trace", "uses"):
202
+ change = {name: -1, "query": {"segment": 0x2000, "offset": 0x100}} if command == "uses" else {name: -1}
203
+ with self.assertRaisesRegex(ValueError, "^" + name + " must be an integer in", msg=(name, command)):
204
+ run_report(data, {**config, **change}, command)
205
+
196
206
 
197
207
  if __name__ == "__main__":
198
208
  unittest.main()
@@ -254,6 +254,34 @@ class MemoryScopeTests(unittest.TestCase):
254
254
  state.access(state.segment("ss"), const(0x201, 16), 1, write=const(0x34, 8))
255
255
  self.assertEqual(state.unread_memory, {})
256
256
 
257
+ def test_aliasing_write_counts_dropped_values_apart_from_dropped_unread_scope_bytes(self):
258
+ # mov word [1000h],1234h; call service; mov byte [bx],1; ret. The scope DS:[BX] covers six
259
+ # bytes: two hold the stored word, four the model never had a value for.
260
+ c = Code().emit("c7 06 00 10 34 12").label("service").branch("e8", "external")
261
+ c.label("store").emit("c6 07 01 c3").label("external").emit("c3")
262
+ registers = {"ds": 0x2000, "ss": 0x3000, "sp": 0xff00, "bx": 0x1000}
263
+
264
+ def store(preserves):
265
+ model = {"site": c.labels["service"], "preserves": preserves, "cases": [{}],
266
+ "evidence": "synthetic service keeping DS:[BX]",
267
+ "preservesMemory": [scope(segment="ds", base="bx", bytes=6)]}
268
+ r = report(c, "effects", registers=registers, callModels=[model])
269
+ self.assertTrue(r["completeWithinModel"])
270
+ declared = r["paths"][0]["conditionalModels"][0]["preservedMemoryScopes"][0]
271
+ self.assertEqual((declared["cachedBytes"], declared["uncachedBytes"]), (2, 4))
272
+ return next(e for e in events(r, "write") if e["site"] == c.labels["store"])
273
+
274
+ # The model leaves BX unknown, so the store may alias every scoped byte and drops them all.
275
+ dropped = store(["ds", "ss"])
276
+ self.assertIsNone(dropped["offset"]["value"])
277
+ self.assertEqual(dropped["uncertainAliasesInvalidated"], 2)
278
+ self.assertEqual(dropped["uncertainScopeBytesInvalidated"], 4)
279
+ # Control: with BX preserved the store names one scoped byte and drops nothing.
280
+ kept = store(["ds", "ss", "ebx"])
281
+ self.assertEqual(kept["offset"]["value"], 0x1000)
282
+ self.assertEqual(kept["uncertainAliasesInvalidated"], 0)
283
+ self.assertEqual(kept["uncertainScopeBytesInvalidated"], 0)
284
+
257
285
  def test_exact_scope_and_byte_limits_execute_and_report_each_scope(self):
258
286
  c = Code().label("service").branch("e8", "external").emit("c3").label("external").emit("c3")
259
287
  for declarations in ([scope(base="bx", bytes=4096)],
@@ -511,6 +511,20 @@ class ArgumentFrameTests(unittest.TestCase):
511
511
  [(0, 1, 0, None), (1, 1, None, "memory invalidated by the modeled call at 2")])
512
512
  self.assertFalse(frame["settledOnThisPath"])
513
513
 
514
+ def test_a_write_that_drops_only_unread_scope_bytes_still_explains_the_slot(self):
515
+ # sub sp,2 reserves a slot nothing writes; the model keeps it without a value, and the ES
516
+ # store after the call (ES unknown) may alias it, so it drops two unread scope bytes and no value.
517
+ c = Code().emit("83 ec 02").branch("e8", "service").emit("26 c6 07 01").branch("e8", "callee").emit("83 c4 02 c3")
518
+ c.label("service").emit("c3").label("callee").emit("55 89 e5 8b 46 04 5d c3")
519
+ scope = {"segment": "ss", "base": "sp", "bytes": 2, "evidence": "synthetic reserved slot"}
520
+ model = {"site": 3, "evidence": "synthetic service", "preserves": ["ss", "esp"], "cases": [{}], "preservesMemory": [scope]}
521
+ r, frames = self.frames(c, registers={"ss": 0x2000, "sp": 0x100}, callModels=[model])
522
+ traced = report(c, "trace", registers={"ss": 0x2000, "sp": 0x100}, callModels=[model])
523
+ store = next(e for e in events(traced, "write") if e["site"] == 6)
524
+ self.assertEqual((store["uncertainAliasesInvalidated"], store["uncertainScopeBytesInvalidated"]), (0, 2))
525
+ self.assertEqual([(s["offset"], s["width"], s["writerSite"], s.get("reason")) for s in frames[0]["slots"]],
526
+ [(0, 2, None, "memory possibly overwritten through another address by the write at 6")])
527
+
514
528
  def test_a_callee_that_stops_leaves_its_frame_open(self):
515
529
  c = Code().emit("6a 01").branch("e8", "callee").emit("83 c4 02 c3").label("callee").emit("55 89 e5 8b 46 04 ff d3")
516
530
  r, frames = self.frames(c)