scientific-method-engine 10.1.0__tar.gz → 11.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 (74) hide show
  1. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/PKG-INFO +7 -1
  2. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/README.md +6 -0
  3. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/machine.py +29 -15
  5. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/pcode_backend.py +24 -1
  6. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/trace.py +52 -5
  7. scientific_method_engine-11.0.0/tests/test_enter_frames.py +135 -0
  8. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_entry_frame.py +2 -2
  9. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_oracle.py +7 -0
  10. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_pe.py +12 -0
  11. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_relational_controls.py +54 -0
  12. scientific_method_engine-11.0.0/tests/test_return_checks.py +134 -0
  13. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_x86.py +1 -1
  14. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/.gitignore +0 -0
  15. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/LICENSE +0 -0
  16. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/__init__.py +0 -0
  17. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/__main__.py +0 -0
  18. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/cli.py +0 -0
  19. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  20. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  21. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  22. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  23. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  24. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  25. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  26. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  27. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  28. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  29. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  30. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  31. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  32. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  33. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  34. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  35. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  36. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  37. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  38. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  39. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  40. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  41. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  42. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  43. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  44. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  45. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  46. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  47. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  48. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  49. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  50. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  51. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  52. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  53. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  54. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  55. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/image.py +0 -0
  56. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/loops.py +0 -0
  57. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  58. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  59. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/pe.py +0 -0
  60. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/relational.py +0 -0
  61. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/reports.py +0 -0
  62. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  63. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/src/scientific_method_engine/x86/values.py +0 -0
  64. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/oracle.py +0 -0
  65. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_continuation_budget.py +0 -0
  66. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_dispatch.py +0 -0
  67. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_effect_order.py +0 -0
  68. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_indirect_far_transfers.py +0 -0
  69. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_interrupt_models.py +0 -0
  70. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_loops.py +0 -0
  71. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_memory_scopes.py +0 -0
  72. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_nested_frame_request.py +0 -0
  73. {scientific_method_engine-10.1.0 → scientific_method_engine-11.0.0}/tests/test_successor_rule.py +0 -0
  74. {scientific_method_engine-10.1.0 → scientific_method_engine-11.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: 10.1.0
3
+ Version: 11.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
@@ -188,3 +188,9 @@ so the function's return balances and its paths can be read to the end. The repo
188
188
  gives the offsets, or the reasons the frame is not established, in which case the query runs as
189
189
  it would without the input. See the
190
190
  [narrower entry contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#a-narrower-entry-inside-its-functions-frame).
191
+
192
+ Each `return` event carries `returnCheck`: the frame's and the instruction's return widths, SP's
193
+ offset from the frame's entry SP, and whether the return words were read and compared with the
194
+ call. A width mismatch and an unbalanced stack stop the path with separate reasons. A root return
195
+ never reads its return words, so `returned: true` on a root path says nothing about them. See the
196
+ [command overview](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#commands).
@@ -172,3 +172,9 @@ so the function's return balances and its paths can be read to the end. The repo
172
172
  gives the offsets, or the reasons the frame is not established, in which case the query runs as
173
173
  it would without the input. See the
174
174
  [narrower entry contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#a-narrower-entry-inside-its-functions-frame).
175
+
176
+ Each `return` event carries `returnCheck`: the frame's and the instruction's return widths, SP's
177
+ offset from the frame's entry SP, and whether the return words were read and compared with the
178
+ call. A width mismatch and an unbalanced stack stop the path with separate reasons. A root return
179
+ never reads its return words, so `returned: true` on a root path says nothing about them. See the
180
+ [command overview](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#commands).
@@ -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.1.0"
8
+ version = "11.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"
@@ -123,7 +123,6 @@ class State:
123
123
  self.memory = {}
124
124
  # Keys grouped by (segment, base) so a write scans only groups that can alias it.
125
125
  self.memory_groups = {}
126
- self.memory_epoch = 0
127
126
  # The order of the write event that stored each modeled byte. lost_memory holds the
128
127
  # byteProducers "unwritten" row of bytes with no value that an ordinary write explains (a
129
128
  # possibly aliasing write dropped them) or that a preservesMemory scope kept without a
@@ -136,7 +135,8 @@ class State:
136
135
  self.memory_cleared = None
137
136
  self.writes = {}
138
137
  # Bytes a preservesMemory scope kept without a value (ADR 0009): key -> the unknown term
139
- # name they had before the modeled call. They stay unread: no value, no producer.
138
+ # name they had before the modeled call. They stay unread: no value, no producer. Every other
139
+ # byte with no value reads a term named by the event its "unwritten" row names (unread_term).
140
140
  self.unread_memory = {}
141
141
  self.events = []
142
142
  # Bytes above each traced call's return frame that the call event records (argument_slots); 0 records none.
@@ -190,11 +190,14 @@ class State:
190
190
  if frame["bp"] is not None:
191
191
  self.setreg(self.bp, op("add", base, const(frame["bp"], self.bits)), None)
192
192
 
193
- def frame_offset(self, value):
194
- """A register value as a signed offset from the current frame's entry SP, or None when it is not one."""
193
+ def frame_offset(self, value, absolute=False):
194
+ """A register value as a signed offset from the current frame's entry SP, or None when it is not one.
195
+
196
+ Two concrete values count as an offset from each other only with ``absolute``.
197
+ """
195
198
  base, delta = address_parts(self.frames[-1]["sp"])
196
199
  other, other_delta = address_parts(value)
197
- if other != base or base == ("absolute",):
200
+ if other != base or (base == ("absolute",) and not absolute):
198
201
  return None
199
202
  offset = (other_delta - delta) % (1 << self.bits)
200
203
  return offset - (1 << self.bits) if offset >> (self.bits - 1) else offset
@@ -262,15 +265,25 @@ class State:
262
265
  self.writes.clear()
263
266
  # The caller records the event that explains the loss right after clearing.
264
267
  self.memory_cleared = len(self.events)
265
- self.memory_epoch += 1
266
268
 
267
- def unread_term(self, key):
268
- """Name the unknown term of a byte with no modeled value: a kept scope term or the epoch's."""
269
- return self.unread_memory.get(key, f"memory:{self.memory_epoch}:{key}")
269
+ def unread_term(self, key, unwritten=None):
270
+ """Name the unknown term of a byte with no modeled value: a kept scope term, or one named by
271
+ the newest event that may have stored the byte.
270
272
 
271
- def byte(self, key):
273
+ That event is the one the byte's ``unwritten`` row names (pass the row when it is already
274
+ built): the newest write that may alias it, the write that dropped its value, the modeled
275
+ call that cleared memory, or none. Reads of the byte name the same term until such an event
276
+ happens, so a reload across writes that cannot store the byte reads the earlier term, and the
277
+ term changes exactly when the reported cause does.
278
+ """
279
+ if key in self.unread_memory:
280
+ return self.unread_memory[key]
281
+ order = (unwritten or self.unwritten(key))["order"]
282
+ return f"memory:{'entry' if order is None else order}:{key}"
283
+
284
+ def byte(self, key, unwritten=None):
272
285
  """The modeled value of one memory byte, or an unknown term produced by the current site."""
273
- return self.memory[key] if key in self.memory else unknown(self.unread_term(key), 8, self.at)
286
+ return self.memory[key] if key in self.memory else unknown(self.unread_term(key, unwritten), 8, self.at)
274
287
 
275
288
  def latest_aliasing_write(self, group, domain):
276
289
  """The order of the newest write outside `group` that may have stored a byte of `domain`, or None."""
@@ -392,8 +405,6 @@ class State:
392
405
  dropped_values = dropped_unread = 0
393
406
  if write is not None:
394
407
  write = Value(write.bits, write.term, sources(write, site=self.at))
395
- self.memory_epoch += 1
396
-
397
408
  written = written_domain(seg, base, delta, width, self.bits, self.flat)
398
409
  self.writes.setdefault((seg, base), {})[written] = len(self.events)
399
410
  for group, members in list(self.memory_groups.items()):
@@ -426,9 +437,12 @@ class State:
426
437
  self.memory_groups.setdefault((seg, base), set()).update(keys)
427
438
  value = write
428
439
  missing = []
440
+ rows = [self.byte_writer(i, key) for i, key in enumerate(keys)]
429
441
  else:
430
442
  missing = [i for i, key in enumerate(keys) if key not in self.memory]
431
- value = join([self.byte(key) for key in keys])
443
+ # Each row's "unwritten" cause names the term of a byte with no value, so it is built once.
444
+ rows = [self.byte_writer(i, key) for i, key in enumerate(keys)]
445
+ value = join([self.byte(key, row.get("unwritten")) for key, row in zip(keys, rows)])
432
446
  relevant = []
433
447
  for g in self.guards:
434
448
  left = g.get("left", {}).get("expression")
@@ -441,7 +455,7 @@ class State:
441
455
  event = self.event("write" if write is not None else "read", segment=segment.report(), offset=offset.report(),
442
456
  width=width, effectiveSegmentRegister=addressing_register, segmentInterpretation="base" if self.flat else "selector-paragraph", interval={"segment": seg, "base": base, "start": delta, "end": delta + width},
443
457
  value=value.report(), missingByteProducers=missing,
444
- byteProducers=[self.byte_writer(i, key) for i, key in enumerate(keys)],
458
+ byteProducers=rows,
445
459
  guards=deepcopy(relevant), role=role,
446
460
  uncertainAliasesInvalidated=dropped_values, uncertainScopeBytesInvalidated=dropped_unread)
447
461
  f = self.frames[-1]
@@ -611,9 +611,32 @@ def pop(state, ins, image):
611
611
  def leave(state, ins, image):
612
612
  if 0x66 in ins.prefix:
613
613
  raise StopPath("Operand-size override on LEAVE is unsupported")
614
+ # The CPU takes LEAVE's stack address size from SS, but SLEIGH lifts an address-size override
615
+ # with the other stack pointer width (ESP in real mode, SP in flat mode).
616
+ if 0x67 in ins.prefix:
617
+ raise StopPath("Address-size override on LEAVE is unsupported")
614
618
  run_plain(state, ins, image)
615
619
 
616
620
 
621
+ def enter(state, ins, image):
622
+ # SLEIGH lifts an operand-size override on ENTER with the default-size push, so p-code and the
623
+ # CPU would disagree on the saved frame pointer's width.
624
+ if 0x66 in ins.prefix:
625
+ raise StopPath("Operand-size override on ENTER is unsupported")
626
+ # The CPU takes ENTER's stack address size from SS, but SLEIGH lifts an address-size override
627
+ # with the other stack pointer width (ESP in real mode, SP in flat mode).
628
+ if 0x67 in ins.prefix:
629
+ raise StopPath("Address-size override on ENTER is unsupported")
630
+ # Nesting levels 0 and 1 lift to straight-line pushes and register writes, which run as p-code.
631
+ # Higher levels copy frame pointers from the caller's frame chain in a p-code loop. The CPU
632
+ # uses the level byte modulo 32, so the stop names that level.
633
+ f = Frame(state, ins, image)
634
+ if any(o.code == "CBRANCH" for o in f.ops):
635
+ raise StopPath(f"ENTER nesting level {ins.operands[1].imm & 0x1F} copies the caller's frame chain, "
636
+ "which is not modeled")
637
+ f.execute()
638
+
639
+
617
640
  def flags_frame(state, ins, image):
618
641
  # PUSHF/POPF keep the evidence layer's opaque flags snapshot; p-code supplies the width.
619
642
  ops, _ = LIFTER.ops(state.flat, ins.bytes, state.at)
@@ -970,7 +993,7 @@ def interrupt(state, ins, image):
970
993
  HANDLERS = {}
971
994
  for names, handler in ((("mov", "movzx", "movsx", "xchg"), move), (("nop",), nop), (("lea",), lea),
972
995
  (("lds", "les"), far_pointer), (("push",), push), (("pop",), pop), (("leave",), leave),
973
- (("pushf", "pushfd", "popf", "popfd"), flags_frame), (("cmp", "test"), compare),
996
+ (("enter",), enter), (("pushf", "pushfd", "popf", "popfd"), flags_frame), (("cmp", "test"), compare),
974
997
  (("add", "sub", "and", "or", "xor"), arithmetic), (("inc", "dec"), step), (("not",), invert),
975
998
  (("neg",), negate), (("adc", "sbb"), carry_arithmetic), (("clc", "stc", "cmc"), carry_flag),
976
999
  (("shl", "sal", "shr", "sar"), shift), (("rol", "ror", "rcl", "rcr"), rotate),
@@ -398,6 +398,47 @@ def snapshot(state):
398
398
  return {name: state.reg(name).report() for name in ALIASES}
399
399
 
400
400
 
401
+ # The stop for each failed combination of (widthMatches, stackBalanced) at a return.
402
+ RETURN_CHECK_STOPS = {(False, True): "return width differs from the call frame",
403
+ (True, False): "stack balance differs from the call",
404
+ (False, False): "return width and stack balance differ from the call frame"}
405
+ ENTRY_TARGET_UNREAD = "not read: the entry frame has no traced caller"
406
+ CHECK_FAILED_UNREAD = "not read: the width or stack balance check failed"
407
+ WORD_READ_STOPPED = "not compared: reading the return words stopped the path"
408
+ TARGET_CHECK_FAILED_UNREAD = "not read: the return target check failed"
409
+ WORD_VALUE_UNKNOWN = "not compared: the word read and the call's word are not both known values"
410
+
411
+
412
+ def return_word_check(matches, known):
413
+ """The ``target`` or ``segment`` entry for a return word read from the stack. A word that is not
414
+ the call's is reported as different only when both values are known; otherwise neither a match
415
+ nor a difference was shown."""
416
+ return "matches the call" if matches else "does not match the call" if known else WORD_VALUE_UNKNOWN
417
+
418
+
419
+ def return_check(state, frame, instruction_bytes, far):
420
+ """The checks a return makes against its frame, before any return word is read.
421
+
422
+ ``target`` (and ``segment`` for a far return) records whether the return words were read and
423
+ compared with the call. An entry frame's are never read, so a returned root path says nothing
424
+ about what its return words hold.
425
+ """
426
+ sp, entry_sp = state.reg(state.sp), frame["sp"]
427
+ offset = state.frame_offset(sp, absolute=True)
428
+ check = {"frame": "entry" if len(state.frames) == 1 else "call",
429
+ "frameBytes": frame["returnBytes"], "instructionBytes": instruction_bytes,
430
+ "widthMatches": frame["returnBytes"] == instruction_bytes,
431
+ "spOffset": offset, "stackBalanced": sp.term == entry_sp.term}
432
+ if "frameSource" in frame:
433
+ check["frameSource"] = frame["frameSource"]
434
+ unread = (ENTRY_TARGET_UNREAD if len(state.frames) == 1 else
435
+ WORD_READ_STOPPED if check["widthMatches"] and check["stackBalanced"] else CHECK_FAILED_UNREAD)
436
+ check["target"] = unread
437
+ if far:
438
+ check["segment"] = unread
439
+ return check
440
+
441
+
401
442
  STRING_BUDGET_STOP = "String iteration budget exhausted"
402
443
  # The accepted range and default of each ordinary path budget input. continuationBudget takes the
403
444
  # same ranges under the names in CONTINUATION_BUDGET_FIELDS, except that its paths may be 0.
@@ -961,21 +1002,27 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
961
1002
  raise StopPath("Far return is outside the PE32 flat model")
962
1003
  frame = state.frames[-1]
963
1004
  roles = result_contracts(state, contracts, frame["entry"])
1005
+ # The entry frame gets the same width and balance checks as a traced call. The return
1006
+ # words are read only for a traced call, after both checks pass.
1007
+ check = return_check(state, frame, 4 if m == "retf" else image.bits // 8, m == "retf")
964
1008
  state.event("return", registers=snapshot(state), cleanupBytes=ins.operands[0].imm if ins.operands else 0,
965
1009
  resultContracts=roles, callSite=frame.get("callSite"),
966
- callerEntry=state.frames[-2]["entry"] if len(state.frames) > 1 else None)
967
- # The entry frame gets the same width and balance checks as a traced call.
968
- expected = 4 if m == "retf" else image.bits // 8
969
- if expected != frame["returnBytes"] or state.reg(state.sp).term != frame["sp"].term:
970
- raise StopPath("return frame or stack balance differs from the call")
1010
+ callerEntry=state.frames[-2]["entry"] if len(state.frames) > 1 else None, returnCheck=check)
1011
+ if not check["widthMatches"] or not check["stackBalanced"]:
1012
+ raise StopPath(RETURN_CHECK_STOPS[check["widthMatches"], check["stackBalanced"]])
971
1013
  if len(state.frames) == 1:
972
1014
  finish(state, returned=True)
973
1015
  break
974
1016
  actual_ip = state.pop(image.bits // 8)
1017
+ check["target"] = return_word_check(actual_ip.number == frame["returnIP"], actual_ip.number is not None)
975
1018
  if actual_ip.number != frame["returnIP"]:
1019
+ if m == "retf":
1020
+ check["segment"] = TARGET_CHECK_FAILED_UNREAD
976
1021
  raise StopPath("return target was overwritten or has unknown provenance")
977
1022
  if m == "retf":
978
1023
  actual_cs = state.pop(2)
1024
+ check["segment"] = return_word_check(actual_cs.term == frame["callerCS"].term,
1025
+ actual_cs.number is not None and frame["callerCS"].number is not None)
979
1026
  if actual_cs.term != frame["callerCS"].term:
980
1027
  raise StopPath("far return segment changed")
981
1028
  state.setreg("cs", actual_cs, at)
@@ -0,0 +1,135 @@
1
+ """ENTER frames: the saved frame pointer, BP and the local allocation come from ENTER's p-code. Synthetic code only."""
2
+ import unittest
3
+
4
+ from test_x86 import Code, events, report
5
+
6
+ ENTRY_SP = ("unknown", "entry:sp")
7
+ INITIAL_BP = ("extract", ("unknown", "initial:ebp"), 0, 16, 32)
8
+ # mov ax, 1234h; leave; retf
9
+ BODY = "b8 34 12 c9 cb"
10
+
11
+
12
+ def below_entry(n):
13
+ """The offset expression for entry SP minus ``n``, wrapped to 16 bits."""
14
+ return ("offset", ENTRY_SP, -n % 0x10000)
15
+
16
+
17
+ def far(code, **extra):
18
+ return report(code, **{"returnBytes": 4, "maxSteps": 12, "maxPaths": 2, **extra})
19
+
20
+
21
+ def frame(size, level=0):
22
+ """ENTER size,level; mov ax, bp; mov cx, sp; leave; retf, with BP and SP copied out after ENTER."""
23
+ return far(f"c8 {size & 0xFF:02x} {size >> 8:02x} {level:02x} 89 e8 89 e1 c9 cb")
24
+
25
+
26
+ class EnterFrames(unittest.TestCase):
27
+ def test_enter_returns_as_the_explicit_prologue_does(self):
28
+ for size in ("04 00", "00 00"):
29
+ explicit = far("55 89 e5 83 ec " + size[:2] + " " + BODY)
30
+ entered = far(f"c8 {size} 00 " + BODY)
31
+ for r in (explicit, entered):
32
+ self.assertTrue(r["completeWithinModel"], r["paths"][0].get("stop"))
33
+ self.assertEqual(r["paths"][0]["registers"]["ax"]["value"], 0x1234)
34
+
35
+ def test_saved_frame_pointer_write_frame_pointer_and_allocation(self):
36
+ r = frame(4)
37
+ path = r["paths"][0]
38
+ self.assertTrue(r["completeWithinModel"], path.get("stop"))
39
+ saved = events(r, "write")
40
+ self.assertEqual(len(saved), 1)
41
+ self.assertEqual(saved[0]["site"], 0)
42
+ self.assertEqual(saved[0]["role"], "push")
43
+ self.assertEqual(saved[0]["width"], 2)
44
+ self.assertEqual(saved[0]["effectiveSegmentRegister"], "ss")
45
+ self.assertEqual(saved[0]["offset"]["expression"], below_entry(2))
46
+ self.assertEqual(saved[0]["value"]["expression"], INITIAL_BP)
47
+ # BP is the address of the saved frame pointer, and SP sits the local size below it.
48
+ self.assertEqual(path["registers"]["ax"]["expression"], below_entry(2))
49
+ self.assertIn(0, path["registers"]["ax"]["producers"])
50
+ self.assertEqual(path["registers"]["cx"]["expression"], below_entry(6))
51
+ self.assertIn(0, path["registers"]["cx"]["producers"])
52
+ # LEAVE reads the saved frame pointer back, so BP and SP return to their entry values.
53
+ restored = events(r, "read")[-1]
54
+ self.assertEqual((restored["role"], restored["offset"]["expression"]), ("pop", below_entry(2)))
55
+ self.assertEqual(path["registers"]["bp"]["expression"], INITIAL_BP)
56
+
57
+ def test_allocation_sizes_zero_and_the_word_edge_wrap(self):
58
+ self.assertEqual(frame(0)["paths"][0]["registers"]["cx"]["expression"], below_entry(2))
59
+ edge = frame(0xFFFF)
60
+ self.assertTrue(edge["completeWithinModel"], edge["paths"][0].get("stop"))
61
+ self.assertEqual(edge["paths"][0]["registers"]["cx"]["expression"], below_entry(2 + 0xFFFF))
62
+
63
+ def test_nesting_level_one_pushes_the_new_frame_pointer(self):
64
+ r = frame(4, level=1)
65
+ path = r["paths"][0]
66
+ self.assertTrue(r["completeWithinModel"], path.get("stop"))
67
+ writes = events(r, "write")
68
+ self.assertEqual([w["offset"]["expression"] for w in writes], [below_entry(2), below_entry(4)])
69
+ self.assertEqual(writes[1]["value"]["expression"], below_entry(2))
70
+ self.assertEqual(path["registers"]["ax"]["expression"], below_entry(2))
71
+ self.assertEqual(path["registers"]["cx"]["expression"], below_entry(8))
72
+ # p-code takes the level modulo 32, as the CPU does: 21h is level 1.
73
+ self.assertEqual(frame(4, level=0x21)["paths"][0]["registers"]["cx"]["expression"], below_entry(8))
74
+
75
+ def test_nesting_levels_that_copy_the_frame_chain_stop(self):
76
+ # The stop names the level the CPU uses, the byte modulo 32.
77
+ for byte, level in ((2, 2), (0x1F, 31), (0x22, 2), (0xFF, 31)):
78
+ r = far(f"c8 04 00 {byte:02x} " + BODY)
79
+ path = r["paths"][0]
80
+ self.assertFalse(r["completeWithinModel"])
81
+ self.assertFalse(path["returned"])
82
+ self.assertEqual(path["stop"], f"ENTER nesting level {level} copies the caller's frame chain, "
83
+ "which is not modeled")
84
+ self.assertEqual(events(r, "write"), [])
85
+
86
+ def test_operand_size_override_stops(self):
87
+ r = far("66 c8 04 00 00 " + BODY)
88
+ self.assertFalse(r["completeWithinModel"])
89
+ self.assertEqual(r["paths"][0]["stop"], "Operand-size override on ENTER is unsupported")
90
+
91
+ def test_address_size_override_stops_before_any_write(self):
92
+ # SLEIGH lifts 67 C8 in real mode with ESP and no SS base; the CPU still uses SS:SP.
93
+ r = far("67 c8 04 00 00 " + BODY)
94
+ self.assertFalse(r["completeWithinModel"])
95
+ self.assertEqual(r["paths"][0]["stop"], "Address-size override on ENTER is unsupported")
96
+ self.assertEqual(events(r, "write"), [])
97
+
98
+ def test_leave_with_an_address_size_override_stops(self):
99
+ # SLEIGH lifts 67 C9 in real mode with ESP and EBP; the CPU still restores SP from BP.
100
+ r = far("55 89 e5 b8 34 12 67 c9 cb")
101
+ self.assertFalse(r["completeWithinModel"])
102
+ self.assertEqual(r["paths"][0]["stop"], "Address-size override on LEAVE is unsupported")
103
+ self.assertEqual(events(r, "read"), [])
104
+
105
+ def test_a_frame_left_unrestored_does_not_return(self):
106
+ r = far("c8 04 00 00 b8 34 12 cb")
107
+ self.assertFalse(r["paths"][0]["returned"])
108
+ self.assertFalse(r["completeWithinModel"])
109
+
110
+ def test_step_limit_at_enter_stays_incomplete(self):
111
+ r = far("c8 04 00 00 " + BODY, maxSteps=1)
112
+ self.assertFalse(r["completeWithinModel"])
113
+ self.assertFalse(r["paths"][0]["returned"])
114
+ self.assertIn("step limit", r["paths"][0]["stop"])
115
+
116
+ def test_argument_bytes_reach_a_callee_through_its_enter_frame(self):
117
+ # push 1234h; push 5678h; call wrapper; ret | wrapper: enter 2,0; mov ax,[bp+4]; mov dx,[bp+6]; leave; ret 4
118
+ c = (Code().label("low").emit("68 34 12").label("high").emit("68 78 56").branch("e8", "wrapper").emit("c3")
119
+ .label("wrapper").emit("c8 02 00 00 8b 46 04 8b 56 06 c9 c2 04 00"))
120
+ r = report(c)
121
+ path = r["paths"][0]
122
+ self.assertTrue(r["completeWithinModel"], path.get("stop"))
123
+ arguments = [e for e in events(r, "read") if e.get("argument")]
124
+ self.assertEqual([(a["value"]["value"], a["argument"]["offsetFromEntrySP"], a["argument"]["pushProducers"])
125
+ for a in arguments],
126
+ [(0x5678, 2, [c.labels["high"]]), (0x1234, 4, [c.labels["low"]])])
127
+ self.assertEqual((path["registers"]["ax"]["value"], path["registers"]["dx"]["value"]), (0x5678, 0x1234))
128
+ # The wrapper's LEAVE and RET 4 restore the caller's frame.
129
+ returned = events(r, "call-return")[0]
130
+ self.assertEqual(returned["registers"]["sp"]["expression"], ENTRY_SP)
131
+ self.assertEqual(returned["registers"]["bp"]["expression"], INITIAL_BP)
132
+
133
+
134
+ if __name__ == "__main__":
135
+ unittest.main()
@@ -36,7 +36,7 @@ class EntryFrameTests(unittest.TestCase):
36
36
  c = cleanup()
37
37
  r = run(c, relationalControls=slot(c, "entryState"))
38
38
  self.assertNotIn("entryFrame", r)
39
- self.assertEqual({p["stop"] for p in r["paths"]}, {"return frame or stack balance differs from the call"})
39
+ self.assertEqual({p["stop"] for p in r["paths"]}, {"stack balance differs from the call"})
40
40
  self.assertEqual(verdict(r)["verdict"], "undecided")
41
41
 
42
42
  def test_the_observed_frame_lets_the_function_return_and_the_control_hold(self):
@@ -75,7 +75,7 @@ class EntryFrameTests(unittest.TestCase):
75
75
  self.assertFalse(frame["established"])
76
76
  self.assertEqual((frame["sp"], frame["arrivals"]), (None, 2))
77
77
  self.assertIn("different offsets: -4, -2", " ".join(frame["reasons"]))
78
- self.assertEqual({p["stop"] for p in r["paths"]}, {"return frame or stack balance differs from the call"})
78
+ self.assertEqual({p["stop"] for p in r["paths"]}, {"stack balance differs from the call"})
79
79
  result = verdict(r)
80
80
  self.assertEqual(result["verdict"], "undecided")
81
81
  self.assertIn("entryFrame was not established", " ".join(result["reasons"]))
@@ -62,6 +62,13 @@ class Stack(unittest.TestCase):
62
62
  def test_push_pop_and_leave(self):
63
63
  check(self, "b81100 50 6a22 5b 59 55 89e5 6a33 c9 c3", resolved=("bx", "cx", "sp"))
64
64
 
65
+ def test_enter_frames(self):
66
+ # mov bp, 1111h; ENTER size,level; mov ax, bp; mov cx, sp; [mov bx,[bp-2]]; mov dx,[bp]; leave; ret
67
+ for enter in ("c8040000", "c8000000", "c8ffff00", "c8040020"):
68
+ check(self, "bd1111 " + enter + " 89e8 89e1 8b5600 c9 c3", resolved=("ax", "cx", "dx", "bp", "sp"))
69
+ for enter in ("c8040001", "c8040021"):
70
+ check(self, "bd1111 " + enter + " 89e8 89e1 8b5efe 8b5600 c9 c3", resolved=("ax", "bx", "cx", "dx", "bp", "sp"))
71
+
65
72
  def test_memory_operands(self):
66
73
  check(self, "bb1000 c7076655 ff37 8f4702 8b4702 c3", registers=DATA, resolved=("ax",))
67
74
 
@@ -392,6 +392,18 @@ class PEReporterTests(unittest.TestCase):
392
392
  self.assertEqual(arg['argument']['offsetFromEntrySP'], 4)
393
393
  self.assertEqual(arg['width'], 4)
394
394
 
395
+ def test_arguments_follow_an_enter_frame(self):
396
+ c = Code().emit('68 78 56 34 12').branch('e8', 'callee').emit('83 c4 04 c3')
397
+ c.label('callee').emit('c8 08 00 00 8b 45 08 c9 c3')
398
+ r = report(c, 'trace')
399
+ self.assertTrue(r['completeWithinModel'], r)
400
+ saved = next(e for e in events(r, 'write') if e['site'] == CODE_RAW + c.labels['callee'])
401
+ self.assertEqual((saved['role'], saved['width']), ('push', 4))
402
+ arg = next(e for e in events(r, 'read') if e.get('argument'))
403
+ self.assertEqual(arg['value']['value'], 0x12345678)
404
+ self.assertEqual(arg['argument']['offsetFromEntrySP'], 4)
405
+ self.assertEqual(arg['argument']['pushProducers'], [CODE_RAW])
406
+
395
407
  def test_callee_cleanup_and_pointer_plus_independent_word(self):
396
408
  c = Code().emit('68 00 20 40 00 66 68 07 00').branch('e8', 'callee').emit('c3')
397
409
  c.label('callee').emit('55 89 e5 66 8b 45 08 8b 55 0a c9 c2 06 00')
@@ -110,6 +110,60 @@ class OrderTests(unittest.TestCase):
110
110
  self.assertIn("not shown equal", occurrence["reason"])
111
111
  self.assertEqual(result["queryAssumptions"]["callModels"], [self.c.labels["service"]])
112
112
 
113
+ def reload(self, store, registers=FRAME, scopes=None):
114
+ # Load a word, test it, run `store` on the nonzero branch, then reload the same word. With
115
+ # `scopes`, a modeled service with those preservesMemory scopes follows the store.
116
+ self.c = Code().emit("a1 00 01 85 c0").label("test").branch("74", "out").emit(store)
117
+ if scopes is not None:
118
+ self.c.label("service").branch("e8", "external")
119
+ self.c.label("use").emit("8b 1e 00 01").label("out").emit("c3").label("external").emit("c3")
120
+ rule = control("reload", "order", before={"site": self.c.labels["test"], "event": "branch"},
121
+ branch={"taken": False}, sameValue={"before": "left", "at": "value"},
122
+ at={"site": self.c.labels["use"], "event": "read"})
123
+ models = [] if scopes is None else [{"site": self.c.labels["service"], "evidence": "synthetic unread service",
124
+ "preserves": ["ds"], "preservesMemory": scopes, "cases": [{}]}]
125
+ return verdict(run(self.c, [rule], registers=registers, callModels=models), "reload")
126
+
127
+ def test_a_reload_keeps_the_tested_word_across_writes_that_cannot_store_it(self):
128
+ for name, store, registers in (
129
+ ("no write", "", {}),
130
+ ("disjoint word", "c7 06 00 02 01 00", {}),
131
+ ("adjacent byte", "c6 06 02 01 05", {}),
132
+ ("another segment register with the same value", "26 c7 06 00 02 01 00", {"es": FRAME["ds"]}),
133
+ ("another segment whose bytes lie elsewhere", "26 c7 06 00 01 01 00", {"es": 0x5000})):
134
+ with self.subTest(name):
135
+ self.assertEqual(self.reload(store, {**FRAME, **registers})["verdict"], "held")
136
+
137
+ def test_a_reload_after_a_write_that_may_store_the_word_is_undecided(self):
138
+ for name, store, registers in (
139
+ ("same word", "c7 06 00 01 01 00", {}),
140
+ ("high byte", "c6 06 01 01 05", {}),
141
+ ("unknown offset", "c7 07 01 00", {}),
142
+ ("unknown segment", "26 c7 06 00 02 01 00", {}),
143
+ ("another segment register naming the same bytes", "26 c7 06 00 01 01 00", {"es": FRAME["ds"]})):
144
+ with self.subTest(name):
145
+ result = self.reload(store, {**FRAME, **registers})
146
+ self.assertEqual(result["verdict"], "undecided")
147
+ occurrence = next(o for p in result["paths"] for o in p["occurrences"])
148
+ self.assertIn("not shown equal", occurrence["reason"])
149
+
150
+ def test_a_reload_through_an_unknown_segment_keeps_the_word_across_a_write_at_another_offset(self):
151
+ # DS is unknown: both accesses use its one value, so the offsets alone keep them apart.
152
+ for store, expected in (("c7 06 00 02 01 00", "held"), ("c6 06 00 01 05", "undecided")):
153
+ with self.subTest(store):
154
+ self.assertEqual(self.reload(store, {"ss": 0x3000, "sp": 0xff00})["verdict"], expected)
155
+
156
+ def test_a_reload_after_a_modeled_service_is_undecided_unless_a_scope_keeps_the_word(self):
157
+ # Without a scope the service may store the word. A preservesMemory scope over it keeps the
158
+ # term the first load read, across a disjoint write before the call too.
159
+ word = {"segment": "ds", "base": "bx", "displacement": 0x100, "bytes": 2, "evidence": "synthetic kept word"}
160
+ for name, store, scopes, expected in (
161
+ ("no scope", "", [], "undecided"),
162
+ ("scope over the word", "", [word], "held"),
163
+ ("scope after a disjoint write", "c7 06 00 02 01 00", [word], "held")):
164
+ with self.subTest(name):
165
+ self.assertEqual(self.reload(store, {**FRAME, "bx": 0}, scopes)["verdict"], expected)
166
+
113
167
  def test_a_wrong_direction_before_an_unread_call_is_undecided(self):
114
168
  # The helper's test runs once traced, then again inside a modeled call before the access.
115
169
  self.c = (Code().branch("e8", "helper").label("service").branch("e8", "helper").label("use").emit("8a 07 c3")
@@ -0,0 +1,134 @@
1
+ """Which checks a return made against its frame (returnCheck), and the stop each failure gives. Synthetic code only."""
2
+ import unittest
3
+ from test_x86 import events, report
4
+
5
+ ENTRY_UNREAD = "not read: the entry frame has no traced caller"
6
+ CHECK_FAILED = "not read: the width or stack balance check failed"
7
+ UNKNOWN_WORD = "not compared: the word read and the call's word are not both known values"
8
+
9
+
10
+ def only(result, kind="return", depth=None):
11
+ found = [e for e in events(result, kind) if depth is None or e["depth"] == depth]
12
+ assert len(found) == 1, found
13
+ return found[0]
14
+
15
+
16
+ def stops(result):
17
+ return {p["stop"] for p in result["paths"]}
18
+
19
+
20
+ class RootReturnChecks(unittest.TestCase):
21
+ def test_a_far_return_from_a_near_entry_fails_the_width_check_alone(self):
22
+ r = report("cb")
23
+ self.assertEqual(stops(r), {"return width differs from the call frame"})
24
+ self.assertFalse(r["completeWithinModel"])
25
+ self.assertEqual(only(r)["returnCheck"], {
26
+ "frame": "entry", "frameBytes": 2, "instructionBytes": 4, "widthMatches": False,
27
+ "spOffset": 0, "stackBalanced": True, "target": ENTRY_UNREAD, "segment": ENTRY_UNREAD})
28
+
29
+ def test_a_near_return_from_a_far_entry_fails_the_width_check_alone(self):
30
+ r = report("c3", returnBytes=4)
31
+ self.assertEqual(stops(r), {"return width differs from the call frame"})
32
+ check = only(r)["returnCheck"]
33
+ self.assertEqual((check["frameBytes"], check["instructionBytes"], check["stackBalanced"]), (4, 2, True))
34
+ self.assertNotIn("segment", check)
35
+
36
+ def test_an_extra_push_fails_the_balance_check_alone(self):
37
+ r = report("50 c3")
38
+ self.assertEqual(stops(r), {"stack balance differs from the call"})
39
+ check = only(r)["returnCheck"]
40
+ self.assertEqual((check["widthMatches"], check["stackBalanced"], check["spOffset"]), (True, False, -2))
41
+
42
+ def test_both_failures_are_named_together(self):
43
+ r = report("50 cb")
44
+ self.assertEqual(stops(r), {"return width and stack balance differ from the call frame"})
45
+ check = only(r)["returnCheck"]
46
+ self.assertEqual((check["widthMatches"], check["stackBalanced"], check["spOffset"]), (False, False, -2))
47
+
48
+ def test_the_offset_counts_from_a_concrete_entry_sp(self):
49
+ check = only(report("50 c3", registers={"ss": 0x9000, "sp": 0x8000}))["returnCheck"]
50
+ self.assertEqual((check["spOffset"], check["stackBalanced"]), (-2, False))
51
+
52
+ def test_an_sp_at_no_offset_from_the_entry_reports_no_offset(self):
53
+ # mov sp, ax: SP takes an unknown value unrelated to the entry SP.
54
+ r = report("8b e0 c3")
55
+ self.assertEqual(stops(r), {"stack balance differs from the call"})
56
+ self.assertIsNone(only(r)["returnCheck"]["spOffset"])
57
+
58
+ def test_a_returned_root_path_says_its_return_words_were_not_read(self):
59
+ # Positive control: the declared far entry returns, but nothing checked the root frame's words.
60
+ r = report("cb", returnBytes=4)
61
+ self.assertTrue(r["completeWithinModel"])
62
+ self.assertTrue(r["paths"][0]["returned"])
63
+ self.assertEqual(only(r)["returnCheck"], {
64
+ "frame": "entry", "frameBytes": 4, "instructionBytes": 4, "widthMatches": True,
65
+ "spOffset": 0, "stackBalanced": True, "target": ENTRY_UNREAD, "segment": ENTRY_UNREAD})
66
+
67
+
68
+ class TracedCallReturnChecks(unittest.TestCase):
69
+ def test_a_nested_near_return_compares_its_target(self):
70
+ r = report("e8 01 00 c3 c3")
71
+ self.assertTrue(r["completeWithinModel"])
72
+ self.assertEqual(only(r, depth=1)["returnCheck"], {
73
+ "frame": "call", "frameSource": "call", "frameBytes": 2, "instructionBytes": 2, "widthMatches": True,
74
+ "spOffset": 0, "stackBalanced": True, "target": "matches the call"})
75
+ self.assertEqual(only(r, depth=0)["returnCheck"]["target"], ENTRY_UNREAD)
76
+
77
+ def test_a_nested_far_return_compares_target_and_segment(self):
78
+ r = report("0e e8 01 00 cb cb", returnBytes=4)
79
+ self.assertTrue(r["completeWithinModel"])
80
+ check = only(r, depth=1)["returnCheck"]
81
+ self.assertEqual((check["frameBytes"], check["target"], check["segment"]), (4, "matches the call", "matches the call"))
82
+ self.assertIn("push-CS/near-call", check["frameSource"])
83
+
84
+ def test_an_overwritten_nested_target_is_compared_and_rejected(self):
85
+ # pop ax; push 5; ret
86
+ r = report("e8 01 00 c3 58 6a 05 c3")
87
+ self.assertEqual(stops(r), {"return target was overwritten or has unknown provenance"})
88
+ check = only(r, depth=1)["returnCheck"]
89
+ self.assertEqual((check["widthMatches"], check["stackBalanced"], check["target"]), (True, True, "does not match the call"))
90
+
91
+ def test_a_changed_nested_segment_is_compared_and_rejected(self):
92
+ # pop ax; pop bx; push 0; push ax; retf
93
+ r = report("0e e8 01 00 cb 58 5b 6a 00 50 cb", returnBytes=4)
94
+ self.assertEqual(stops(r), {"far return segment changed"})
95
+ check = only(r, depth=1)["returnCheck"]
96
+ self.assertEqual((check["target"], check["segment"]), ("matches the call", "does not match the call"))
97
+
98
+ def test_an_unknown_nested_target_is_not_reported_as_different(self):
99
+ # pop ax; push bx; ret: BX holds no known value, so the word is neither a match nor a difference.
100
+ r = report("e8 01 00 c3 58 53 c3")
101
+ self.assertEqual(stops(r), {"return target was overwritten or has unknown provenance"})
102
+ self.assertEqual(only(r, depth=1)["returnCheck"]["target"], UNKNOWN_WORD)
103
+
104
+ def test_an_unknown_far_target_leaves_the_segment_unread(self):
105
+ # pop ax; push bx; retf
106
+ r = report("0e e8 01 00 cb 58 53 cb", returnBytes=4)
107
+ check = only(r, depth=1)["returnCheck"]
108
+ self.assertEqual((check["target"], check["segment"]), (UNKNOWN_WORD, "not read: the return target check failed"))
109
+
110
+ def test_an_unknown_nested_segment_is_not_reported_as_different(self):
111
+ # pop ax; pop bx; push dx; push ax; retf
112
+ r = report("0e e8 01 00 cb 58 5b 52 50 cb", returnBytes=4)
113
+ self.assertEqual(stops(r), {"far return segment changed"})
114
+ check = only(r, depth=1)["returnCheck"]
115
+ self.assertEqual((check["target"], check["segment"]), ("matches the call", UNKNOWN_WORD))
116
+
117
+ def test_a_far_return_over_a_near_call_frame_stays_rejected_with_both_failures(self):
118
+ # The callee rebuilds its near frame as a far one (pop ax; push cs; push ax; retf). Width and
119
+ # balance both fail against the near call, and the return words are left unread.
120
+ r = report("e8 01 00 cb 58 0e 50 cb", returnBytes=4)
121
+ self.assertEqual(stops(r), {"return width and stack balance differ from the call frame"})
122
+ self.assertEqual(only(r, depth=1)["returnCheck"], {
123
+ "frame": "call", "frameSource": "call", "frameBytes": 2, "instructionBytes": 4, "widthMatches": False,
124
+ "spOffset": -2, "stackBalanced": False, "target": CHECK_FAILED, "segment": CHECK_FAILED})
125
+
126
+ def test_a_wrong_segment_conversion_stays_rejected(self):
127
+ # pop ax; push 0; push ax; retf
128
+ r = report("e8 01 00 cb 58 6a 00 50 cb", returnBytes=4)
129
+ self.assertEqual(stops(r), {"return width and stack balance differ from the call frame"})
130
+ self.assertFalse(r["completeWithinModel"])
131
+
132
+
133
+ if __name__ == "__main__":
134
+ unittest.main()
@@ -2689,7 +2689,7 @@ class ReporterTests(unittest.TestCase):
2689
2689
  code = Code().emit("0e").branch("e8", "callee").emit("c3").label("callee").emit("c3")
2690
2690
  result = report(code)
2691
2691
  self.assertFalse(result["completeWithinModel"])
2692
- self.assertIn("return frame", result["paths"][0]["stop"])
2692
+ self.assertEqual(result["paths"][0]["stop"], "return width differs from the call frame")
2693
2693
 
2694
2694
  def test_xchg_captures_memory_address_before_register_update(self):
2695
2695
  result = report("bb 20 02 b8 78 56 89 07 bb 20 02 87 1f c3", registers={"ds": 0x1234})