scientific-method-engine 7.4.0__tar.gz → 8.0.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 (69) hide show
  1. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/argument_frames.py +51 -13
  4. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/machine.py +4 -1
  5. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/relational.py +4 -4
  6. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/test_x86.py +112 -13
  7. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/.gitignore +0 -0
  8. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/LICENSE +0 -0
  9. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/README.md +0 -0
  10. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/__init__.py +0 -0
  11. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/__main__.py +0 -0
  12. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/cli.py +0 -0
  13. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  14. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  15. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  16. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  17. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  18. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  19. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  20. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  21. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  22. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  23. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  24. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  25. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  26. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  27. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  28. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  29. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  30. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  31. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  32. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  33. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  34. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  35. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  36. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  37. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  38. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  39. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  40. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  41. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  42. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  43. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  44. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  45. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  46. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  47. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/image.py +0 -0
  48. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/loops.py +0 -0
  49. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  50. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  51. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  52. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/pe.py +0 -0
  53. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/reports.py +0 -0
  54. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  55. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/trace.py +0 -0
  56. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/src/scientific_method_engine/x86/values.py +0 -0
  57. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/oracle.py +0 -0
  58. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/test_continuation_budget.py +0 -0
  59. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/test_dispatch.py +0 -0
  60. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/test_effect_order.py +0 -0
  61. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/test_entry_frame.py +0 -0
  62. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/test_loops.py +0 -0
  63. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/test_memory_scopes.py +0 -0
  64. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/test_nested_frame_request.py +0 -0
  65. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/test_oracle.py +0 -0
  66. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/test_pe.py +0 -0
  67. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/test_relational_controls.py +0 -0
  68. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.0}/tests/test_successor_rule.py +0 -0
  69. {scientific_method_engine-7.4.0 → scientific_method_engine-8.0.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: 7.4.0
3
+ Version: 8.0.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 = "7.4.0"
8
+ version = "8.0.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"
@@ -7,6 +7,8 @@ amount never join or split slots. Whatever a read did not settle on the path sta
7
7
  """
8
8
  from capstone.x86 import X86_OP_IMM, X86_OP_REG
9
9
 
10
+ from .machine import NO_WRITE
11
+
10
12
  # The argument bytes one frame maps; a wider frame is mapped up to here and stays open.
11
13
  WINDOW_BYTES = 256
12
14
 
@@ -131,12 +133,27 @@ def _frame(image, events, index):
131
133
  # A read byte with no known caller writer, one the callee stored to first, or one whose producers
132
134
  # lack the slot's writer saw something other than the caller's bytes. The store check catches an
133
135
  # overwrite derived from the argument itself, which keeps the writer among its producers.
134
- stale = [i for i, at in enumerate(span) if by_byte[at]["writerSite"] is None or first_store.get(at, read["order"]) < read["order"]
135
- or by_byte[at]["writerSite"] not in read["byteProducers"][i]["producers"]]
136
+ stale, unknown = [], []
137
+ for i, at in enumerate(span):
138
+ slot = by_byte[at]
139
+ if first_store.get(at, read["order"]) < read["order"]:
140
+ stale.append(i)
141
+ elif slot["writerSite"] is None:
142
+ stale.append(i)
143
+ # Nothing on the path wrote a byte with no write, so the caller did not. A byte a modeled
144
+ # call invalidated or another address may have stored could still hold the caller's value.
145
+ if slot["reason"] != NO_WRITE:
146
+ unknown.append(i)
147
+ elif slot["writerSite"] not in read["byteProducers"][i]["producers"]:
148
+ # No callee store through the frame's segment and base explains the missing writer: a callee
149
+ # write through another address or a modeled call in the callee may or may not have replaced it.
150
+ stale.append(i)
151
+ unknown.append(i)
136
152
  partial = [s["offset"] for s in covered if s["offset"] < offset or s["offset"] + s["width"] > offset + read["argument"]["width"]]
137
153
  groupings.append({"readSite": read["site"], "readOrder": read["order"], "offset": offset, "width": read["argument"]["width"],
138
154
  "grouping": read["argument"]["grouping"], "slotOffsets": [s["offset"] for s in covered],
139
- "partialSlots": partial, "bytesNotFromSlotWriter": stale})
155
+ "partialSlots": partial, "bytesNotFromSlotWriter": stale,
156
+ "bytesOfUnknownOrigin": unknown})
140
157
  if stale:
141
158
  open_reasons.append(f"bytes {stale} of the read at {read['site']} do not come from the slot's writer")
142
159
  if partial:
@@ -182,12 +199,17 @@ def argument_frames(report, image):
182
199
 
183
200
  A path gets one map per traced call, from caller-written slots to callee reads. A site's
184
201
  groupings agree only when every path that traced a call there settled on the same read widths
185
- and groupings. Separately, a site's widths are consistent when its paths read at least one byte
186
- the caller wrote and no two reads with a different offset, width or grouping both saw one shared
187
- byte from the caller; a path that skipped a read leaves the site consistent but not agreed.
188
- A read that saw bytes the callee stored itself, or bytes with no known caller writer, stays
189
- listed and marked with the paths it was made on that way, and its conflicts stay listed, but
190
- those bytes do not decide whether the widths are consistent. The report must come from
202
+ and groupings. Separately, a site's widths are consistent (``True``) when its paths read at
203
+ least one byte the caller wrote and no two reads with a different offset, width or grouping
204
+ both saw one shared byte from the caller; a path that skipped a read leaves the site consistent
205
+ but not agreed. Bytes the callee stored itself and bytes no write on the path stored are not
206
+ the caller's and do not decide consistency. A byte of unknown origin (invalidated by a modeled
207
+ call, possibly stored through another address, or missing the slot writer among its producers
208
+ without a callee store) may be the caller's, and so may a read byte past the mapped window: a
209
+ pair of reads that would conflict on such a byte is listed in ``undecidedWidths`` and leaves the
210
+ site's ``widthsConsistent`` ``None`` unless another pair conflicts on the caller's bytes. A site
211
+ with no such pair whose reads saw no byte the caller wrote is ``None`` when some read saw a byte
212
+ of unknown origin and ``False`` otherwise. The report must come from
191
213
  ``trace`` with ``argument_window=WINDOW_BYTES``: each traced call's slots come from its
192
214
  ``argumentSlots`` record, which this removes from every path, declared continuations included.
193
215
  """
@@ -207,7 +229,7 @@ def argument_frames(report, image):
207
229
  widths = sorted({tuple(sorted({(g["offset"], g["width"], g["grouping"]) for g in f["groupings"]})) for _, f in rows})
208
230
  # Each read's paths, split by whether every byte it saw came from the caller's slot writer, and the
209
231
  # frame bytes it saw from the slot writer on any path.
210
- read_on, from_caller, not_from_caller, caller_bytes = {}, {}, {}, {}
232
+ read_on, from_caller, not_from_caller, caller_bytes, unknown_bytes = {}, {}, {}, {}, {}
211
233
  for i, f in rows:
212
234
  for g in f["groupings"]:
213
235
  key = (g["offset"], g["width"], g["grouping"])
@@ -215,14 +237,29 @@ def argument_frames(report, image):
215
237
  (not_from_caller if g["bytesNotFromSlotWriter"] else from_caller).setdefault(key, set()).add(i)
216
238
  mapped = range(min(g["width"], f["mappedBytes"] - g["offset"]))
217
239
  caller_bytes.setdefault(key, set()).update(g["offset"] + at for at in mapped if at not in g["bytesNotFromSlotWriter"])
240
+ # A read byte past the window was never mapped, so it may be the caller's too.
241
+ unmapped = range(max(0, f["mappedBytes"] - g["offset"]), g["width"])
242
+ unknown_bytes.setdefault(key, set()).update(g["offset"] + at for at in [*g["bytesOfUnknownOrigin"], *unmapped])
218
243
  reads = sorted(read_on)
219
244
  # Distinct reads that share a byte conflict: different intervals, or one interval grouped two ways.
220
245
  pairs = [(a, b) for n, a in enumerate(reads) for b in reads[n + 1:] if _overlap(a, b)]
221
246
  conflicting = [[{"offset": o, "width": w, "grouping": k} for o, w, k in pair] for pair in pairs]
222
- # Only the caller's bytes decide consistency: a pair counts when both reads saw one shared byte from
247
+ # Only the caller's bytes decide consistency: a pair conflicts when both reads saw one shared byte from
223
248
  # the slot writer. A callee reusing its argument slot as a local neither breaks nor supplies the
224
- # width the caller's argument is read at, but a read past the caller's bytes still reads them.
249
+ # width the caller's argument is read at, but a read past the caller's bytes still reads them. A pair
250
+ # that would conflict if bytes of unknown origin were the caller's is undecided.
225
251
  caller_conflict = any(caller_bytes[a] & caller_bytes[b] for a, b in pairs)
252
+ undecided = [(a, b) for a, b in pairs if not caller_bytes[a] & caller_bytes[b]
253
+ and (caller_bytes[a] | unknown_bytes[a]) & (caller_bytes[b] | unknown_bytes[b])]
254
+ if caller_conflict:
255
+ consistent = False
256
+ elif undecided:
257
+ consistent = None
258
+ elif any(caller_bytes.values()):
259
+ consistent = True
260
+ else:
261
+ # No read saw a byte from the slot writers; one of unknown origin leaves open whether any read did.
262
+ consistent = None if any(unknown_bytes.values()) else False
226
263
  report["argumentFrameSites"].append({
227
264
  "callSite": site, "paths": sorted({i for i, _ in rows}), "frames": len(rows),
228
265
  "unsettledPaths": sorted({i for i, f in rows if not f["settledOnThisPath"]}),
@@ -231,7 +268,8 @@ def argument_frames(report, image):
231
268
  "fromCallerOnPaths": sorted(from_caller.get((o, w, k), ())),
232
269
  "notFromCallerOnPaths": sorted(not_from_caller.get((o, w, k), ()))} for o, w, k in reads],
233
270
  "conflictingWidths": conflicting,
234
- "widthsConsistent": any(caller_bytes.values()) and not caller_conflict,
271
+ "undecidedWidths": [[{"offset": o, "width": w, "grouping": k} for o, w, k in pair] for pair in undecided],
272
+ "widthsConsistent": consistent,
235
273
  "agreed": len(widths) == 1 and all(f["settledOnThisPath"] for _, f in rows),
236
274
  "interpretation": "read widths per traced path; paths that never reached this call are not represented"})
237
275
  return report
@@ -25,6 +25,9 @@ FLAT_PORT_REASON = "port access in the flat model depends on I/O privilege, whic
25
25
  # The write-log key that marks a point where the model forgot all memory.
26
26
  MEMORY_CLEARED = ("memory-cleared",)
27
27
 
28
+ # The ``unwritten`` cause of a byte that no write on the path stored.
29
+ NO_WRITE = "no write on this path"
30
+
28
31
 
29
32
  class WriteLog:
30
33
  """Append-only list of (key, previous value) pairs, one per register or memory byte a write changes.
@@ -299,7 +302,7 @@ class State:
299
302
  return dict(lost)
300
303
  if self.memory_cleared is not None:
301
304
  return {"cause": "dropped by a modeled call", "order": self.memory_cleared}
302
- return {"cause": "no write on this path", "order": None}
305
+ return {"cause": NO_WRITE, "order": None}
303
306
 
304
307
  def byte_writer(self, index, key):
305
308
  """The byteProducers row of one accessed byte: its producers and the write that stored it."""
@@ -6,7 +6,7 @@ whose paths were not all read (a stop, a limit, a dropped path) is undecided, ne
6
6
  """
7
7
  from bisect import bisect_right
8
8
  from .image import integer
9
- from .machine import ALIASES, State
9
+ from .machine import ALIASES, NO_WRITE, State
10
10
 
11
11
  KINDS = ("reach", "order", "lastWriter", "containment", "relation", "origin")
12
12
  OPERATORS = ("eq", "ne", "lt", "le", "gt", "ge")
@@ -333,7 +333,7 @@ class _Path:
333
333
  # Orders of modeled call returns, ascending.
334
334
  self.modeled = []
335
335
  # Unknown memory term name -> the first order of a read that showed its bytes had no
336
- # modeled value for a reason other than "no write on this path".
336
+ # modeled value for a reason other than NO_WRITE.
337
337
  self.first_drop = {}
338
338
  # For each event, the most recent branch earlier in the same frame (same entry and depth,
339
339
  # completed callee frames skipped), or None.
@@ -343,7 +343,7 @@ class _Path:
343
343
  self.by_site.setdefault((e["site"], e["kind"]), []).append(e["order"])
344
344
  if e["kind"] == "call-return" and e.get("modeled"):
345
345
  self.modeled.append(e["order"])
346
- if e["kind"] == "read" and any((r.get("unwritten") or {}).get("cause", "no write on this path") != "no write on this path"
346
+ if e["kind"] == "read" and any((r.get("unwritten") or {}).get("cause", NO_WRITE) != NO_WRITE
347
347
  for r in e.get("byteProducers", ())):
348
348
  for n in _leaves(e["value"]["expression"], set()):
349
349
  if n.startswith("memory:"):
@@ -525,7 +525,7 @@ def _occurrence(control, path, anchor, image):
525
525
  "writer": {"site": writer["site"], "order": writer["order"], "entry": writer["entry"], "depth": writer["depth"]}})
526
526
  else:
527
527
  unwritten = row.get("unwritten") or {"cause": "unknown", "order": None}
528
- verdict = (("held" if ENTRY_STATE in allowed else "violated") if unwritten["cause"] == "no write on this path"
528
+ verdict = (("held" if ENTRY_STATE in allowed else "violated") if unwritten["cause"] == NO_WRITE
529
529
  else "undecided")
530
530
  rows.append({"index": row["index"], "verdict": verdict, "writer": None, "unwritten": unwritten})
531
531
  verdicts.append(verdict)
@@ -431,7 +431,7 @@ class ArgumentFrameTests(unittest.TestCase):
431
431
  self.assertEqual(r["argumentFrameSites"][0]["readWidthSets"], [[{"offset": 0, "width": 2, "grouping": "consumed width only"},
432
432
  {"offset": 2, "width": 4, "grouping": "far-pointer"},
433
433
  {"offset": 6, "width": 2, "grouping": "consumed width only"}]])
434
- self.assertTrue(all(site["agreed"] and site["widthsConsistent"] for site in r["argumentFrameSites"]))
434
+ self.assertTrue(all(site["agreed"] and site["widthsConsistent"] is True for site in r["argumentFrameSites"]))
435
435
 
436
436
  def test_the_report_keeps_the_writes_its_slots_cite(self):
437
437
  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")
@@ -510,8 +510,10 @@ class ArgumentFrameTests(unittest.TestCase):
510
510
  frame = frames[0]
511
511
  self.assertEqual((frame["slots"][0]["writerSite"], frame["slots"][0]["reason"]), (None, "memory invalidated by the modeled call at 2"))
512
512
  self.assertEqual(frame["groupings"][0]["bytesNotFromSlotWriter"], [0, 1])
513
+ self.assertEqual(frame["groupings"][0]["bytesOfUnknownOrigin"], [0, 1])
513
514
  self.assertFalse(frame["settledOnThisPath"])
514
515
  self.assertFalse(r["argumentFrameSites"][0]["agreed"])
516
+ self.assertIsNone(r["argumentFrameSites"][0]["widthsConsistent"])
515
517
 
516
518
  def test_a_word_a_modeled_call_preserved_keeps_its_writer(self):
517
519
  # The model keeps the pushed word on a concrete stack, so the callee reads the push.
@@ -584,6 +586,17 @@ class ArgumentFrameTests(unittest.TestCase):
584
586
  self.assertEqual(frame["slots"][-1]["writerSite"], None)
585
587
  self.assertEqual(frame["slots"][-1]["offset"] + frame["slots"][-1]["width"], 256)
586
588
 
589
+ def test_a_read_past_the_window_leaves_the_site_undecided(self):
590
+ # The callee reads only a word 260 bytes up, past the mapped window: whose bytes it saw is open.
591
+ c = Code().emit("6a 01").branch("e8", "callee").emit("83 c4 02 c3").label("callee").emit("55 89 e5 8b 86 08 01 5d c3")
592
+ r, frames = self.frames(c)
593
+ self.assertEqual(frames[0]["mappedBytes"], 256)
594
+ self.assertEqual(frames[0]["groupings"][0]["offset"], 260)
595
+ self.assertIsNone(r["argumentFrameSites"][0]["widthsConsistent"])
596
+ # Control: the same word read inside the window saw only bytes no write stored.
597
+ c = Code().emit("6a 01").branch("e8", "callee").emit("83 c4 02 c3").label("callee").emit("55 89 e5 8b 86 fe 00 5d c3")
598
+ self.assertIs(self.frames(c)[0]["argumentFrameSites"][0]["widthsConsistent"], False)
599
+
587
600
  def test_paths_that_read_different_widths_keep_the_site_open(self):
588
601
  # One path reads a word, the other a far pointer, from the same two pushed words.
589
602
  c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3")
@@ -596,7 +609,7 @@ class ArgumentFrameTests(unittest.TestCase):
596
609
  [{"offset": 0, "width": 4, "grouping": "far-pointer"}]])
597
610
  self.assertFalse(site["agreed"])
598
611
  self.assertEqual(len(site["unsettledPaths"]), 1)
599
- self.assertFalse(site["widthsConsistent"])
612
+ self.assertIs(site["widthsConsistent"], False)
600
613
  self.assertEqual(site["conflictingWidths"], [[{"offset": 0, "width": 2, "grouping": "consumed width only"},
601
614
  {"offset": 0, "width": 4, "grouping": "far-pointer"}]])
602
615
 
@@ -611,7 +624,7 @@ class ArgumentFrameTests(unittest.TestCase):
611
624
  bypass = next(i for i, path in enumerate(r["paths"]) if not path["argumentFrames"][0]["settledOnThisPath"])
612
625
  self.assertEqual(site["unsettledPaths"], [bypass])
613
626
  self.assertIn("the slot at 2 was not read by the callee on this path", r["paths"][bypass]["argumentFrames"][0]["openReasons"])
614
- self.assertTrue(site["widthsConsistent"])
627
+ self.assertIs(site["widthsConsistent"], True)
615
628
  self.assertEqual(site["conflictingWidths"], [])
616
629
  self.assertEqual(site["readWidths"], [{"offset": 0, "width": 2, "grouping": "consumed width only", "paths": [0, 1],
617
630
  "fromCallerOnPaths": [0, 1], "notFromCallerOnPaths": []},
@@ -628,6 +641,8 @@ class ArgumentFrameTests(unittest.TestCase):
628
641
  self.assertEqual(len(frames), 2)
629
642
  reuse = next(i for i, path in enumerate(r["paths"]) if path["argumentFrames"][0]["groupings"][0]["width"] == 4)
630
643
  self.assertEqual(r["paths"][reuse]["argumentFrames"][0]["groupings"][0]["bytesNotFromSlotWriter"], [0, 1])
644
+ # The callee stored those bytes itself, so they are not of unknown origin.
645
+ self.assertEqual(r["paths"][reuse]["argumentFrames"][0]["groupings"][0]["bytesOfUnknownOrigin"], [])
631
646
  site = r["argumentFrameSites"][0]
632
647
  self.assertEqual(site["readWidths"], [{"offset": 0, "width": 2, "grouping": "consumed width only", "paths": [1 - reuse],
633
648
  "fromCallerOnPaths": [1 - reuse], "notFromCallerOnPaths": []},
@@ -635,7 +650,8 @@ class ArgumentFrameTests(unittest.TestCase):
635
650
  "fromCallerOnPaths": [], "notFromCallerOnPaths": [reuse]}])
636
651
  self.assertEqual(site["conflictingWidths"], [[{"offset": 0, "width": 2, "grouping": "consumed width only"},
637
652
  {"offset": 0, "width": 4, "grouping": "consumed width only"}]])
638
- self.assertTrue(site["widthsConsistent"])
653
+ self.assertEqual(site["undecidedWidths"], [])
654
+ self.assertIs(site["widthsConsistent"], True)
639
655
  self.assertFalse(site["agreed"])
640
656
  # Control: when the dword read sees the caller's bytes, the same pair makes the site inconsistent.
641
657
  c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3")
@@ -644,7 +660,7 @@ class ArgumentFrameTests(unittest.TestCase):
644
660
  site = self.frames(c)[0]["argumentFrameSites"][0]
645
661
  self.assertEqual(len(site["conflictingWidths"]), 1)
646
662
  self.assertEqual([w["notFromCallerOnPaths"] for w in site["readWidths"]], [[], []])
647
- self.assertFalse(site["widthsConsistent"])
663
+ self.assertIs(site["widthsConsistent"], False)
648
664
 
649
665
  def test_a_read_past_the_callers_bytes_still_conflicts_on_the_bytes_it_saw(self):
650
666
  # One pushed word, read as a dword on one path and as a word on the other. The dword's upper
@@ -655,11 +671,14 @@ class ArgumentFrameTests(unittest.TestCase):
655
671
  r, _ = self.frames(c)
656
672
  wide = next(i for i, path in enumerate(r["paths"]) if path["argumentFrames"][0]["groupings"][0]["width"] == 4)
657
673
  self.assertEqual(r["paths"][wide]["argumentFrames"][0]["groupings"][0]["bytesNotFromSlotWriter"], [2, 3])
674
+ # Nothing on the path wrote the upper bytes, so the caller did not: they are not of unknown origin.
675
+ self.assertEqual(r["paths"][wide]["argumentFrames"][0]["groupings"][0]["bytesOfUnknownOrigin"], [])
658
676
  site = r["argumentFrameSites"][0]
659
677
  self.assertEqual([(w["width"], w["fromCallerOnPaths"], w["notFromCallerOnPaths"]) for w in site["readWidths"]],
660
678
  [(2, [1 - wide], []), (4, [], [wide])])
661
679
  self.assertEqual(len(site["conflictingWidths"]), 1)
662
- self.assertFalse(site["widthsConsistent"])
680
+ self.assertEqual(site["undecidedWidths"], [])
681
+ self.assertIs(site["widthsConsistent"], False)
663
682
  # A dword over a stored first word and the caller's second word conflicts with a word read of the second.
664
683
  c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3")
665
684
  c.label("callee").emit("55 89 e5 85 f6").branch("74", "reuse").emit("8b 46 04 8b 5e 06").branch("eb", "done")
@@ -667,7 +686,82 @@ class ArgumentFrameTests(unittest.TestCase):
667
686
  site = self.frames(c)[0]["argumentFrameSites"][0]
668
687
  self.assertEqual([(w["offset"], w["width"]) for w in site["readWidths"]], [(0, 2), (0, 4), (2, 2)])
669
688
  self.assertEqual(len(site["conflictingWidths"]), 2)
670
- self.assertFalse(site["widthsConsistent"])
689
+ self.assertIs(site["widthsConsistent"], False)
690
+
691
+ def test_reads_that_share_only_bytes_nothing_wrote_do_not_conflict(self):
692
+ # One pushed word. One path reads a dword over it, the other reads the word above it, which
693
+ # nothing on the path wrote. The pair shares only those bytes, so it neither conflicts nor
694
+ # leaves the site undecided, and the dword's lower bytes are the caller's word.
695
+ c = Code().emit("6a 01").branch("e8", "callee").emit("83 c4 02 c3")
696
+ c.label("callee").emit("55 89 e5 85 f6").branch("74", "wide").emit("8b 46 06").branch("eb", "done")
697
+ c.label("wide").emit("66 8b 46 04").label("done").emit("5d c3")
698
+ r, frames = self.frames(c)
699
+ self.assertEqual(sorted((g["offset"], g["width"], g["bytesNotFromSlotWriter"], g["bytesOfUnknownOrigin"])
700
+ for f in frames for g in f["groupings"]), [(0, 4, [2, 3], []), (2, 2, [0, 1], [])])
701
+ site = r["argumentFrameSites"][0]
702
+ self.assertEqual(site["conflictingWidths"], [[{"offset": 0, "width": 4, "grouping": "consumed width only"},
703
+ {"offset": 2, "width": 2, "grouping": "consumed width only"}]])
704
+ self.assertEqual(site["undecidedWidths"], [])
705
+ self.assertIs(site["widthsConsistent"], True)
706
+
707
+ def test_a_pair_that_would_conflict_only_on_bytes_of_unknown_origin_is_undecided(self):
708
+ # The caller pushes a word. On one path a DS store before the call may alias the symbolic stack
709
+ # and the callee reads a dword; on the other the callee reads the caller's word. The dword's
710
+ # bytes may still be the caller's word, so the site is neither consistent nor inconsistent.
711
+ def build():
712
+ c = Code().emit("6a 01 85 ff").branch("74", "plain").emit("c7 06 00 01 05 00 be 01 00").branch("eb", "call")
713
+ c.label("plain").emit("31 f6").label("call").branch("e8", "callee").emit("83 c4 02 c3")
714
+ c.label("callee").emit("55 89 e5 85 f6").branch("75", "wide").emit("8b 46 04").branch("eb", "done")
715
+ c.label("wide").emit("66 8b 46 04").label("done").emit("5d c3")
716
+ return c
717
+ pair = [[{"offset": 0, "width": 2, "grouping": "consumed width only"}, {"offset": 0, "width": 4, "grouping": "consumed width only"}]]
718
+ r, frames = self.frames(build())
719
+ wide = next(f for f in frames if f["groupings"][0]["width"] == 4)
720
+ self.assertEqual([(s["offset"], s["width"], s["writerSite"], s.get("reason")) for s in wide["slots"]],
721
+ [(0, 4, None, "memory possibly overwritten through another address by the write at 6")])
722
+ self.assertEqual(wide["groupings"][0]["bytesOfUnknownOrigin"], [0, 1, 2, 3])
723
+ site = r["argumentFrameSites"][0]
724
+ self.assertEqual(site["conflictingWidths"], pair)
725
+ self.assertEqual(site["undecidedWidths"], pair)
726
+ self.assertIsNone(site["widthsConsistent"])
727
+ # Control: on a concrete stack the DS store lands elsewhere, so the dword saw the caller's word.
728
+ site = self.frames(build(), registers={"ss": 0x2000, "sp": 0x100, "ds": 0x3000})[0]["argumentFrameSites"][0]
729
+ self.assertEqual(site["conflictingWidths"], pair)
730
+ self.assertEqual(site["undecidedWidths"], [])
731
+ self.assertIs(site["widthsConsistent"], False)
732
+
733
+ def test_a_callee_store_through_another_address_leaves_its_slot_undecided(self):
734
+ # As with a callee reusing its slot, but the store goes through ES:[BX] (both unknown), which may
735
+ # or may not alias the slot. The dword read may still see the caller's words.
736
+ c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3")
737
+ c.label("callee").emit("55 89 e5 85 f6").branch("74", "reuse").emit("8b 46 04").branch("eb", "done")
738
+ c.label("reuse").emit("26 c7 07 00 00 66 8b 46 04").label("done").emit("5d c3")
739
+ r, frames = self.frames(c)
740
+ wide = next(f for f in frames if f["groupings"][0]["width"] == 4)
741
+ self.assertEqual([s["writerSite"] for s in wide["slots"]], [2, 0])
742
+ self.assertEqual((wide["groupings"][0]["bytesNotFromSlotWriter"], wide["groupings"][0]["bytesOfUnknownOrigin"]),
743
+ ([0, 1, 2, 3], [0, 1, 2, 3]))
744
+ site = r["argumentFrameSites"][0]
745
+ self.assertEqual(len(site["undecidedWidths"]), 1)
746
+ self.assertIsNone(site["widthsConsistent"])
747
+
748
+ def test_a_modeled_call_in_the_callee_leaves_its_slot_undecided(self):
749
+ # The callee calls a modeled service before reading its argument. The push wrote the slot, but
750
+ # the model forgot memory, so the read may or may not still see the caller's word.
751
+ def build():
752
+ c = Code().emit("6a 01").branch("e8", "callee").emit("83 c4 02 c3")
753
+ c.label("callee").emit("55 89 e5").branch("e8", "service").emit("8b 46 04 5d c3").label("service").emit("c3")
754
+ return c
755
+ model = [{"site": 12, "evidence": "synthetic service", "preserves": ["ss", "esp", "ebp"], "cases": [{}]}]
756
+ r, frames = self.frames(build(), callModels=model)
757
+ self.assertEqual(frames[0]["slots"][0]["writerSite"], 0)
758
+ self.assertEqual((frames[0]["groupings"][0]["bytesNotFromSlotWriter"], frames[0]["groupings"][0]["bytesOfUnknownOrigin"]),
759
+ ([0, 1], [0, 1]))
760
+ self.assertIsNone(r["argumentFrameSites"][0]["widthsConsistent"])
761
+ # Control: traced instead of modeled, the service leaves the caller's word in place.
762
+ r, frames = self.frames(build())
763
+ self.assertEqual(frames[0]["groupings"][0]["bytesOfUnknownOrigin"], [])
764
+ self.assertIs(r["argumentFrameSites"][0]["widthsConsistent"], True)
671
765
 
672
766
  def test_a_site_read_only_after_the_callee_stored_its_slot_is_not_consistent(self):
673
767
  # The callee stores over its argument and then reads it: the read is listed, but none saw the caller's word.
@@ -676,13 +770,13 @@ class ArgumentFrameTests(unittest.TestCase):
676
770
  self.assertEqual(site["readWidths"], [{"offset": 0, "width": 2, "grouping": "consumed width only", "paths": [0],
677
771
  "fromCallerOnPaths": [], "notFromCallerOnPaths": [0]}])
678
772
  self.assertEqual(site["conflictingWidths"], [])
679
- self.assertFalse(site["widthsConsistent"])
773
+ self.assertIs(site["widthsConsistent"], False)
680
774
  # A path that reads the caller's word and then the stored word at the same width lists the path both ways.
681
775
  c = Code().emit("6a 01").branch("e8", "callee").emit("83 c4 02 c3")
682
776
  c.label("callee").emit("55 89 e5 8b 46 04 c7 46 04 09 00 8b 5e 04 5d c3")
683
777
  site = self.frames(c)[0]["argumentFrameSites"][0]
684
778
  self.assertEqual([(w["paths"], w["fromCallerOnPaths"], w["notFromCallerOnPaths"]) for w in site["readWidths"]], [([0], [0], [0])])
685
- self.assertTrue(site["widthsConsistent"])
779
+ self.assertIs(site["widthsConsistent"], True)
686
780
 
687
781
  def test_paths_that_group_the_same_bytes_differently_keep_the_site_open(self):
688
782
  # Both paths read four bytes at offset 0: one as a far pointer with LES, one as a 32-bit dword.
@@ -696,7 +790,7 @@ class ArgumentFrameTests(unittest.TestCase):
696
790
  self.assertEqual(site["readWidthSets"], [[{"offset": 0, "width": 4, "grouping": "consumed width only"}],
697
791
  [{"offset": 0, "width": 4, "grouping": "far-pointer"}]])
698
792
  self.assertFalse(site["agreed"])
699
- self.assertFalse(site["widthsConsistent"])
793
+ self.assertIs(site["widthsConsistent"], False)
700
794
  self.assertEqual(len(site["conflictingWidths"]), 1)
701
795
 
702
796
  def test_one_path_that_groups_the_same_bytes_two_ways_stays_open(self):
@@ -709,7 +803,7 @@ class ArgumentFrameTests(unittest.TestCase):
709
803
  self.assertIn("the 4 bytes at 0 are read with more than one grouping", frames[0]["openReasons"])
710
804
  site = r["argumentFrameSites"][0]
711
805
  self.assertFalse(site["agreed"])
712
- self.assertFalse(site["widthsConsistent"])
806
+ self.assertIs(site["widthsConsistent"], False)
713
807
 
714
808
  def test_a_site_whose_callee_reads_nothing_is_not_consistent(self):
715
809
  # A pushed word the callee never reads leaves no read to be consistent with.
@@ -717,7 +811,7 @@ class ArgumentFrameTests(unittest.TestCase):
717
811
  r, _ = self.frames(c)
718
812
  site = r["argumentFrameSites"][0]
719
813
  self.assertEqual(site["readWidths"], [])
720
- self.assertFalse(site["widthsConsistent"])
814
+ self.assertIs(site["widthsConsistent"], False)
721
815
  self.assertFalse(site["agreed"])
722
816
 
723
817
  def test_a_write_through_another_address_drops_the_slot_writer(self):
@@ -730,11 +824,16 @@ class ArgumentFrameTests(unittest.TestCase):
730
824
  self.assertEqual([(s["offset"], s["width"], s["writerSite"], s.get("reason")) for s in frame["slots"]],
731
825
  [(0, 2, None, "memory possibly overwritten through another address by the write at 2")])
732
826
  self.assertEqual(frame["groupings"][0]["bytesNotFromSlotWriter"], [0, 1])
827
+ self.assertEqual(frame["groupings"][0]["bytesOfUnknownOrigin"], [0, 1])
733
828
  self.assertFalse(frame["settledOnThisPath"])
829
+ # The only read may or may not have seen the caller's word.
830
+ self.assertIsNone(r["argumentFrameSites"][0]["widthsConsistent"])
734
831
  # On a concrete stack the DS write lands elsewhere, so the push stays the slot's writer.
735
- frame = self.frames(c, registers={"ss": 0x2000, "sp": 0x100, "ds": 0x3000})[1][0]
832
+ r, frames = self.frames(c, registers={"ss": 0x2000, "sp": 0x100, "ds": 0x3000})
833
+ frame = frames[0]
736
834
  self.assertEqual([(s["offset"], s["width"], s["writerSite"]) for s in frame["slots"]], [(0, 2, 0)])
737
835
  self.assertTrue(frame["settledOnThisPath"], frame["openReasons"])
836
+ self.assertIs(r["argumentFrameSites"][0]["widthsConsistent"], True)
738
837
 
739
838
  def test_every_slot_agrees_with_the_callee_read_of_the_same_byte(self):
740
839
  # Each caller fills a frame through pushes, a reserved word, stores through DS or ES and a