scientific-method-engine 8.0.0__tar.gz → 8.1.1__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 (70) hide show
  1. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/PKG-INFO +9 -1
  2. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/README.md +8 -0
  3. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/pyproject.toml +1 -1
  4. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/cli.py +2 -0
  5. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/memory_scopes.py +18 -1
  6. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/relational.py +47 -7
  7. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/trace.py +91 -29
  8. scientific_method_engine-8.1.1/tests/test_interrupt_models.py +219 -0
  9. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_relational_controls.py +132 -0
  10. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/.gitignore +0 -0
  11. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/LICENSE +0 -0
  12. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/__init__.py +0 -0
  13. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/__main__.py +0 -0
  14. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  15. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  16. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  17. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  18. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  19. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  20. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  21. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  22. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  23. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  24. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  25. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  26. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  27. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  28. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  29. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  30. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  31. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  32. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  33. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  34. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  35. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  36. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  37. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  38. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  39. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  40. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  41. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  42. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  43. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  44. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  45. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/__init__.py +0 -0
  46. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  47. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/dispatch.py +0 -0
  48. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/effect_order.py +0 -0
  49. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/image.py +0 -0
  50. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/loops.py +0 -0
  51. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/machine.py +0 -0
  52. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/pcode.py +0 -0
  53. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  54. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/pe.py +0 -0
  55. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/reports.py +0 -0
  56. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/result_flow.py +0 -0
  57. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/src/scientific_method_engine/x86/values.py +0 -0
  58. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/oracle.py +0 -0
  59. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_continuation_budget.py +0 -0
  60. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_dispatch.py +0 -0
  61. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_effect_order.py +0 -0
  62. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_entry_frame.py +0 -0
  63. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_loops.py +0 -0
  64. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_memory_scopes.py +0 -0
  65. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_nested_frame_request.py +0 -0
  66. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_oracle.py +0 -0
  67. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_pe.py +0 -0
  68. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_successor_rule.py +0 -0
  69. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_table_continuations.py +0 -0
  70. {scientific_method_engine-8.0.0 → scientific_method_engine-8.1.1}/tests/test_x86.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 8.0.0
3
+ Version: 8.1.1
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
@@ -145,6 +145,14 @@ boundary and continuation limits remain explicit gaps or stops. Partial-table sp
145
145
  partial evidence, never complete dispatch or native-reachability claims. See the
146
146
  [table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).
147
147
 
148
+ A call model may also sit at an `INT n` instruction in the real-mode model. The interrupt is
149
+ still reported as a hardware boundary with its vector, the handler is not executed, and each case
150
+ returns to the next instruction with SP and CS as before the interrupt. Registers, flags and memory
151
+ the model does not preserve or set are unknown. `leavesFlags: true` describes a service that returns
152
+ with a far return and leaves the interrupt's FLAGS word on the stack. Without a model, and at INT1,
153
+ INT3 (in either encoding), INTO or any PE32 interrupt, the path stops at the interrupt as before. See
154
+ [ADR 0017](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/decisions/0017-call-models-at-interrupt-sites.md).
155
+
148
156
  A call model may declare `preservesMemory`: up to 32 scopes (4,096 bytes in total), each naming a
149
157
  segment register, an address-width base register, an optional displacement, a byte count and the
150
158
  evidence for assuming the service leaves those bytes alone. Scopes resolve against the pre-call
@@ -129,6 +129,14 @@ boundary and continuation limits remain explicit gaps or stops. Partial-table sp
129
129
  partial evidence, never complete dispatch or native-reachability claims. See the
130
130
  [table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).
131
131
 
132
+ A call model may also sit at an `INT n` instruction in the real-mode model. The interrupt is
133
+ still reported as a hardware boundary with its vector, the handler is not executed, and each case
134
+ returns to the next instruction with SP and CS as before the interrupt. Registers, flags and memory
135
+ the model does not preserve or set are unknown. `leavesFlags: true` describes a service that returns
136
+ with a far return and leaves the interrupt's FLAGS word on the stack. Without a model, and at INT1,
137
+ INT3 (in either encoding), INTO or any PE32 interrupt, the path stops at the interrupt as before. See
138
+ [ADR 0017](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/decisions/0017-call-models-at-interrupt-sites.md).
139
+
132
140
  A call model may declare `preservesMemory`: up to 32 scopes (4,096 bytes in total), each naming a
133
141
  segment register, an address-width base register, an optional displacement, a byte count and the
134
142
  evidence for assuming the service leaves those bytes alone. Scopes resolve against the pre-call
@@ -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 = "8.0.0"
8
+ version = "8.1.1"
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"
@@ -27,6 +27,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
27
27
  "Declared table continuations are separate conditional paths that spend continuationBudget\n"
28
28
  "(paths, totalSteps, maxSteps, visitLimit, stringIterations); ordinary computed transfers remain stopped.\n"
29
29
  "Port accesses and interrupts are hardware-boundary events; portInputs supplies port reads as assumptions.\n"
30
+ "A callModels entry at an INT n site (real mode) returns past the interrupt under its cases (leavesFlags: true\n"
31
+ "keeps the interrupt's FLAGS word on the stack); other interrupts stop.\n"
30
32
  "callModels[].preservesMemory keeps explicit, bounded pre-call byte scopes across a modeled call; other memory stays unknown.\n"
31
33
  "A scope needs a concrete segment; its base may be symbolic, such as BP in an entryFrame query.\n"
32
34
  "Each traced path's loops record lists restart edges and what changed between iterations (loopIterationLimit).\n"
@@ -56,7 +56,7 @@ def validate_scopes(model, bits, flat):
56
56
  ranges.append((displacement, displacement + size))
57
57
 
58
58
 
59
- def capture_scopes(state, model):
59
+ def capture_scopes(state, model, frame_bytes=0):
60
60
  """Resolve each scope against the pre-call state and snapshot its bytes.
61
61
 
62
62
  Returns ``(values, unread, descriptions)``: the cached bytes, the unknown term names of bytes
@@ -68,8 +68,23 @@ def capture_scopes(state, model):
68
68
  share a linear byte (segment aliases included). A symbolic base may address any byte of its
69
69
  segment, so it may alias every scope whose segment range overlaps that segment. An uncached
70
70
  byte stays uncached after the call.
71
+
72
+ ``frame_bytes`` is the size of the return frame the processor writes below SS:SP when the modeled
73
+ instruction runs: the return address of a call, or FLAGS, CS and IP of an interrupt. Those bytes
74
+ no longer hold their pre-call values, so a scope that shares a byte with that frame on the same
75
+ segment and base raises ``StopPath``. A scope that only may alias the frame stays the query's
76
+ hypothesis.
71
77
  """
72
78
  values, unread, descriptions, resolved = {}, {}, [], []
79
+ frame = None
80
+ if frame_bytes:
81
+ try:
82
+ frame_seg, frame_base, _, frame_keys = state.keys(
83
+ state.segment("ss"), op("sub", state.reg(state.sp), const(frame_bytes, state.bits)), frame_bytes)
84
+ frame = ((frame_seg, frame_base), set(frame_keys))
85
+ except StopPath:
86
+ # A frame that wraps past offset zero of the stack segment is not checked.
87
+ frame = None
73
88
  for scope in model.get("preservesMemory", []):
74
89
  segment, base = state.segment(scope["segment"]), state.reg(scope["base"])
75
90
  if segment.number is None:
@@ -91,6 +106,8 @@ def capture_scopes(state, model):
91
106
  shared = domains_may_overlap(prior_domain, domain)
92
107
  if shared:
93
108
  raise StopPath("preservesMemory intervals overlap or alias")
109
+ if frame is not None and frame[0] == (seg, group_base) and not frame[1].isdisjoint(keys):
110
+ raise StopPath("preservesMemory scope covers the return frame the processor writes below SP")
94
111
  resolved.append(((seg, group_base), set(keys), domain))
95
112
  linear = seg == ("linear",)
96
113
  cached = 0
@@ -5,6 +5,7 @@ occurrence is held, violated or undecided. A violation on any path fails the que
5
5
  whose paths were not all read (a stop, a limit, a dropped path) is undecided, never held.
6
6
  """
7
7
  from bisect import bisect_right
8
+ from math import inf
8
9
  from .image import integer
9
10
  from .machine import ALIASES, NO_WRITE, State
10
11
 
@@ -217,11 +218,16 @@ def validate_controls(config, image):
217
218
  return controls
218
219
 
219
220
 
220
- # Linear forms: (constant, {atom: coefficient}); an atom is (term, bits) or ("signed", term, bits).
221
+ # Linear forms: (constant, {atom: coefficient}); an atom is (term, bits), ("signed", term, bits) or
222
+ # (HIDDEN, site, event), the events at a site that modeled callees before the anchor may have added.
223
+ HIDDEN = "hidden-occurrences"
224
+
221
225
 
222
226
  def _atom_range(atom, ranges):
223
227
  if atom in ranges:
224
228
  return ranges[atom]
229
+ if atom[0] == HIDDEN:
230
+ return 0, inf
225
231
  if atom[0] == "signed":
226
232
  half = 1 << (atom[2] - 1)
227
233
  return -half, half - 1
@@ -367,7 +373,8 @@ class _Path:
367
373
  return bisect_right(self.by_site.get((site, kind), ()), through)
368
374
 
369
375
  def modeled_before(self, order):
370
- return [self.events[o]["callSite"] for o in self.modeled[:bisect_right(self.modeled, order - 1)]]
376
+ # A modeled call's own return at the order counts: its callee ran before that event.
377
+ return [self.events[o]["callSite"] for o in self.modeled[:bisect_right(self.modeled, order)]]
371
378
 
372
379
  def value(self, term, anchor):
373
380
  if "entryRegister" in term:
@@ -404,7 +411,12 @@ class _Path:
404
411
  return _scaled(self.form(operand["mul"][0], anchor, ranges, modular), operand["mul"][1])
405
412
  if "occurrences" in operand:
406
413
  o = operand["occurrences"]
407
- return self.count(o["site"], o["event"], anchor["order"]), {}
414
+ count = self.count(o["site"], o["event"], anchor["order"])
415
+ # A modeled callee the path did not read may have run the counted site, so past one the
416
+ # read count is a lower bound: the form adds a hidden count of zero or more.
417
+ if self.modeled_before(anchor["order"]):
418
+ return count, {(HIDDEN, o["site"], o["event"]): 1}
419
+ return count, {}
408
420
  value = self.value(operand, anchor)
409
421
  # A form congruent modulo the value's own width is congruent modulo any narrower modulus.
410
422
  # A narrower value needs its integer value, which only a wrap-free range gives.
@@ -413,6 +425,22 @@ class _Path:
413
425
  return _integer(value["expression"], value["bits"], operand.get("signed", False), ranges)
414
426
 
415
427
 
428
+ def _bound(value):
429
+ """An interval end as reports carry it: None for an end no read event bounds."""
430
+ return None if value in (inf, -inf) else value
431
+
432
+
433
+ def _hidden(path, anchor, *forms):
434
+ """The reason for an undecided result whose forms hold counts that modeled calls may have raised."""
435
+ counted = sorted({(atom[1], atom[2]) for form in forms for atom in form[1] if atom[0] == HIDDEN})
436
+ if not counted:
437
+ return {}
438
+ calls = path.modeled_before(anchor["order"])
439
+ names = ", ".join(f"{event} events at {site}" for site, event in counted)
440
+ return {"reason": f"the count of {names} passed modeled calls at {', '.join(map(str, calls))}, whose callees may "
441
+ f"hold more of them, so the read count is only a lower bound", "modeledCalls": calls}
442
+
443
+
416
444
  def _ranges(control, path, anchor):
417
445
  """The assumed ranges by atom. Raises _Unresolved when this occurrence cannot apply one."""
418
446
  ranges = {}
@@ -489,7 +517,8 @@ def _occurrence(control, path, anchor, image):
489
517
  detail.update(taken=found.get("taken"), decidedBy=found.get("decidedBy"), branchReason=found.get("reason"))
490
518
  if found.get("taken") != control["branch"]["taken"]:
491
519
  # A modeled callee after the read execution may have run the branch again.
492
- modeled = [e["callSite"] for e in between if e["kind"] == "call-return" and e.get("modeled")]
520
+ modeled = [e["callSite"] for e in events[found["order"] + 1:order + 1]
521
+ if e["kind"] == "call-return" and e.get("modeled")]
493
522
  if modeled:
494
523
  detail.update(reason="the last read execution of the branch went the other way; a later modeled call is unread",
495
524
  modeledCalls=modeled)
@@ -554,12 +583,17 @@ def _occurrence(control, path, anchor, image):
554
583
  constant = difference[0] % size
555
584
  atoms = {a: k % size for a, k in difference[1].items() if k % size}
556
585
  if atoms:
557
- return "undecided", {"reason": f"left and right are not shown congruent modulo 2**{modulo}"}
586
+ return "undecided", _hidden(path, anchor, difference) or {
587
+ "reason": f"left and right are not shown congruent modulo 2**{modulo}"}
558
588
  same = constant == 0
559
589
  held = same if control["op"] == "eq" else not same
560
590
  return "held" if held else "violated", {"leftMinusRightModulo": constant}
561
591
  lo, hi = _interval(difference, ranges)
562
- return _decide(difference, control["op"], ranges), {"leftMinusRight": {"min": lo, "max": hi}}
592
+ verdict = _decide(difference, control["op"], ranges)
593
+ detail = {"leftMinusRight": {"min": _bound(lo), "max": _bound(hi)}}
594
+ if verdict == "undecided":
595
+ detail.update(_hidden(path, anchor, difference))
596
+ return verdict, detail
563
597
  if kind == "containment":
564
598
  interval = control["interval"]
565
599
  try:
@@ -571,6 +605,8 @@ def _occurrence(control, path, anchor, image):
571
605
  if segment["expression"] != anchor["segment"]["expression"] or segment["bits"] != anchor["segment"]["bits"]:
572
606
  return "undecided", {"reason": "the write's segment is not shown equal to the interval's segment",
573
607
  "writeSegment": anchor["segment"], "intervalSegment": segment}
608
+ if any(atom[0] == HIDDEN for atom in start[1]):
609
+ return "undecided", _hidden(path, anchor, start)
574
610
  bits = anchor["offset"]["bits"]
575
611
  size = 1 << bits
576
612
  relative = _combine(_modular(anchor["offset"]["expression"], bits, ranges), start, -1)
@@ -583,7 +619,11 @@ def _occurrence(control, path, anchor, image):
583
619
  room = _combine(_combine(length, relative, -1), (anchor["width"], {}), -1)
584
620
  rlo, rhi = _interval(relative, ranges)
585
621
  llo, lhi = _interval(length, ranges)
586
- return _decide(room, "ge", ranges), {"relativeStart": {"min": rlo, "max": rhi}, "width": anchor["width"], "length": {"min": llo, "max": lhi}}
622
+ verdict = _decide(room, "ge", ranges)
623
+ detail = {"relativeStart": {"min": rlo, "max": rhi}, "width": anchor["width"], "length": {"min": _bound(llo), "max": _bound(lhi)}}
624
+ if verdict == "undecided":
625
+ detail.update(_hidden(path, anchor, length))
626
+ return verdict, detail
587
627
  # origin
588
628
  try:
589
629
  value = path.value(control["value"], anchor)
@@ -10,6 +10,7 @@ from .values import const, unknown, sources, op, Value
10
10
  from .result_flow import validate_contracts, result_contracts
11
11
  from .loops import LoopTracker
12
12
  from .memory_scopes import validate_scopes, capture_scopes, retain_scopes, scope_history
13
+ from .pcode_backend import interrupt_vector
13
14
 
14
15
  def call_target(image, site, ins):
15
16
  if ins.mnemonic in ("lcall", "ljmp"):
@@ -27,6 +28,19 @@ PORTS = ("in", "out", "insb", "insw", "insd", "outsb", "outsw", "outsd")
27
28
  PORT_INPUTS = ("in", "insb", "insw", "insd")
28
29
 
29
30
 
31
+ def modeled_interrupt(image, ins, site):
32
+ """The vector of the ``INT n`` at ``site`` that a call model there describes, or None.
33
+
34
+ Only an ``INT n`` in the real-mode model takes a model. INT1, INT3 (also when encoded as
35
+ ``INT 1`` or ``INT 3``), INTO and every interrupt in the PE32 flat model keep stopping the path,
36
+ with or without a model at their site (ADR 0017). The vector can be 0, so test it against None.
37
+ """
38
+ if ins is None or ins.mnemonic != "int" or image.flat:
39
+ return None
40
+ vector, _ = interrupt_vector(image.flat, ins, site)
41
+ return None if vector in (1, 3) else vector
42
+
43
+
30
44
  def base_mnemonic(ins):
31
45
  # Capstone names REP/REPNE/BND prefixes in the mnemonic ("repz ret", "rep insb", "bnd jmp").
32
46
  return ins.mnemonic.split()[-1]
@@ -453,6 +467,11 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
453
467
  raise ValueError("A model requires 1..16 return cases")
454
468
  if "returnBytes" in model and (type(model["returnBytes"]) is not int or model["returnBytes"] not in (2, 4)):
455
469
  raise ValueError("Modeled returnBytes must be 2 or 4")
470
+ if "returnBytes" in model and modeled_interrupt(image, image.decode(model["site"]), model["site"]) is not None:
471
+ raise ValueError("An interrupt model takes no returnBytes: the interrupt returns past its own FLAGS, CS and IP")
472
+ if "leavesFlags" in model and (model["leavesFlags"] is not True
473
+ or modeled_interrupt(image, image.decode(model["site"]), model["site"]) is None):
474
+ raise ValueError("leavesFlags must be true and needs an INT n site in the real-mode model")
456
475
  if any(r not in REGISTERS for r in model.get("preserves", [])):
457
476
  raise ValueError("Model preserves must name full registers")
458
477
  validate_scopes(model, image.bits, image.flat)
@@ -460,6 +479,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
460
479
  for r, n in case.get("registers", {}).items():
461
480
  if r not in ALIASES or type(n) is not int or not 0 <= n < 1 << ALIASES[r][2]:
462
481
  raise ValueError("Invalid model register")
482
+ model_at = {model["site"]: model for model in models}
463
483
  explicit_continuation_budget = validate_continuation_budget(config)
464
484
  observed_frame = entry_frame(image, config, entry) if arrive is None else None
465
485
  root = State(entry, image, config)
@@ -515,6 +535,52 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
515
535
  gap["callStack"] = open_calls(s)
516
536
  global_gaps.append(gap)
517
537
 
538
+ def capture_model_scopes(s, model, frame_bytes):
539
+ # Scopes resolve against the state before the modeled instruction runs. frame_bytes is the
540
+ # return frame the processor writes below SP, which no scope may claim to preserve.
541
+ values, unread, scopes = capture_scopes(s, model, frame_bytes)
542
+ return values, unread, scopes, scope_history(s, values, unread)
543
+
544
+ def model_returns(s, model, captured, following, assumption, limit_reason, target, **marks):
545
+ # One child per case, each a conditional return under the query's model. ``marks`` extend
546
+ # the conditionalModels entry and the modeled call-return event (an interrupt's vector).
547
+ nonlocal created
548
+ at = s.at
549
+ kept_values, kept_unread, preserved_scopes, kept_history = captured
550
+ for case in model["cases"]:
551
+ if created >= max_paths:
552
+ path_limit(at, s, limit_reason)
553
+ break
554
+ child = deepcopy(s)
555
+ created += 1
556
+ for r in REGISTERS:
557
+ if r not in model.get("preserves", []) and r not in ("esp", "cs"):
558
+ child.setreg(r, unknown(f"modeled-call:{at}:{r}", ALIASES[r][2]), at)
559
+ child.clear_memory()
560
+ retain_scopes(child, kept_values, kept_unread, kept_history)
561
+ if model.get("leavesFlags"):
562
+ # The handler returned with a far return over the interrupt's FLAGS word, which stays on
563
+ # the stack. Its word is the pre-interrupt FLAGS snapshot, so a later POPF restores them.
564
+ child.save_flags(16)
565
+ child.forget_flags()
566
+ child.direction_flag = unknown(f"modeled-call:{at}:DF:{child.flag_serial}", 1, at)
567
+ child.interrupt_flag = unknown(f"modeled-call:{at}:IF:{child.flag_serial}", 1, at)
568
+ for r, n in case.get("registers", {}).items():
569
+ child.setreg(r, const(n, ALIASES[r][2], at), at)
570
+ child.conditional.append({"site": at, "evidence": model["evidence"], **marks,
571
+ "assumption": assumption + "; memory effects unresolved"
572
+ + (" outside explicit scopes" if preserved_scopes else ""),
573
+ "preservedMemoryScopes": preserved_scopes})
574
+ # The scopes are reported once, on the path's conditionalModels entry; the event cites its index.
575
+ child.event("call-return", callSite=at, callerEntry=s.frames[-1]["entry"],
576
+ # A modeled call's result contracts are its target's; an interrupt's target is None,
577
+ # which no contract names.
578
+ resultContracts=result_contracts(child, contracts, target),
579
+ registers=snapshot(child), modeled=True, **marks,
580
+ unknownMemoryEffects=True, conditionalModel=len(child.conditional) - 1)
581
+ child.at = following
582
+ pending.append(child)
583
+
518
584
  def finish(s, reason=None, returned=False):
519
585
  if continuing and reason and reason.startswith(STRING_BUDGET_STOP):
520
586
  # machine.py names no budget; a continuation's string iterations come from continuationBudget.
@@ -712,6 +778,27 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
712
778
  string_step(state, ins, count)
713
779
  state.at = following
714
780
  continue
781
+ interrupt_model = model_at.get(at) if m == "int" else None
782
+ vector = modeled_interrupt(image, ins, at) if interrupt_model else None
783
+ if vector is not None:
784
+ # The handler is not executed. The boundary event is kept, and each case returns to the
785
+ # next instruction under the query's model, with CS as before the interrupt and SP as before it or,
786
+ # under leavesFlags, one FLAGS word below (ADR 0017).
787
+ # Scopes resolve first, so a path that stops on them reports the boundary unmodeled.
788
+ try:
789
+ captured = capture_model_scopes(state, interrupt_model, 6)
790
+ except StopPath:
791
+ state.event("hardware-boundary", boundary="interrupt", mnemonic=m, vector=vector,
792
+ interpretation="the interrupt handler and its effects are not modeled")
793
+ raise
794
+ state.event("hardware-boundary", boundary="interrupt", mnemonic=m, vector=vector, modeled=True,
795
+ interpretation="the interrupt handler is not executed; a callModels case supplies its return")
796
+ model_returns(state, interrupt_model, captured, following,
797
+ "interrupt returns to the next instruction with its FLAGS word left on the stack and CS unchanged"
798
+ if interrupt_model.get("leavesFlags") else
799
+ "interrupt returns to the next instruction with balanced stack and CS unchanged",
800
+ "path limit at modeled interrupt", None, boundary="interrupt", vector=vector)
801
+ break
715
802
  if m in ("call", "lcall"):
716
803
  target, provenance = call_target(image, at, ins)
717
804
  indirect_value = None
@@ -730,7 +817,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
730
817
  push_cs = (not image.flat and m == "call" and previous is not None and previous.mnemonic == "push"
731
818
  and previous.size + state.path[-2] == at and previous.operands[0].type == X86_OP_REG
732
819
  and previous.reg_name(previous.operands[0].reg) == "cs" and previous.operands[0].size == 2)
733
- model = next((x for x in models if x["site"] == at), None)
820
+ model = model_at.get(at)
734
821
  if model:
735
822
  return_bytes = model.get("returnBytes", 4 if m == "lcall" else image.bits // 8)
736
823
  # The encoding before the call decides validity; a path that reaches the call
@@ -745,38 +832,13 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
745
832
  raise StopPath("push-CS/near-call model requires an explicit four-byte return contract")
746
833
  # Scopes resolve against the pre-call state: before the modeled frame consumes an
747
834
  # already-pushed CS word and before a case replaces registers.
748
- kept_values, kept_unread, preserved_scopes = capture_scopes(state, model)
749
- kept_history = scope_history(state, kept_values, kept_unread)
835
+ captured = capture_model_scopes(state, model, 4 if m == "lcall" else image.bits // 8)
750
836
  if push_cs:
751
837
  actual_cs = state.pop(2)
752
838
  if actual_cs.term != state.reg("cs").term:
753
839
  raise StopPath("modeled far return segment changed")
754
- for case in model["cases"]:
755
- if created >= max_paths:
756
- path_limit(at, state, "path limit at modeled call")
757
- break
758
- child = deepcopy(state)
759
- created += 1
760
- for r in REGISTERS:
761
- if r not in model.get("preserves", []) and r not in ("esp", "cs"):
762
- child.setreg(r, unknown(f"modeled-call:{at}:{r}", ALIASES[r][2]), at)
763
- child.clear_memory()
764
- retain_scopes(child, kept_values, kept_unread, kept_history)
765
- child.forget_flags()
766
- child.direction_flag = unknown(f"modeled-call:{at}:DF:{child.flag_serial}", 1, at)
767
- child.interrupt_flag = unknown(f"modeled-call:{at}:IF:{child.flag_serial}", 1, at)
768
- for r, n in case.get("registers", {}).items():
769
- child.setreg(r, const(n, ALIASES[r][2], at), at)
770
- child.conditional.append({"site": at, "evidence": model["evidence"],
771
- "assumption": "call returns with balanced stack; memory effects unresolved"
772
- + (" outside explicit scopes" if preserved_scopes else ""),
773
- "preservedMemoryScopes": preserved_scopes})
774
- # The scopes are reported once, on the path's conditionalModels entry; the event cites its index.
775
- child.event("call-return", callSite=at, callerEntry=state.frames[-1]["entry"],
776
- resultContracts=result_contracts(child, contracts, target), registers=snapshot(child), modeled=True,
777
- unknownMemoryEffects=True, conditionalModel=len(child.conditional) - 1)
778
- child.at = following
779
- pending.append(child)
840
+ model_returns(state, model, captured, following, "call returns with balanced stack",
841
+ "path limit at modeled call", target)
780
842
  break
781
843
  if target is None:
782
844
  raise StopPath("unresolved call: " + provenance.get("reason", "outside mapped code"))
@@ -0,0 +1,219 @@
1
+ """Call models at INT n sites (ADR 0017), over synthetic real-mode code. No original bytes or claims."""
2
+ import unittest
3
+
4
+ from test_x86 import Code, report
5
+ from test_pe import CODE_RAW, Code as FlatCode, report as flat_report
6
+
7
+ FRAME = {"ds": 0x2000, "ss": 0x3000, "sp": 0xff00}
8
+
9
+
10
+ def model(site, cases=({},), **extra):
11
+ return {"site": site, "evidence": "synthetic interrupt service hypothesis", "cases": list(cases), **extra}
12
+
13
+
14
+ def control(name, kind, **fields):
15
+ return {"name": name, "kind": kind, **fields}
16
+
17
+
18
+ def verdict(result, name):
19
+ return next(c for c in result["relationalControls"]["controls"] if c["name"] == name)
20
+
21
+
22
+ def wrapper_case(test="a8 01"):
23
+ """A caller passes one far scratch pointer twice to a wrapper around INT 33h.
24
+
25
+ The wrapper stores CX then DX through the two pointers and copies BX to AX; the caller reads
26
+ the scratch word into CX and tests bit zero of AL (``test``), or of CL to test the scratch word.
27
+ """
28
+ c = (Code().emit("1e b8 40 00 50 1e 50").branch("e8", "wrapper").emit("83 c4 08")
29
+ .label("scratch").emit("8b 0e 40 00").label("test").emit(test).branch("74", "zero").emit("c3")
30
+ .label("zero").emit("c3")
31
+ .label("wrapper").emit("55 89 e5").label("int").emit("cd 33")
32
+ .emit("c4 7e 04").label("first").emit("26 89 0d").emit("c4 7e 08").label("second").emit("26 89 15")
33
+ .emit("89 d8 5d c3"))
34
+ frame = {"segment": "ss", "base": "bp", "bytes": 12, "evidence": "synthetic saved BP, return word and four argument words"}
35
+ service = model(c.labels["int"], [{"registers": {"cx": 5, "dx": 7}}], preserves=["ds", "ss", "ebp"],
36
+ preservesMemory=[frame])
37
+ return c, service
38
+
39
+
40
+ class InterruptModelTests(unittest.TestCase):
41
+ def test_each_case_returns_past_the_interrupt_with_its_boundary_kept(self):
42
+ r = report("cd 21 c3", "effects", registers=FRAME, callModels=[model(0, [{"registers": {"ax": 0}}, {"registers": {"ax": 1}}])])
43
+ self.assertTrue(r["completeWithinModel"])
44
+ self.assertEqual(sorted(p["registers"]["ax"]["value"] for p in r["paths"]), [0, 1])
45
+ for path in r["paths"]:
46
+ self.assertTrue(path["returned"])
47
+ boundary = next(e for e in path["events"] if e["kind"] == "hardware-boundary")
48
+ self.assertEqual((boundary["boundary"], boundary["vector"], boundary["modeled"]), ("interrupt", 0x21, True))
49
+ returned = next(e for e in path["events"] if e["kind"] == "call-return")
50
+ self.assertEqual((returned["callSite"], returned["boundary"], returned["vector"]), (0, "interrupt", 0x21))
51
+ self.assertTrue(returned["modeled"] and returned["unknownMemoryEffects"])
52
+ self.assertEqual(returned["resultContracts"], [])
53
+ entry = path["conditionalModels"][returned["conditionalModel"]]
54
+ self.assertEqual((entry["site"], entry["boundary"], entry["vector"]), (0, "interrupt", 0x21))
55
+ self.assertTrue(entry["assumption"].startswith("interrupt returns to the next instruction"))
56
+ self.assertEqual(entry["preservedMemoryScopes"], [])
57
+ # Unpreserved registers come back unknown, and SP is as before the interrupt.
58
+ self.assertIsNone(path["registers"]["bx"]["value"])
59
+ self.assertEqual(path["registers"]["sp"]["value"], FRAME["sp"])
60
+ self.assertEqual(r["hardwareBoundaries"][0]["placement"], "everyTracedPath")
61
+ summary = r["effectOrdering"]["paths"][0]
62
+ self.assertEqual(len(summary["hardwareBoundaryOrders"]), 1)
63
+ self.assertEqual(summary["calls"], [])
64
+ self.assertFalse(summary["effectCompleteWithinModel"])
65
+ self.assertEqual(r["effectOrdering"]["nativeReachability"], "unconfirmed")
66
+
67
+ def test_without_a_model_the_interrupt_still_stops_the_path(self):
68
+ c, service = wrapper_case()
69
+ for models in ([], [model(c.labels["first"])]):
70
+ r = report(c, registers=FRAME, callModels=models)
71
+ self.assertEqual(r["paths"][0]["stop"], "interrupt handler is not modeled; later effects are not read")
72
+
73
+ def test_a_model_at_int3_into_or_a_pe32_interrupt_is_not_consumed(self):
74
+ unmodeled = "interrupt handler is not modeled; later effects are not read"
75
+ # INT 1 and INT 3 written as INT n are the same debug traps as INT1 and INT3.
76
+ for code, stop in (("cc c3", unmodeled), ("f1 c3", unmodeled), ("cd 03 c3", unmodeled), ("cd 01 c3", unmodeled),
77
+ ("ce c3", "Unsupported instruction semantics: into")):
78
+ r = report(code, registers=FRAME, callModels=[model(0)])
79
+ self.assertEqual(r["paths"][0]["stop"], stop, code)
80
+ self.assertEqual(r["paths"][0]["conditionalModels"], [])
81
+ r = flat_report(FlatCode().emit("cd 2e c3"), callModels=[model(CODE_RAW)])
82
+ self.assertFalse(r["paths"][0]["returned"])
83
+ self.assertEqual(r["paths"][0]["conditionalModels"], [])
84
+
85
+ def test_an_interrupt_model_rejects_return_bytes(self):
86
+ for width in (2, 4):
87
+ with self.assertRaisesRegex(ValueError, "interrupt model takes no returnBytes"):
88
+ report("cd 21 c3", registers=FRAME, callModels=[model(0, returnBytes=width)])
89
+
90
+ def test_a_scope_that_does_not_resolve_stops_with_the_boundary_unmodeled(self):
91
+ scope = {"segment": "ds", "base": "si", "bytes": 2, "evidence": "synthetic scope"}
92
+ r = report("cd 21 c3", registers={"ss": 0x3000, "sp": 0xff00},
93
+ callModels=[model(0, preserves=["ds", "ss"], preservesMemory=[scope])])
94
+ path = r["paths"][0]
95
+ self.assertTrue(path["stop"].startswith("preservesMemory address unresolved"))
96
+ boundary = next(e for e in path["events"] if e["kind"] == "hardware-boundary")
97
+ self.assertEqual((boundary["vector"], "modeled" in boundary), (0x21, False))
98
+ self.assertEqual(path["conditionalModels"], [])
99
+
100
+ def test_leaves_flags_keeps_the_interrupts_flags_word_for_a_later_popf(self):
101
+ # int 25h; popf; ret. The service returns with a far return and leaves FLAGS on the stack.
102
+ r = report("cd 25 9d c3", registers=FRAME, callModels=[model(0, leavesFlags=True)])
103
+ path = r["paths"][0]
104
+ self.assertTrue(path["returned"])
105
+ # The POPF takes the word the interrupt left, so the RET finds SP as before the interrupt.
106
+ self.assertEqual(path["registers"]["sp"]["value"], FRAME["sp"])
107
+ self.assertTrue(path["conditionalModels"][0]["assumption"].startswith(
108
+ "interrupt returns to the next instruction with its FLAGS word left on the stack"))
109
+ saved = next(e for e in path["events"] if e["kind"] == "flags-save")
110
+ restored = next(e for e in path["events"] if e["kind"] == "flags-restore")
111
+ self.assertEqual(saved["value"], restored["value"])
112
+ self.assertTrue(restored["intactLocalSnapshot"])
113
+ # Without it, the POPF takes the caller's word and the RET reads past the caller's frame.
114
+ r = report("cd 25 9d c3", registers=FRAME, callModels=[model(0)])
115
+ self.assertEqual(r["paths"][0]["registers"]["sp"]["value"], FRAME["sp"] + 2)
116
+ restored = next(e for e in r["paths"][0]["events"] if e["kind"] == "flags-restore")
117
+ self.assertFalse(restored["intactLocalSnapshot"])
118
+
119
+ def test_leaves_flags_needs_true_on_an_interrupt_model(self):
120
+ for code, value in (("cd 25 c3", 1), ("cd 25 c3", False), ("e8 00 00 c3", True), ("cd 03 c3", True)):
121
+ with self.assertRaisesRegex(ValueError, "leavesFlags must be true"):
122
+ report(code, registers=FRAME, callModels=[model(0, leavesFlags=value)])
123
+
124
+ def test_a_scope_over_the_frame_the_processor_writes_stops_the_path(self):
125
+ def scope(displacement, size):
126
+ return {"segment": "ss", "base": "sp", "displacement": displacement, "bytes": size, "evidence": "synthetic stack scope"}
127
+ # FLAGS, CS and IP of an interrupt fill SS:SP-6..SP-1; a near call's return address fills SS:SP-2..SP-1.
128
+ for code, displacement, size in (("cd 21 c3", -6, 1), ("cd 21 c3", -2, 4), ("e8 00 00 c3", -2, 1), ("e8 00 00 c3", -4, 8)):
129
+ r = report(code, registers=FRAME, callModels=[model(0, preserves=["ss"], preservesMemory=[scope(displacement, size)])])
130
+ path = r["paths"][0]
131
+ self.assertEqual(path["stop"], "preservesMemory scope covers the return frame the processor writes below SP", code)
132
+ self.assertEqual(path["conditionalModels"], [])
133
+ r = report("cd 21 c3", registers=FRAME, callModels=[model(0, preserves=["ss"], preservesMemory=[scope(-6, 1)])])
134
+ boundary = next(e for e in r["paths"][0]["events"] if e["kind"] == "hardware-boundary")
135
+ self.assertNotIn("modeled", boundary)
136
+ # Bytes at and above SP, and below the frame, stay the query's hypothesis.
137
+ for code, displacement in (("cd 21 c3", 0), ("cd 21 c3", -8), ("e8 00 00 c3", 0), ("e8 00 00 c3", -4)):
138
+ r = report(code, registers=FRAME, callModels=[model(0, preserves=["ss"], preservesMemory=[scope(displacement, 2)])])
139
+ self.assertTrue(r["paths"][0]["returned"], (code, displacement))
140
+
141
+ def test_the_path_limit_drops_cases_at_the_interrupt_as_a_gap(self):
142
+ r = report("cd 21 c3", registers=FRAME, maxPaths=1, callModels=[model(0, [{"registers": {"ax": 0}}, {"registers": {"ax": 1}}])])
143
+ self.assertFalse(r["completeWithinModel"])
144
+ self.assertEqual(len(r["paths"]), 0)
145
+ self.assertEqual(r["gaps"], [{"site": 0, "reason": "path limit at modeled interrupt"}])
146
+
147
+ def wrapper_controls(self, c, writer="second"):
148
+ return [control("later store", "lastWriter", at={"site": c.labels["scratch"], "event": "read"}, writers=[c.labels[writer]]),
149
+ control("predicate", "origin", at={"site": c.labels["test"], "event": "compare"}, value={"field": "left"},
150
+ expect={"inputs": {"include": [{"modeledCall": c.labels["int"], "register": "bx"}]}}),
151
+ control("not scratch", "origin", at={"site": c.labels["test"], "event": "compare"}, value={"field": "left"},
152
+ expect={"producers": {"exclude": [c.labels["scratch"]]}})]
153
+
154
+ def test_aliased_outputs_and_the_predicate_source_hold_through_a_modeled_interrupt(self):
155
+ c, service = wrapper_case()
156
+ r = report(c, "effects", registers=FRAME, callModels=[service], relationalControls=self.wrapper_controls(c)[:2])
157
+ self.assertTrue(r["completeWithinModel"])
158
+ self.assertTrue(r["relationalControls"]["allHeld"])
159
+ self.assertEqual(verdict(r, "later store")["verdict"], "held")
160
+ self.assertEqual(verdict(r, "predicate")["verdict"], "held")
161
+ # The service register is an unread input, which may hide any producer, so an exclusion stays open.
162
+ r = report(c, registers=FRAME, callModels=[service], relationalControls=self.wrapper_controls(c)[2:])
163
+ excluded = verdict(r, "not scratch")
164
+ self.assertEqual(excluded["verdict"], "undecided")
165
+ self.assertIn("may be hidden by an unread input", excluded["paths"][0]["occurrences"][0]["reason"])
166
+ # Both stores went through the one far address the caller passed twice.
167
+ stores = [e for e in r["paths"][0]["events"] if e["kind"] == "write" and e["site"] in (c.labels["first"], c.labels["second"])]
168
+ self.assertEqual([(e["segment"]["value"], e["offset"]["value"]) for e in stores], [(0x2000, 0x40)] * 2)
169
+ self.assertEqual(verdict(r, "not scratch")["queryAssumptions"]["callModels"], [c.labels["int"]])
170
+ self.assertEqual(len(r["paths"][0]["conditionalModels"][0]["preservedMemoryScopes"]), 1)
171
+
172
+ def test_supplied_predicate_cases_decide_the_branch_each_way(self):
173
+ c, service = wrapper_case()
174
+ service["cases"] = [{"registers": {"bx": 0, "cx": 5, "dx": 7}}, {"registers": {"bx": 1, "cx": 5, "dx": 7}}]
175
+ r = report(c, registers=FRAME, callModels=[service])
176
+ taken = [next(e["taken"] for e in p["events"] if e["kind"] == "branch") for p in r["paths"]]
177
+ self.assertEqual(sorted(taken), [False, True])
178
+ # A case that supplies BX makes it a constant, so the origin control cannot see the service register.
179
+ r = report(c, registers=FRAME, callModels=[service], relationalControls=self.wrapper_controls(c)[1:2])
180
+ self.assertEqual(verdict(r, "predicate")["verdict"], "undecided")
181
+
182
+ def test_unscoped_wrong_writer_wrong_origin_and_capped_controls_do_not_hold(self):
183
+ c, service = wrapper_case()
184
+ # Without the frame scope the pointers and the return word are lost at the interrupt.
185
+ unscoped = {k: v for k, v in service.items() if k != "preservesMemory"}
186
+ r = report(c, registers=FRAME, callModels=[unscoped], relationalControls=self.wrapper_controls(c)[:2])
187
+ self.assertEqual(r["paths"][0]["stop"], "return target was overwritten or has unknown provenance")
188
+ self.assertEqual(verdict(r, "later store")["verdict"], "undecided")
189
+ self.assertFalse(r["relationalControls"]["allHeld"])
190
+ with self.assertRaisesRegex(ValueError, "later store violated"):
191
+ report(c, registers=FRAME, callModels=[service], relationalControls=self.wrapper_controls(c, "first")[:1])
192
+ # A caller that tests the scratch word instead takes its predicate from the scratch read.
193
+ scratch, service = wrapper_case("f6 c1 01")
194
+ for rule in self.wrapper_controls(scratch)[1:]:
195
+ with self.assertRaisesRegex(ValueError, rule["name"] + " violated"):
196
+ report(scratch, registers=FRAME, callModels=[service], relationalControls=[rule])
197
+ c, service = wrapper_case()
198
+ r = report(c, registers=FRAME, callModels=[service], maxSteps=12, relationalControls=self.wrapper_controls(c)[:2])
199
+ self.assertEqual(r["paths"][0]["stop"], "step limit; loop progress unresolved")
200
+ self.assertEqual(verdict(r, "later store")["verdict"], "undecided")
201
+ self.assertEqual(verdict(r, "predicate")["verdict"], "undecided")
202
+
203
+ def test_an_entry_frame_trace_continues_through_a_modeled_interrupt(self):
204
+ # From the wrapper's entry, the frame trace reaches the code after the interrupt only through the model.
205
+ c, service = wrapper_case()
206
+ regions = [{"name": "synthetic", "start": 0, "end": len(c.bytes()), "ip": 0, "segment": 0x1000, "resident": True,
207
+ "entries": [0, c.labels["wrapper"]], "evidence": "synthetic declared code extent"}]
208
+ after = c.labels["int"] + 2
209
+ regions[0]["entries"].append(after)
210
+ for models, established in (([], False), ([service], True)):
211
+ r = report(c, regions=regions, entry=after, entryFrame={"from": c.labels["wrapper"]},
212
+ registers={"ds": 0x2000, "ss": 0x3000}, callModels=models)
213
+ self.assertEqual(r["entryFrame"]["established"], established)
214
+ if established:
215
+ self.assertEqual((r["entryFrame"]["sp"], r["entryFrame"]["bp"]), (-2, -2))
216
+
217
+
218
+ if __name__ == "__main__":
219
+ unittest.main()
@@ -113,6 +113,25 @@ class OrderTests(unittest.TestCase):
113
113
  with self.assertRaisesRegex(ValueError, "went the other way"):
114
114
  run(self.c, [rule], registers=FRAME)
115
115
 
116
+ def test_an_anchor_on_a_modeled_calls_return_follows_its_callee(self):
117
+ # At the modeled call's own return the callee has run, so it may have produced the before event.
118
+ self.c = (Code().branch("e8", "helper").label("service").branch("e8", "helper").label("use").emit("8a 07 c3")
119
+ .label("helper").emit("85 db").label("test").branch("74", "zero").emit("c3").label("zero").emit("c3"))
120
+ model = [{"site": self.c.labels["service"], "evidence": "synthetic unread helper call", "cases": [{}]}]
121
+ direction = control("direction", "order", before={"site": self.c.labels["test"], "event": "branch"},
122
+ branch={"taken": False}, at={"site": self.c.labels["service"], "event": "call-return"})
123
+ result = verdict(run(self.c, [direction], registers=FRAME, callModels=model), "direction")
124
+ self.assertEqual(result["verdict"], "undecided")
125
+ taken = next(o for p in result["paths"] for o in p["occurrences"] if o["taken"])
126
+ self.assertEqual(taken["modeledCalls"], [self.c.labels["service"]])
127
+ # With the first call modeled, no read event precedes that call's return.
128
+ first = [{**model[0], "site": 0}]
129
+ before = control("first", "order", before={"site": self.c.labels["test"], "event": "branch"},
130
+ at={"site": 0, "event": "call-return"})
131
+ result = verdict(run(self.c, [before], registers=FRAME, callModels=first), "first")
132
+ self.assertEqual(result["verdict"], "undecided")
133
+ self.assertEqual(result["paths"][0]["occurrences"][0]["modeledCalls"], [0])
134
+
116
135
 
117
136
  class LastWriterTests(unittest.TestCase):
118
137
  def cleanup(self):
@@ -407,6 +426,52 @@ class RelationTests(unittest.TestCase):
407
426
  rule = self.appends(16)
408
427
  self.assertEqual(verdict(run(self.c, [rule], visitLimit=8), "capacity")["verdict"], "undecided")
409
428
 
429
+ def test_an_output_count_past_a_modeled_call_is_a_lower_bound(self):
430
+ # The caller runs the append helper twice; the second call may be modeled.
431
+ c = (Code().branch("e8", "append").label("service").branch("e8", "append").label("return").emit("c3")
432
+ .label("append").label("write").emit("88 07 43 c3"))
433
+
434
+ def capacity(n):
435
+ return control("capacity", "relation", at={"site": c.labels["return"], "event": "return"}, op="le",
436
+ left={"occurrences": {"site": c.labels["write"], "event": "write"}}, right=n)
437
+ self.assertEqual(verdict(run(c, [capacity(2)], registers=FRAME), "capacity")["verdict"], "held")
438
+ with self.assertRaisesRegex(ValueError, "capacity violated"):
439
+ run(c, [capacity(1)], registers=FRAME)
440
+ # The modeled call hides the second append, so the path's count of one is only a lower bound.
441
+ model = [{"site": c.labels["service"], "evidence": "synthetic unread helper call", "cases": [{}]}]
442
+ result = verdict(run(c, [capacity(1)], registers=FRAME, callModels=model), "capacity")
443
+ self.assertEqual(result["verdict"], "undecided")
444
+ occurrence = result["paths"][0]["occurrences"][0]
445
+ self.assertIn(f"passed modeled calls at {c.labels['service']}", occurrence["reason"])
446
+ self.assertEqual(occurrence["modeledCalls"], [c.labels["service"]])
447
+ self.assertEqual(occurrence["leftMinusRight"], {"min": 0, "max": None})
448
+ self.assertEqual(result["paths"][0]["modeledCalls"], [c.labels["service"]])
449
+ # The read count already exceeds a capacity of zero, and already meets a minimum of one.
450
+ with self.assertRaisesRegex(ValueError, "capacity violated"):
451
+ run(c, [capacity(0)], registers=FRAME, callModels=model)
452
+ least = control("least", "relation", at={"site": c.labels["return"], "event": "return"}, op="ge",
453
+ left={"occurrences": {"site": c.labels["write"], "event": "write"}}, right=1)
454
+ self.assertEqual(verdict(run(c, [least], registers=FRAME, callModels=model), "least")["verdict"], "held")
455
+ # A congruence needs the exact count.
456
+ parity = control("parity", "relation", at={"site": c.labels["return"], "event": "return"}, op="eq", modulo=1,
457
+ left={"occurrences": {"site": c.labels["write"], "event": "write"}}, right=1)
458
+ result = verdict(run(c, [parity], registers=FRAME, callModels=model), "parity")
459
+ self.assertEqual(result["verdict"], "undecided")
460
+ self.assertIn("lower bound", result["paths"][0]["occurrences"][0]["reason"])
461
+ # The same count on both sides cancels: the hidden events are the same events.
462
+ same = control("same", "relation", at={"site": c.labels["return"], "event": "return"}, op="eq",
463
+ left={"occurrences": {"site": c.labels["write"], "event": "write"}},
464
+ right={"occurrences": {"site": c.labels["write"], "event": "write"}})
465
+ self.assertEqual(verdict(run(c, [same], registers=FRAME, callModels=model), "same")["verdict"], "held")
466
+ # An anchor before the modeled call counts every event up to it, so the count decides there.
467
+ first = control("first", "relation", at={"site": c.labels["write"], "event": "write"}, op="le",
468
+ left={"occurrences": {"site": c.labels["write"], "event": "write"}}, right=1)
469
+ self.assertEqual(verdict(run(c, [first], registers=FRAME, callModels=model), "first")["verdict"], "held")
470
+ # At the modeled call's own return the callee has already run, so its writes may precede the anchor.
471
+ returned = control("returned", "relation", at={"site": c.labels["service"], "event": "call-return"}, op="le",
472
+ left={"occurrences": {"site": c.labels["write"], "event": "write"}}, right=1)
473
+ self.assertEqual(verdict(run(c, [returned], registers=FRAME, callModels=model), "returned")["verdict"], "undecided")
474
+
410
475
  def test_modulo_accepts_only_equality(self):
411
476
  rule = self.terminator("c6 00 00")
412
477
  with self.assertRaisesRegex(ValueError, "modulo"):
@@ -510,6 +575,73 @@ class OriginTests(unittest.TestCase):
510
575
  # Without the case value the call's BX is an unknown input of the value.
511
576
  self.assertEqual(verdict(run(c, [rule], callModels=[{**model, "cases": [{}]}]), "service")["verdict"], "held")
512
577
 
578
+ def reencoding(self):
579
+ # The helper tests its recursive call's AX against FFFF and on a match writes a fresh FFFF;
580
+ # otherwise it returns zero. The recursive call is modeled with the helper's frame kept.
581
+ c = Code().branch("e8", "helper").label("test").emit("83 f8 ff c3")
582
+ c.label("helper").label("recurse").branch("e8", "helper").label("tested").emit("83 f8 ff").label("branch").branch("75", "zero")
583
+ c.label("reencode").emit("b8 ff ff").label("after").branch("eb", "out").label("zero").emit("31 c0").label("out").emit("c3")
584
+ return c
585
+
586
+ def reencoding_query(self, c, controls, case):
587
+ model = {"site": c.labels["recurse"], "evidence": "synthetic recursive return", "preserves": ["ss"],
588
+ "preservesMemory": [{"segment": "ss", "base": "sp", "bytes": 2, "evidence": "synthetic return address"}],
589
+ "cases": [case]}
590
+ checkpoints = [c.labels["after"]] if "after" in c.labels else []
591
+ return run(c, controls, registers={"ss": 0x3000, "sp": 0xff00}, checkpoints=checkpoints,
592
+ returnContracts=self.contracts(c), callModels=[model])
593
+
594
+ def test_a_reencoded_recursive_result_keeps_the_tested_value_the_branch_and_the_local_producer_apart(self):
595
+ c = self.reencoding()
596
+ after = {"site": c.labels["after"], "event": "checkpoint"}
597
+ tested = control("tested", "origin", at={"site": c.labels["tested"], "event": "compare"}, value={"field": "left"},
598
+ expect={"inputs": {"include": [{"modeledCall": c.labels["recurse"], "register": "ax"}]}})
599
+ guarded = control("guarded", "order", at=after, before={"site": c.labels["branch"], "event": "branch"}, branch={"taken": False})
600
+ output = control("output", "origin", at=after, value={"field": "registers.ax"},
601
+ expect={"producers": {"include": [c.labels["reencode"]]}})
602
+ copied = control("copied", "origin", at=after, value={"field": "registers.ax"},
603
+ expect={"inputs": {"include": [{"modeledCall": c.labels["recurse"], "register": "ax"}]}})
604
+ # With the recursive AX unknown, the tested value is the recursive result.
605
+ open_result = self.reencoding_query(c, [tested, guarded, output], {})
606
+ self.assertEqual(verdict(open_result, "tested")["verdict"], "held")
607
+ # The mismatching path passes the modeled recursion without reaching the checkpoint, so
608
+ # controls anchored there stay undecided in this query.
609
+ for name in ("guarded", "output"):
610
+ self.assertEqual(verdict(open_result, name)["verdict"], "undecided", name)
611
+ # The fresh encoding does not carry the recursive value.
612
+ with self.assertRaisesRegex(ValueError, rf"copied violated .* at site {c.labels['after']} .*not among the value's inputs"):
613
+ self.reencoding_query(c, [copied], {})
614
+ # With the encoding supplied, the re-encoding follows the match and its own write produced the output.
615
+ # sameValue holds as well, since the tested value and the fresh constant are the same number.
616
+ same = control("same", "order", at=after, before={"site": c.labels["tested"], "event": "compare"},
617
+ sameValue={"before": "left", "at": "registers.ax"})
618
+ supplied = self.reencoding_query(c, [tested, guarded, output, copied, same], {"registers": {"ax": 0xffff}})
619
+ for name in ("guarded", "output", "same"):
620
+ self.assertEqual(verdict(supplied, name)["verdict"], "held", name)
621
+ for name in ("tested", "copied"):
622
+ self.assertEqual(verdict(supplied, name)["verdict"], "undecided", name)
623
+ # The caller's test reaches the helper's own return as the originating one; the modeled
624
+ # recursive return is not among the returns the value came through.
625
+ caller = control("caller", "origin", at={"site": c.labels["test"], "event": "compare"}, value={"field": "left"},
626
+ expect={"originatingReturns": {"entries": [c.labels["helper"]]}, "producers": {"include": [c.labels["reencode"]]}})
627
+ result = verdict(self.reencoding_query(c, [caller], {"registers": {"ax": 0xffff}}), "caller")
628
+ self.assertEqual(result["verdict"], "held")
629
+ returns = result["paths"][0]["occurrences"][0]["returns"]
630
+ self.assertEqual([(r["site"], r["originating"], r["modeled"]) for r in returns], [(c.labels["out"], True, False)])
631
+
632
+ def test_originating_returns_hold_when_a_modeled_recursive_return_supplies_the_value(self):
633
+ # The helper copies its modeled recursive call's AX up unchanged. The modeled return belongs
634
+ # to the helper too, so only the returns' modeled field tells it from the helper's own return.
635
+ c = Code().branch("e8", "helper").label("test").emit("83 f8 ff c3")
636
+ c.label("helper").label("recurse").branch("e8", "helper").label("out").emit("c3")
637
+ caller = control("caller", "origin", at={"site": c.labels["test"], "event": "compare"}, value={"field": "left"},
638
+ expect={"originatingReturns": {"entries": [c.labels["helper"]]}})
639
+ result = verdict(self.reencoding_query(c, [caller], {"registers": {"ax": 0xffff}}), "caller")
640
+ self.assertEqual(result["verdict"], "held")
641
+ returns = result["paths"][0]["occurrences"][0]["returns"]
642
+ self.assertEqual([(r["site"], r["originating"], r["modeled"]) for r in returns],
643
+ [(c.labels["recurse"], True, True), (c.labels["out"], False, False)])
644
+
513
645
  def test_originating_returns_need_a_return_contract(self):
514
646
  c = self.recursion()
515
647
  with self.assertRaisesRegex(ValueError, "needs a returnContracts declaration"):