scientific-method-engine 9.1.0__tar.gz → 10.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/PKG-INFO +9 -1
  2. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/README.md +8 -0
  3. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/effect_order.py +1 -1
  5. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/image.py +55 -3
  6. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/relational.py +51 -3
  7. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/reports.py +5 -2
  8. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/trace.py +72 -3
  9. scientific_method_engine-10.1.0/tests/test_indirect_far_transfers.py +351 -0
  10. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_oracle.py +19 -0
  11. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_relational_controls.py +89 -0
  12. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/.gitignore +0 -0
  13. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/LICENSE +0 -0
  14. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/__init__.py +0 -0
  15. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/__main__.py +0 -0
  16. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/cli.py +0 -0
  17. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  18. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  19. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  20. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  21. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  22. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  23. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  24. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  25. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  26. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  27. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  28. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  29. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  30. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  31. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  32. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  33. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  34. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  35. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  36. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  37. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  38. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  39. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  40. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  41. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  42. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  43. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  44. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  45. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  46. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  47. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  48. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  49. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  50. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  51. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  52. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/loops.py +0 -0
  53. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/machine.py +0 -0
  54. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  55. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  56. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  57. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
  58. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  59. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/src/scientific_method_engine/x86/values.py +0 -0
  60. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/oracle.py +0 -0
  61. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_continuation_budget.py +0 -0
  62. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_dispatch.py +0 -0
  63. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_effect_order.py +0 -0
  64. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_entry_frame.py +0 -0
  65. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_interrupt_models.py +0 -0
  66. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_loops.py +0 -0
  67. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_memory_scopes.py +0 -0
  68. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_nested_frame_request.py +0 -0
  69. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_pe.py +0 -0
  70. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_successor_rule.py +0 -0
  71. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_table_continuations.py +0 -0
  72. {scientific_method_engine-9.1.0 → scientific_method_engine-10.1.0}/tests/test_x86.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 9.1.0
3
+ Version: 10.1.0
4
4
  Summary: Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code.
5
5
  Project-URL: Source, https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine
6
6
  Author: kibertoad
@@ -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 far call or jump through an `m16:16` pointer is followed when the path stored both words and
149
+ the address names declared code through one region's exact mapping, or names a source FBOV
150
+ trampoline whose overlay entry is declared. The event keeps the pointer read, each word's
151
+ producers and writers, and how the target was admitted. An unknown or partly unknown word, an
152
+ address outside declared code, a segment alias of resident code, an overlay's analysis segment and
153
+ an `m16:32` pointer stop the path with a named reason. See
154
+ [indirect far transfers](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#indirect-far-transfers-through-a-traced-pointer).
155
+
148
156
  A call model may also sit at an `INT n` instruction in the real-mode model. The interrupt is
149
157
  still reported as a hardware boundary with its vector, the handler is not executed, and each case
150
158
  returns to the next instruction with SP and CS as before the interrupt. Registers, flags and memory
@@ -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 far call or jump through an `m16:16` pointer is followed when the path stored both words and
133
+ the address names declared code through one region's exact mapping, or names a source FBOV
134
+ trampoline whose overlay entry is declared. The event keeps the pointer read, each word's
135
+ producers and writers, and how the target was admitted. An unknown or partly unknown word, an
136
+ address outside declared code, a segment alias of resident code, an overlay's analysis segment and
137
+ an `m16:32` pointer stop the path with a named reason. See
138
+ [indirect far transfers](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#indirect-far-transfers-through-a-traced-pointer).
139
+
132
140
  A call model may also sit at an `INT n` instruction in the real-mode model. The interrupt is
133
141
  still reported as a hardware boundary with its vector, the handler is not executed, and each case
134
142
  returns to the next instruction with SP and CS as before the interrupt. Registers, flags and memory
@@ -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 = "9.1.0"
8
+ version = "10.1.0"
9
9
  description = "Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code."
10
10
  readme = "README.md"
11
11
  requires-python = ">=3.12"
@@ -4,7 +4,7 @@ from bisect import bisect_right
4
4
  from .memory_scopes import model_scopes, without_scopes
5
5
 
6
6
 
7
- KINDS = {"read", "write", "call", "call-return", "return", "branch", "compare", "flag-assumption",
7
+ KINDS = {"read", "write", "call", "far-jump", "call-return", "return", "branch", "compare", "flag-assumption",
8
8
  "arithmetic", "value-transfer", "conversion", "flag-write", "flags-save", "flags-restore", "local-iret", "string-operation", "declared-jump-continuation",
9
9
  "hardware-boundary"}
10
10
 
@@ -3,6 +3,7 @@ import re
3
3
  from pathlib import Path
4
4
  import xxhash
5
5
  from capstone import Cs, CS_ARCH_X86, CS_MODE_16, CS_MODE_32
6
+ from capstone.x86 import X86_OP_MEM
6
7
  from .pe import prepare_pe
7
8
  import capstone
8
9
 
@@ -109,6 +110,8 @@ class Image:
109
110
  self.decoder = Cs(CS_ARCH_X86, CS_MODE_32 if self.flat else CS_MODE_16)
110
111
  self.decoder.detail = True
111
112
  self.cache = {}
113
+ # overlayExports rows by trampoline site, built on the first far_pointer_target call.
114
+ self.trampoline_rows = None
112
115
  self.relocations = config.get("relocations", [])
113
116
  if not isinstance(self.relocations, list) or len(self.relocations) > 100000:
114
117
  raise ValueError("Invalid relocation metadata")
@@ -125,10 +128,13 @@ class Image:
125
128
  def region(self, site):
126
129
  return next((r for r in self.regions if r["start"] <= site < r["end"]), None)
127
130
 
131
+ def mapped_region(self, segment, ip):
132
+ """The region whose declared mapping covers ``segment:ip`` exactly, or None. At most one does."""
133
+ return next((r for r in self.regions if r["segment"] == segment and r["ip"] <= ip < r["ip"] + r["end"] - r["start"]), None)
134
+
128
135
  def offset(self, segment, ip):
129
- exact = [r for r in self.regions if r["segment"] == segment and r["ip"] <= ip < r["ip"] + r["end"] - r["start"]]
130
- if exact:
131
- r = exact[0]
136
+ r = self.mapped_region(segment, ip)
137
+ if r is not None:
132
138
  return r["start"] + ip - r["ip"]
133
139
  if self.flat:
134
140
  return None
@@ -157,6 +163,10 @@ class Image:
157
163
  def far_target(self, site, ins):
158
164
  if self.flat:
159
165
  return None, {"reason": "far transfer is outside the PE32 flat model"}
166
+ if ins.operands and ins.operands[0].type == X86_OP_MEM:
167
+ # The pointer is read from memory when the instruction runs; only a traced path knows it
168
+ # (far_pointer_target).
169
+ return None, {"reason": "computed transfer remains unresolved"}
160
170
  # ptr16:16 immediate only. Operand-size-prefixed far calls are unsupported.
161
171
  if ins.size != 5 or self.data[site] not in (0x9a, 0xea):
162
172
  return None, {"reason": "unsupported far transfer encoding"}
@@ -170,6 +180,48 @@ class Image:
170
180
  target = integer(fixup["target"], 0, len(self.data) - 1, "canonical target")
171
181
  return target, {"rawSegment": raw, "offset": ip, "resolvedSegment": fixup["segment"], "relocation": fixup}
172
182
 
183
+ def far_pointer_target(self, segment, offset):
184
+ """The code a known ``segment:offset`` far pointer names, as ``(target, admission)``.
185
+
186
+ The pointer is admitted only through the exact declared mapping of one region: ``segment``
187
+ equals the region's segment and ``offset`` lies in its IP range. A region with a
188
+ ``container`` is an overlay's analysis view, whose segment is not a load address, so a
189
+ pointer that names it is refused. So is a pointer that reaches declared resident code only
190
+ through another segment (a canonical alias), because the code would then run under a CS
191
+ and IP the region's mapping does not describe. A pointer at a source FBOV trampoline
192
+ (``overlayExports``) continues at that trampoline's overlay entry, as an immediate far
193
+ transfer through a relocated trampoline does. Returns ``(None, {"reason": ...})`` when the
194
+ pointer is not admitted.
195
+ """
196
+ region = self.mapped_region(segment, offset)
197
+ if region is None:
198
+ if self.offset(segment, offset) is not None:
199
+ return None, {"reason": "far pointer names declared resident code only through a segment alias of its mapping"}
200
+ return None, {"reason": "far pointer names no declared code region"}
201
+ if region.get("container") is not None:
202
+ return None, {"reason": "far pointer names overlay code by its analysis segment, which is not a load address",
203
+ "region": region["name"]}
204
+ site = region["start"] + offset - region["ip"]
205
+ admission = {"rule": "exact declared region mapping", "region": region["name"], "regionSegment": region["segment"],
206
+ "regionIp": region["ip"], "regionStart": region["start"], "regionEvidence": region["evidence"]}
207
+ if self.trampoline_rows is None:
208
+ # Indexed once: a traced path can take many indirect far transfers, and the source FBOV
209
+ # tables can list thousands of trampolines.
210
+ self.trampoline_rows = {}
211
+ for row in self.config.get("overlayExports", []):
212
+ if isinstance(row, dict):
213
+ self.trampoline_rows.setdefault(row.get("trampoline"), []).append(row)
214
+ exports = self.trampoline_rows.get(site, [])
215
+ if not exports:
216
+ return site, admission
217
+ if len(exports) > 1 or type(exports[0].get("entry")) is not int:
218
+ return None, {**admission, "reason": "far pointer names an FBOV trampoline without one overlay entry"}
219
+ export = exports[0]
220
+ admission["trampoline"] = {k: export.get(k) for k in ("trampoline", "descriptor", "entry", "evidence")}
221
+ if self.region(export["entry"]) is None:
222
+ return None, {**admission, "reason": "the overlay entry the FBOV trampoline names lies outside declared code regions"}
223
+ return export["entry"], admission
224
+
173
225
  def file_offset(self, va, width=1):
174
226
  """Only loaded raw PE bytes; zero-fill and alignment padding are not source extents."""
175
227
  metadata = self.config.get("peMetadata")
@@ -293,14 +293,55 @@ HIDDEN = "hidden-occurrences"
293
293
 
294
294
 
295
295
  def _atom_range(atom, ranges):
296
- if atom in ranges:
297
- return ranges[atom]
298
296
  if atom[0] == HIDDEN:
299
297
  return 0, inf
300
298
  if atom[0] == "signed":
301
299
  half = 1 << (atom[2] - 1)
302
300
  return -half, half - 1
303
- return 0, (1 << atom[1]) - 1
301
+ return _unsigned(atom[0], atom[1], ranges)
302
+
303
+
304
+ def _unsigned(term, bits, ranges):
305
+ """Bounds on the term's unsigned value at its width, read from bitwise structure and assumptions.
306
+
307
+ An assumed range, a constant, ``and``, ``or``, ``xor``, a shift right or division by a constant
308
+ (an arithmetic shift only when its operand's sign bit is clear), a remainder by a constant, a zero extension or an extracted field narrows the width's full
309
+ range; any other term keeps it.
310
+ """
311
+ if (term, bits) in ranges:
312
+ return ranges[(term, bits)]
313
+ top = (1 << bits) - 1
314
+ tag = term[0]
315
+ if tag == "constant":
316
+ return term[1] & top, term[1] & top
317
+ if tag in ("and", "or", "xor"):
318
+ (alo, ahi), (blo, bhi) = _unsigned(term[1], bits, ranges), _unsigned(term[2], bits, ranges)
319
+ if tag == "and":
320
+ return 0, min(ahi, bhi)
321
+ # Neither operand sets a bit above its own highest bit; OR keeps every bit of each operand.
322
+ return max(alo, blo) if tag == "or" else 0, (1 << max(ahi, bhi).bit_length()) - 1
323
+ if tag in ("shr", "sar", "udiv", "umod") and term[2][0] == "constant":
324
+ lo, hi = _unsigned(term[1], bits, ranges)
325
+ k = term[2][1] & top
326
+ if tag == "sar" and hi >> (bits - 1):
327
+ # An operand that may have its sign bit set shifts ones in from the top.
328
+ return 0, top
329
+ if tag in ("shr", "sar"):
330
+ # With the sign bit clear, an arithmetic shift right is the logical one.
331
+ # Shift terms carry x86's five-bit count mask; a count the mask changes keeps only the upper bound.
332
+ s = k & 31
333
+ return lo >> s if s == k else 0, hi >> s
334
+ if k == 0:
335
+ return 0, top
336
+ return (lo // k, hi // k) if tag == "udiv" else (0, min(hi, k - 1))
337
+ if tag == "zeroExtend" and term[3] == bits:
338
+ return _unsigned(term[1], term[2], ranges)
339
+ if tag == "extract" and term[3] == bits:
340
+ lo, hi = _unsigned(term[1], term[4], ranges)
341
+ low = term[2]
342
+ if hi >> low <= top:
343
+ return lo >> low, hi >> low
344
+ return 0, top
304
345
 
305
346
 
306
347
  def _interval(form, ranges):
@@ -529,6 +570,13 @@ def _ranges(control, path, anchor):
529
570
  if a["max"] >= 1 << atom[1]:
530
571
  raise ValueError(f"Relational control {control['name']} assumption range exceeds the value's width")
531
572
  ranges[atom] = (a["min"], a["max"])
573
+ # The assumed value's own expression may bound it too: keep the narrower range, and refuse an
574
+ # assumption the expression rules out, since a relation would hold over an empty range.
575
+ for atom, (lo, hi) in list(ranges.items()):
576
+ slo, shi = _unsigned(atom[0], atom[1], {k: v for k, v in ranges.items() if k != atom})
577
+ if lo > shi or hi < slo:
578
+ raise _Unresolved(f"the assumed range {lo}..{hi} is outside the range {slo}..{shi} the value's expression allows here")
579
+ ranges[atom] = max(lo, slo), min(hi, shi)
532
580
  return ranges
533
581
 
534
582
 
@@ -1770,16 +1770,19 @@ def _run_report(image, config, command):
1770
1770
  if command == "returns":
1771
1771
  report = return_flows(report, config)
1772
1772
  if command != "trace":
1773
- kinds = {"arguments": ("address-formation", "read", "call", "call-return"), "effects": ("address-formation", "write", "call", "call-return", "return", "branch", "string-operation", "hardware-boundary",
1773
+ kinds = {"arguments": ("address-formation", "read", "call", "call-return"), "effects": ("address-formation", "write", "call", "far-jump", "call-return", "return", "branch", "string-operation", "hardware-boundary",
1774
1774
  "flag-assumption", "flag-write", "flags-save", "flags-restore", "local-iret"),
1775
1775
  "returns": ("return", "call-return", "compare", "branch", "write"),
1776
- "guards": ("compare", "branch", "read", "write", "call", "call-return"),
1776
+ "guards": ("compare", "branch", "read", "write", "call", "far-jump", "call-return"),
1777
1777
  "memory": ("read", "write", "address-formation")}[command]
1778
1778
  for path in report["paths"]:
1779
1779
  # Returns keep the transfers, conversions and reads that depend on a declared result.
1780
1780
  consumed = {c["order"] for f in path.get("returnFlows", {}).get("results", ()) for c in f["consumers"]}
1781
1781
  # Arguments keeps the writes its argument-frame slots cite as writers.
1782
1782
  consumed |= {s["writerOrder"] for f in path.get("argumentFrames", ()) for s in f["slots"] if s["writerSite"] is not None}
1783
+ # A kept indirect far CALL or JMP keeps the pointer read its provenance cites.
1784
+ consumed |= {e["provenance"]["pointerRead"]["order"] for e in path["events"] if e["kind"] in kinds
1785
+ and isinstance(e.get("provenance"), dict) and "pointerRead" in e["provenance"]}
1783
1786
  path["events"] = [e for e in path["events"] if e["kind"] in kinds or e["order"] in consumed or
1784
1787
  (command == "effects" and e["kind"] == "read" and (e.get("nearPointerAccessCandidates") or e.get("nearPointerArgumentCandidates")))]
1785
1788
  return report
@@ -6,7 +6,7 @@ from .image import integer
6
6
  from .machine import (State, StopPath, REGISTERS, ALIASES, BRANCH_CONDITIONS, string_instruction,
7
7
  string_count, string_effect, check_string_form, compare_string, repeated, string_width,
8
8
  FLAT_PORT_REASON)
9
- from .values import const, unknown, sources, op, Value
9
+ from .values import const, unknown, sources, op, join
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
@@ -22,6 +22,63 @@ def call_target(image, site, ins):
22
22
  return None, {"reason": "computed transfer remains unresolved"}
23
23
 
24
24
 
25
+ def far_pointer_word(state, read, low):
26
+ """One word of the far pointer ``read`` has just fetched, as ``(row, word)``.
27
+
28
+ ``row`` reports the word's value and the producers and writers of its two bytes. ``word`` is the
29
+ modeled value of those bytes with all their sources, including the markers of declared return
30
+ results that ``producers`` leaves out, or None when a byte has no modeled value.
31
+ """
32
+ rows = read["byteProducers"][low // 8:low // 8 + 2]
33
+ interval = read["interval"]
34
+ seg, base, start = interval["segment"], interval["base"], interval["start"]
35
+ keys = [(seg, base, start + i if seg == ("linear",) else (start + i) % (1 << state.bits))
36
+ for i in (low // 8, low // 8 + 1)]
37
+ word = join([state.memory[key] for key in keys]) if all(key in state.memory for key in keys) else None
38
+ return ({"value": None if word is None else word.number,
39
+ "producers": sorted({p for row in rows for p in row["producers"]}), "bytes": rows}, word)
40
+
41
+
42
+ def far_pointer_transfer(state, image):
43
+ """Resolve an indirect far CALL or JMP from the m16:16 pointer the trace has just read.
44
+
45
+ Called right after ``state.get`` read the operand, so the newest event is that read; any other
46
+ newest event is an engine error, so the provenance never cites the wrong event. Returns
47
+ ``(target, provenance, code_segment)``. ``provenance`` keeps the read's order and address, its
48
+ effective segment register, and both words with the producers and writers of their bytes. The
49
+ target is admitted only when both words are known and ``Image.far_pointer_target`` admits the
50
+ address they form; otherwise ``target`` and ``code_segment`` are None and ``provenance`` names
51
+ the reason. ``code_segment`` is the value CS takes: the segment word with every source of its
52
+ bytes (declared return results included), or the overlay
53
+ entry region's segment when the pointer names an FBOV trampoline.
54
+ """
55
+ read = state.events[-1]
56
+ if read["kind"] != "read" or read["site"] != state.at or read["width"] != 4:
57
+ raise RuntimeError("an indirect far transfer needs its own m16:16 read as the newest event")
58
+ (offset_word, _), (segment_word, segment_value) = far_pointer_word(state, read, 0), far_pointer_word(state, read, 16)
59
+ provenance = {"encoding": "m16:16",
60
+ "pointerRead": {"order": read["order"], "segment": read["segment"], "offset": read["offset"],
61
+ "segmentRegister": read["effectiveSegmentRegister"]},
62
+ "offsetWord": offset_word, "segmentWord": segment_word}
63
+ unknown_words = [name for name, word in (("offset", offset_word), ("segment", segment_word)) if word["value"] is None]
64
+ if unknown_words:
65
+ provenance["reason"] = "far pointer " + " and ".join(unknown_words) + (" words" if len(unknown_words) > 1 else " word") + " unknown"
66
+ return None, provenance, None
67
+ provenance["loadedAddress"] = f"{segment_word['value']:04X}:{offset_word['value']:04X}"
68
+ target, admission = image.far_pointer_target(segment_word["value"], offset_word["value"])
69
+ admission = dict(admission)
70
+ reason = admission.pop("reason", None)
71
+ provenance["admission"] = admission
72
+ if target is None:
73
+ provenance["reason"] = reason
74
+ return None, provenance, None
75
+ if "trampoline" in admission:
76
+ return target, provenance, const(image.region(target)["segment"], 16, state.at)
77
+ # CS keeps every source of the segment word's bytes, so a declared result stored there stays a
78
+ # result origin of CS.
79
+ return target, provenance, segment_value
80
+
81
+
25
82
  OVERLAP_REASON = "overlapping entry-path instructions; boundary unresolved"
26
83
  RETURNS = {"ret": "near return", "retf": "far return", "iret": "interrupt return", "iretd": "interrupt return"}
27
84
  INTERRUPTS = ("int", "int1", "int3", "into")
@@ -806,9 +863,11 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
806
863
  break
807
864
  if m in ("call", "lcall"):
808
865
  target, provenance = call_target(image, at, ins)
809
- indirect_value = None
866
+ indirect_value = code_segment = None
810
867
  if target is None and ins.operands and ins.operands[0].type in (X86_OP_REG, X86_OP_MEM):
811
868
  indirect_value = state.get(ins, ins.operands[0], image)
869
+ if m == "lcall":
870
+ target, provenance, code_segment = far_pointer_transfer(state, image)
812
871
  guard_checks = []
813
872
  if indirect_value is not None:
814
873
  for g in state.guards:
@@ -874,7 +933,8 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
874
933
  "continuation": following, "returnIP": return_ip, "callSite": at,
875
934
  "callerCS": state.reg("cs"), "localFlagsFrame": flags_frame})
876
935
  if m == "lcall":
877
- state.setreg("cs", const(target_region["segment"], 16, at), at)
936
+ # An indirect far call loads CS from the pointer's segment word (far_pointer_transfer).
937
+ state.setreg("cs", const(target_region["segment"], 16, at) if code_segment is None else code_segment, at)
878
938
  state.at = target
879
939
  continue
880
940
  if m in ("iret", "iretd"):
@@ -927,6 +987,15 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
927
987
  continue
928
988
  if m in ("jmp", "ljmp"):
929
989
  target, provenance = call_target(image, at, ins)
990
+ if target is None and m == "ljmp" and ins.operands[0].type == X86_OP_MEM:
991
+ pointer = state.get(ins, ins.operands[0], image)
992
+ target, provenance, code_segment = far_pointer_transfer(state, image)
993
+ state.event("far-jump", target=target, provenance=provenance, indirectValue=pointer.report())
994
+ if target is None:
995
+ raise StopPath("unresolved jump: " + provenance["reason"])
996
+ state.setreg("cs", code_segment, at)
997
+ state.at = target
998
+ continue
930
999
  if target is None:
931
1000
  if continue_declared_jumps and at in image.indirect_jumps:
932
1001
  deferred.append(deepcopy(state))
@@ -0,0 +1,351 @@
1
+ """Indirect far CALL and JMP through a traced m16:16 pointer. Synthetic bytes only."""
2
+ import unittest
3
+
4
+ from test_x86 import events
5
+ from scientific_method_engine.x86.reports import run_report
6
+ from scientific_method_engine.x86.trace import walk
7
+ from scientific_method_engine.x86.image import Image
8
+
9
+ # The producer stores an offset and a segment at DS:0200, then calls through them.
10
+ STORE_OFFSET = "c7 06 00 02 30 00" # mov word [0200], 0030
11
+ STORE_SEGMENT = "c7 06 02 02 00 10" # mov word [0202], 1000
12
+ CALL = "ff 1e 00 02" # call far [0200]
13
+ JUMP = "ff 2e 00 02" # jmp far [0200]
14
+ TARGETS = 0x30
15
+ # 0030: mov ax, 42; retf 0034: mov ax, 7; retf 0038: mov ax, 42; ret
16
+ TARGET_CODE = "b8 2a 00 cb b8 07 00 cb b8 2a 00 c3"
17
+ FRAME = {"ds": 0x1000, "ss": 0x9000}
18
+
19
+
20
+ def program(*parts):
21
+ producer = bytes.fromhex(" ".join(parts))
22
+ assert len(producer) <= TARGETS
23
+ return producer + bytes(TARGETS - len(producer)) + bytes.fromhex(TARGET_CODE), len(producer)
24
+
25
+
26
+ def regions(data, producer_end, resident=None):
27
+ rows = [{"name": "producer", "start": 0, "end": producer_end, "ip": 0, "segment": 0x1000, "entries": [0],
28
+ "evidence": "synthetic producer"},
29
+ {"name": "target", "start": TARGETS, "end": len(data), "ip": TARGETS, "segment": 0x1000,
30
+ "entries": [TARGETS], "evidence": "synthetic declared target"}]
31
+ if resident is not None:
32
+ for row in rows:
33
+ row["resident"] = resident
34
+ return rows
35
+
36
+
37
+ def run(*parts, command="trace", resident=None, **extra):
38
+ data, end = program(*parts)
39
+ config = {"regions": regions(data, end, resident), "entry": 0, "registers": {**FRAME, **extra.pop("registers", {})},
40
+ "maxSteps": 32, "maxPaths": 2, "totalSteps": 64, "visitLimit": 4, **extra}
41
+ return run_report(data, config, command)
42
+
43
+
44
+ def site(*parts):
45
+ return len(bytes.fromhex(" ".join(parts)))
46
+
47
+
48
+ def only_path(test, result):
49
+ test.assertEqual(len(result["paths"]), 1)
50
+ return result["paths"][0]
51
+
52
+
53
+ class FollowedPointer(unittest.TestCase):
54
+ def test_produced_pointer_enters_the_declared_target_and_returns(self):
55
+ result = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3", command="guards")
56
+ path = only_path(self, result)
57
+ self.assertTrue(path["returned"], path["stop"])
58
+ self.assertTrue(result["completeWithinModel"])
59
+ self.assertEqual(path["registers"]["ax"]["value"], 42)
60
+ call = events(result, "call")[0]
61
+ self.assertEqual(call["site"], 12)
62
+ self.assertEqual(call["target"], TARGETS)
63
+ self.assertEqual(call["returnFrameBytes"], 4)
64
+ self.assertEqual(call["indirectValue"]["value"], 0x10000030)
65
+ provenance = call["provenance"]
66
+ self.assertEqual(provenance["encoding"], "m16:16")
67
+ self.assertEqual(provenance["loadedAddress"], "1000:0030")
68
+ self.assertEqual((provenance["offsetWord"]["value"], provenance["offsetWord"]["producers"]), (0x30, [0]))
69
+ self.assertEqual((provenance["segmentWord"]["value"], provenance["segmentWord"]["producers"]), (0x1000, [6]))
70
+ self.assertEqual([row["writeOrder"] for row in provenance["offsetWord"]["bytes"] + provenance["segmentWord"]["bytes"]],
71
+ [0, 0, 1, 1])
72
+ self.assertEqual(provenance["pointerRead"]["segmentRegister"], "ds")
73
+ self.assertEqual(provenance["pointerRead"]["offset"]["value"], 0x200)
74
+ self.assertEqual(provenance["admission"], {"rule": "exact declared region mapping", "region": "target",
75
+ "regionSegment": 0x1000, "regionIp": TARGETS, "regionStart": TARGETS,
76
+ "regionEvidence": "synthetic declared target"})
77
+ self.assertNotIn("reason", provenance)
78
+ # The read that fetched the pointer is the event the provenance cites.
79
+ read = next(e for e in path["events"] if e["order"] == provenance["pointerRead"]["order"])
80
+ self.assertEqual((read["kind"], read["width"]), ("read", 4))
81
+ returned = [e for e in path["events"] if e["kind"] == "call-return"]
82
+ self.assertEqual([(e["callSite"], e["modeled"]) for e in returned], [(12, False)])
83
+
84
+ def test_callee_runs_under_the_segment_word_and_the_far_return_restores_cs(self):
85
+ result = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3")
86
+ path = only_path(self, result)
87
+ inner = next(e for e in path["events"] if e["kind"] == "return" and e["depth"] == 1)
88
+ self.assertEqual(inner["registers"]["cs"]["value"], 0x1000)
89
+ self.assertIn(6, inner["registers"]["cs"]["producers"])
90
+ self.assertEqual(path["registers"]["cs"]["value"], 0x1000)
91
+
92
+ def test_overwriting_the_offset_word_changes_the_target(self):
93
+ rewrite = "c7 06 00 02 34 00"
94
+ result = run(STORE_OFFSET, STORE_SEGMENT, rewrite, CALL, "c3")
95
+ path = only_path(self, result)
96
+ self.assertTrue(path["returned"], path["stop"])
97
+ self.assertEqual(path["registers"]["ax"]["value"], 7)
98
+ call = events(result, "call")[0]
99
+ self.assertEqual(call["target"], 0x34)
100
+ self.assertEqual(call["provenance"]["offsetWord"]["producers"], [12])
101
+ self.assertEqual(call["provenance"]["segmentWord"]["producers"], [6])
102
+
103
+ def test_overwriting_the_segment_word_with_an_undeclared_segment_stops(self):
104
+ rewrite = "c7 06 02 02 00 20"
105
+ result = run(STORE_OFFSET, STORE_SEGMENT, rewrite, CALL, "c3")
106
+ path = only_path(self, result)
107
+ self.assertFalse(path["returned"])
108
+ self.assertEqual(path["stop"], "unresolved call: far pointer names no declared code region")
109
+ call = events(result, "call")[0]
110
+ self.assertIsNone(call["target"])
111
+ self.assertEqual(call["provenance"]["loadedAddress"], "2000:0030")
112
+ self.assertEqual(call["provenance"]["segmentWord"]["producers"], [12])
113
+ self.assertFalse(result["completeWithinModel"])
114
+
115
+ def test_effective_segment_override_is_kept(self):
116
+ # mov word es:[0200], 0030 / mov word es:[0202], 1000 / call far es:[0200]
117
+ result = run("26 c7 06 00 02 30 00", "26 c7 06 02 02 00 10", "26 ff 1e 00 02", "c3", registers={"es": 0x1000, "ds": 0x5000})
118
+ path = only_path(self, result)
119
+ self.assertTrue(path["returned"], path["stop"])
120
+ self.assertEqual(events(result, "call")[0]["provenance"]["pointerRead"]["segmentRegister"], "es")
121
+
122
+ def test_pointer_built_from_registers_by_instructions_is_followed(self):
123
+ # mov ax, 0030 / mov [0200], ax / mov ax, 1000 / mov [0202], ax / call far [0200]
124
+ result = run("b8 30 00", "a3 00 02", "b8 00 10", "a3 02 02", CALL, "c3")
125
+ path = only_path(self, result)
126
+ self.assertTrue(path["returned"], path["stop"])
127
+ provenance = events(result, "call")[0]["provenance"]
128
+ self.assertEqual(provenance["offsetWord"]["producers"], [0, 3])
129
+ self.assertEqual(provenance["segmentWord"]["producers"], [6, 9])
130
+
131
+
132
+ class StoppedPointer(unittest.TestCase):
133
+ def assert_stopped(self, result, reason):
134
+ path = only_path(self, result)
135
+ self.assertFalse(path["returned"])
136
+ self.assertEqual(path["stop"], reason)
137
+ self.assertFalse(result["completeWithinModel"])
138
+ self.assertFalse([e for e in path["events"] if e["depth"] > 0], "the target must not be entered")
139
+ call = [e for e in path["events"] if e["kind"] in ("call", "far-jump")][-1]
140
+ self.assertIsNone(call["target"])
141
+ return call["provenance"]
142
+
143
+ def test_unknown_pointer_stays_stopped(self):
144
+ provenance = self.assert_stopped(run(CALL, "c3"), "unresolved call: far pointer offset and segment words unknown")
145
+ self.assertEqual({row["unwritten"]["cause"] for w in ("offsetWord", "segmentWord") for row in provenance[w]["bytes"]},
146
+ {"no write on this path"})
147
+ self.assertNotIn("loadedAddress", provenance)
148
+
149
+ def test_partly_unknown_pointer_stays_stopped(self):
150
+ self.assert_stopped(run(STORE_OFFSET, CALL, "c3"), "unresolved call: far pointer segment word unknown")
151
+ self.assert_stopped(run(STORE_SEGMENT, CALL, "c3"), "unresolved call: far pointer offset word unknown")
152
+ # One byte of the segment word stored: the word is still unknown.
153
+ self.assert_stopped(run(STORE_OFFSET, "c6 06 02 02 00", CALL, "c3"), "unresolved call: far pointer segment word unknown")
154
+
155
+ def test_alias_invalidated_pointer_stays_stopped(self):
156
+ # mov word es:[di], 0 with ES and DI unknown may store over the pointer.
157
+ provenance = self.assert_stopped(run(STORE_OFFSET, STORE_SEGMENT, "26 c7 05 00 00", CALL, "c3"),
158
+ "unresolved call: far pointer offset and segment words unknown")
159
+ causes = {row["unwritten"]["cause"] for w in ("offsetWord", "segmentWord") for row in provenance[w]["bytes"]}
160
+ self.assertEqual(causes, {"dropped by a possibly aliasing write"})
161
+
162
+ def test_pointer_dropped_by_a_modeled_call_stays_stopped(self):
163
+ # A modeled call between the stores and the transfer forgets memory.
164
+ parts = (STORE_OFFSET, STORE_SEGMENT, "e8 00 00", CALL, "c3")
165
+ model = [{"site": 12, "evidence": "synthetic modeled service", "cases": [{}]}]
166
+ result = run(*parts, callModels=model)
167
+ provenance = self.assert_stopped(result, "unresolved call: far pointer offset and segment words unknown")
168
+ self.assertEqual({row["unwritten"]["cause"] for row in provenance["offsetWord"]["bytes"]}, {"dropped by a modeled call"})
169
+
170
+ def test_target_outside_declared_regions_stays_stopped(self):
171
+ # 1000:0020 lies between the two declared regions.
172
+ provenance = self.assert_stopped(run("c7 06 00 02 20 00", STORE_SEGMENT, CALL, "c3"),
173
+ "unresolved call: far pointer names no declared code region")
174
+ self.assertEqual(provenance["loadedAddress"], "1000:0020")
175
+
176
+ def test_canonical_segment_alias_is_not_followed(self):
177
+ # 1003:0000 is linear 10030, the resident target, but not under the target region's mapping.
178
+ provenance = self.assert_stopped(run("c7 06 00 02 00 00", "c7 06 02 02 03 10", CALL, "c3", resident=True),
179
+ "unresolved call: far pointer names declared resident code only through a segment alias of its mapping")
180
+ self.assertEqual(provenance["loadedAddress"], "1003:0000")
181
+
182
+ def test_overlay_analysis_segment_is_not_a_load_address(self):
183
+ data, end = program(STORE_OFFSET, STORE_SEGMENT, CALL, "c3")
184
+ rows = regions(data, end, resident=True)
185
+ rows[1].update(resident=False, container={"view": "overlay-1", "start": TARGETS, "end": len(data)})
186
+ result = run_report(data, {"regions": rows, "entry": 0, "registers": FRAME}, "trace")
187
+ provenance = self.assert_stopped(
188
+ result, "unresolved call: far pointer names overlay code by its analysis segment, which is not a load address")
189
+ self.assertEqual(provenance["admission"], {"region": "target"})
190
+
191
+ def test_operand_size_override_stays_stopped(self):
192
+ # 66 FF 1E is a far call through m16:32, outside the segmented16 frame model.
193
+ result = run(STORE_OFFSET, STORE_SEGMENT, "66 ff 1e 00 02", "c3")
194
+ path = only_path(self, result)
195
+ self.assertEqual(path["stop"], "Operand-size control transfer override is outside the selected frame model")
196
+ self.assertFalse(events(result, "call"))
197
+
198
+ def test_unknown_jump_pointer_stays_stopped_with_its_event(self):
199
+ provenance = self.assert_stopped(run(STORE_SEGMENT, JUMP), "unresolved jump: far pointer offset word unknown")
200
+ self.assertEqual(provenance["segmentWord"]["value"], 0x1000)
201
+
202
+
203
+ class ModelsAndLimits(unittest.TestCase):
204
+ def test_call_model_at_the_site_keeps_precedence(self):
205
+ model = [{"site": 12, "evidence": "synthetic far service", "cases": [{"registers": {"ax": 5}}]}]
206
+ result = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3", callModels=model)
207
+ path = only_path(self, result)
208
+ self.assertTrue(path["returned"], path["stop"])
209
+ self.assertEqual(path["registers"]["ax"]["value"], 5)
210
+ self.assertEqual(path["conditionalModels"][0]["site"], 12)
211
+ self.assertEqual(events(result, "call")[0]["target"], TARGETS)
212
+ self.assertFalse([e for e in path["events"] if e["depth"] > 0])
213
+
214
+ def test_depth_limit_stops_before_the_target(self):
215
+ result = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3", maxDepth=1)
216
+ path = only_path(self, result)
217
+ self.assertEqual(path["stop"], "call depth limit; recursion or callee remains unresolved")
218
+ self.assertEqual(events(result, "call")[0]["target"], TARGETS)
219
+
220
+ def test_step_limit_inside_the_target_stays_a_stop(self):
221
+ result = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3", maxSteps=4)
222
+ path = only_path(self, result)
223
+ self.assertEqual(path["stop"], "step limit; loop progress unresolved")
224
+ self.assertEqual(path["stopSite"], TARGETS + 3)
225
+
226
+ def test_reach_control_into_the_target_holds_only_when_read(self):
227
+ control = [{"name": "enters", "kind": "reach", "at": {"site": TARGETS}, "expect": "always"}]
228
+ held = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3", relationalControls=control)
229
+ self.assertEqual(held["relationalControls"]["controls"][0]["verdict"], "held")
230
+ for limit in ({"maxDepth": 1}, {"maxSteps": 3}):
231
+ with self.subTest(limit=limit):
232
+ capped = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3", relationalControls=control, **limit)
233
+ self.assertEqual(capped["relationalControls"]["controls"][0]["verdict"], "undecided")
234
+ unknown = run(STORE_OFFSET, CALL, "c3", relationalControls=control)
235
+ self.assertEqual(unknown["relationalControls"]["controls"][0]["verdict"], "undecided")
236
+
237
+
238
+ class FarJump(unittest.TestCase):
239
+ def test_produced_pointer_jump_continues_at_the_target(self):
240
+ result = run("c7 06 00 02 38 00", STORE_SEGMENT, JUMP)
241
+ path = only_path(self, result)
242
+ self.assertTrue(path["returned"], path["stop"])
243
+ self.assertEqual(path["registers"]["ax"]["value"], 42)
244
+ jump = next(e for e in path["events"] if e["kind"] == "far-jump")
245
+ self.assertEqual(jump["target"], 0x38)
246
+ self.assertEqual(jump["provenance"]["loadedAddress"], "1000:0038")
247
+ self.assertEqual(jump["provenance"]["offsetWord"]["producers"], [0])
248
+ self.assertEqual(jump["indirectValue"]["value"], 0x10000038)
249
+
250
+ def test_far_jump_event_reaches_the_guard_and_effect_projections(self):
251
+ for command in ("guards", "effects"):
252
+ with self.subTest(command=command):
253
+ result = run("c7 06 00 02 38 00", STORE_SEGMENT, JUMP, command=command)
254
+ self.assertTrue(events(result, "far-jump"))
255
+
256
+ def test_projections_keep_the_pointer_read_a_kept_transfer_cites(self):
257
+ cases = (("effects", (STORE_OFFSET, STORE_SEGMENT, CALL, "c3"), "call"),
258
+ ("effects", ("c7 06 00 02 38 00", STORE_SEGMENT, JUMP), "far-jump"),
259
+ ("arguments", (STORE_OFFSET, STORE_SEGMENT, CALL, "c3"), "call"))
260
+ for command, parts, kind in cases:
261
+ with self.subTest(command=command, kind=kind):
262
+ path = only_path(self, run(*parts, command=command))
263
+ transfer = next(e for e in path["events"] if e["kind"] == kind)
264
+ order = transfer["provenance"]["pointerRead"]["order"]
265
+ read = [e for e in path["events"] if e["order"] == order]
266
+ self.assertEqual([(e["kind"], e["width"]) for e in read], [("read", 4)])
267
+ # Effects still leaves out reads no kept event cites.
268
+ path = only_path(self, run(STORE_OFFSET, STORE_SEGMENT, "a1 00 02", CALL, "c3", command="effects"))
269
+ self.assertEqual([e["width"] for e in path["events"] if e["kind"] == "read"], [4])
270
+
271
+
272
+ class ResultOrigins(unittest.TestCase):
273
+ # 0000: call 0011; mov [word], ax; mov word [other], const; call far [0200]; ret
274
+ # 0011: mov ax, 1000 or 0030; ret (declared result in AX)
275
+ def run_flow(self, result_word, other_word):
276
+ stored = {"offset": "00 02", "segment": "02 02"}
277
+ other = {"offset": "c7 06 00 02 30 00", "segment": "c7 06 02 02 00 10"}[other_word]
278
+ value = {"offset": "30 00", "segment": "00 10"}[result_word]
279
+ helper = site("e8 0e 00", "a3 " + stored[result_word], other, CALL, "c3")
280
+ self.assertEqual(helper, 0x11)
281
+ return run("e8 0e 00", "a3 " + stored[result_word], other, CALL, "c3", "b8 " + value, "c3", command="trace",
282
+ returnContracts=[{"entry": helper, "register": "ax", "evidence": "synthetic result contract"}])
283
+
284
+ def callee_cs(self, result):
285
+ path = only_path(self, result)
286
+ self.assertTrue(path["returned"], path["stop"])
287
+ return next(e for e in path["events"] if e["kind"] == "return" and e["depth"] == 1 and e["site"] == 0x33)["registers"]["cs"]
288
+
289
+ def test_a_declared_result_stored_as_the_segment_word_is_a_result_origin_of_cs(self):
290
+ cs = self.callee_cs(self.run_flow("segment", "offset"))
291
+ self.assertEqual(cs["value"], 0x1000)
292
+ self.assertTrue(cs.get("resultOrigins"))
293
+
294
+ def test_a_declared_result_stored_as_the_offset_word_is_not(self):
295
+ cs = self.callee_cs(self.run_flow("offset", "segment"))
296
+ self.assertEqual(cs["value"], 0x1000)
297
+ self.assertNotIn("resultOrigins", cs)
298
+
299
+
300
+ class Trampolines(unittest.TestCase):
301
+ def layout(self, entry_declared=True):
302
+ # Resident producer, a resident stub holding an INT 3Fh trampoline at file 0x20, and an
303
+ # overlay whose entry is file 0x30.
304
+ data, end = program("c7 06 00 02 20 00", STORE_SEGMENT, CALL, "c3")
305
+ data = data[:0x20] + bytes.fromhex("cd 3f 00 00") + data[0x24:]
306
+ rows = [{"name": "producer", "start": 0, "end": end, "ip": 0, "segment": 0x1000, "resident": True,
307
+ "entries": [0], "evidence": "synthetic producer"},
308
+ {"name": "stub", "start": 0x20, "end": 0x24, "ip": 0x20, "segment": 0x1000, "resident": True,
309
+ "entries": [0x20], "evidence": "synthetic trampoline stub"}]
310
+ if entry_declared:
311
+ rows.append({"name": "overlay", "start": TARGETS, "end": len(data), "ip": 0, "segment": 0x4000,
312
+ "resident": False, "container": {"view": "overlay-1", "start": TARGETS, "end": len(data)},
313
+ "entries": [TARGETS], "evidence": "synthetic overlay analysis view"})
314
+ exports = [{"descriptor": 1, "trampoline": 0x20, "entry": TARGETS, "codeRange": {"start": TARGETS, "end": len(data)},
315
+ "evidence": "synthetic FBOV descriptor/trampoline"}]
316
+ return run_report(data, {"regions": rows, "entry": 0, "registers": FRAME, "overlayExports": exports}, "trace")
317
+
318
+ def test_pointer_at_a_trampoline_continues_at_its_overlay_entry(self):
319
+ result = self.layout()
320
+ path = only_path(self, result)
321
+ self.assertTrue(path["returned"], path["stop"])
322
+ self.assertEqual(path["registers"]["ax"]["value"], 42)
323
+ call = events(result, "call")[0]
324
+ self.assertEqual(call["target"], TARGETS)
325
+ admission = call["provenance"]["admission"]
326
+ self.assertEqual(admission["region"], "stub")
327
+ self.assertEqual(admission["trampoline"], {"trampoline": 0x20, "descriptor": 1, "entry": TARGETS,
328
+ "evidence": "synthetic FBOV descriptor/trampoline"})
329
+ inner = next(e for e in path["events"] if e["kind"] == "return" and e["depth"] == 1)
330
+ self.assertEqual(inner["registers"]["cs"]["value"], 0x4000)
331
+
332
+ def test_trampoline_entry_outside_declared_regions_stays_stopped(self):
333
+ result = self.layout(entry_declared=False)
334
+ path = only_path(self, result)
335
+ self.assertEqual(path["stop"], "unresolved call: the overlay entry the FBOV trampoline names lies outside declared code regions")
336
+ self.assertEqual(events(result, "call")[0]["provenance"]["admission"]["trampoline"]["entry"], TARGETS)
337
+
338
+
339
+ class StaticWalk(unittest.TestCase):
340
+ def test_walk_names_an_indirect_far_transfer_as_computed(self):
341
+ for transfer in (CALL, JUMP):
342
+ with self.subTest(transfer=transfer):
343
+ data, end = program(transfer, "c3")
344
+ image = Image(data, {"regions": regions(data, end)})
345
+ _, gaps, edges, _, _ = walk(image, [0])
346
+ self.assertIn({"site": 0, "reason": "computed transfer remains unresolved"}, gaps)
347
+ self.assertIsNone(edges[0]["target"])
348
+
349
+
350
+ if __name__ == "__main__":
351
+ unittest.main()
@@ -39,6 +39,25 @@ class AddressForms(unittest.TestCase):
39
39
  check(self, "bb4000 c7073412 c747027856 c41f bb4000 c537 c3", registers=DATA, resolved=("bx", "es", "si", "ds"))
40
40
 
41
41
 
42
+ class FarTransfers(unittest.TestCase):
43
+ """Indirect far CALL and JMP through an m16:16 pointer the routine stores first (code at 1000:0000)."""
44
+ CODE = {"ds": 0x1000}
45
+
46
+ def test_call_far_through_memory(self):
47
+ # The pointer names 1000:0018 (AX=7) and not 1000:0014 (AX=42); the caller adds one after the far return.
48
+ result = check(self, "c7060002 1800 c7060202 0010 ff1e0002 050100 c3 b82a00cb b80700cb",
49
+ registers=self.CODE, resolved=("ax", "sp"))
50
+ self.assertEqual(result["paths"][0]["registers"]["ax"]["value"], 8)
51
+
52
+ def test_call_far_through_a_based_operand_with_a_segment_override(self):
53
+ check(self, "bb0002 26c7071300 26c747020010 26ff1f 40 c3 b82a00cb",
54
+ registers={"es": 0x1000, "ds": 0x3000}, resolved=("ax", "sp"))
55
+
56
+ def test_jmp_far_through_memory(self):
57
+ result = check(self, "c7060002 1000 c7060202 0010 ff2e0002 b82a00c3", registers=self.CODE, resolved=("ax",))
58
+ self.assertEqual(result["paths"][0]["registers"]["ax"]["value"], 42)
59
+
60
+
42
61
  class Stack(unittest.TestCase):
43
62
  def test_push_pop_and_leave(self):
44
63
  check(self, "b81100 50 6a22 5b 59 55 89e5 6a33 c9 c3", resolved=("bx", "cx", "sp"))
@@ -594,6 +594,95 @@ class RelationTests(unittest.TestCase):
594
594
  self.assertEqual(verdict(run(c, [bounded], registers=FRAME), "byte")["verdict"], "held")
595
595
 
596
596
 
597
+ class BitwiseBoundTests(unittest.TestCase):
598
+ """Unsigned bounds read from masks, shifts, division and extracted fields of an unknown loaded word."""
599
+
600
+ def check(self, body, op, right, signed=False, before=""):
601
+ # mov bx,[0200h] (or the body's own load), then the body, then a checkpoint at the return.
602
+ self.c = Code().emit(before).emit(body).label("return").emit("c3")
603
+ left = {"field": "registers.bx", **({"signed": True} if signed else {})}
604
+ rule = control("bound", "relation", at={"site": self.c.labels["return"], "event": "checkpoint"}, op=op, left=left, right=right)
605
+ return verdict(run(self.c, [rule], registers=FRAME), "bound")
606
+
607
+ def test_a_constant_mask_bounds_an_unknown_word(self):
608
+ # and bx,3
609
+ held = self.check("8b 1e 00 02 81 e3 03 00", "le", 3)
610
+ self.assertEqual(held["verdict"], "held")
611
+ self.assertEqual(held["paths"][0]["occurrences"][0]["leftMinusRight"], {"min": -3, "max": 0})
612
+ self.assertEqual(self.check("8b 1e 00 02 81 e3 03 00", "le", 2)["verdict"], "undecided")
613
+ with self.assertRaisesRegex(ValueError, "bound violated"):
614
+ self.check("8b 1e 00 02 81 e3 03 00", "gt", 3)
615
+
616
+ def test_an_unmasked_word_stays_undecided(self):
617
+ self.assertEqual(self.check("8b 1e 00 02", "le", 3)["verdict"], "undecided")
618
+
619
+ def test_a_mask_with_the_sign_bit_leaves_the_signed_value_undecided(self):
620
+ # and bx,8003h: the unsigned value is at most 8003h, while the signed value may be negative.
621
+ self.assertEqual(self.check("8b 1e 00 02 81 e3 03 80", "le", 0x8003)["verdict"], "held")
622
+ self.assertEqual(self.check("8b 1e 00 02 81 e3 03 80", "ge", 0, signed=True)["verdict"], "undecided")
623
+ # With the sign bit masked off, the signed value is the unsigned one.
624
+ self.assertEqual(self.check("8b 1e 00 02 81 e3 03 00", "ge", 0, signed=True)["verdict"], "held")
625
+
626
+ def test_shifts_extracted_fields_and_division_by_constants_bound_the_value(self):
627
+ # shr bx,4
628
+ self.assertEqual(self.check("8b 1e 00 02 c1 eb 04", "le", 0x0fff)["verdict"], "held")
629
+ self.assertEqual(self.check("8b 1e 00 02 c1 eb 04", "le", 0x0ffe)["verdict"], "undecided")
630
+ # mov ax,[0200h]; and ax,0FF0h; movzx bx,ah: the high byte of the masked word is at most 0Fh.
631
+ self.assertEqual(self.check("a1 00 02 25 f0 0f 0f b6 dc", "le", 0x0f)["verdict"], "held")
632
+ self.assertEqual(self.check("a1 00 02 25 f0 0f 0f b6 dc", "le", 0x0e)["verdict"], "undecided")
633
+ # xor dx,dx; mov ax,[0200h]; mov cx,10; div cx; then the remainder or the quotient into BX.
634
+ divide = "31 d2 a1 00 02 b9 0a 00 f7 f1"
635
+ self.assertEqual(self.check(divide + " 89 d3", "le", 9)["verdict"], "held")
636
+ self.assertEqual(self.check(divide + " 89 d3", "le", 8)["verdict"], "undecided")
637
+ self.assertEqual(self.check(divide + " 89 c3", "le", 0xffff // 10)["verdict"], "held")
638
+ self.assertEqual(self.check(divide + " 89 c3", "le", 0xffff // 10 - 1)["verdict"], "undecided")
639
+
640
+ def test_an_arithmetic_shift_is_bounded_only_when_the_sign_bit_is_clear(self):
641
+ # and bx,7FFFh; sar bx,4: the sign bit is clear, so the shift is a logical one.
642
+ self.assertEqual(self.check("8b 1e 00 02 81 e3 ff 7f c1 fb 04", "le", 0x07ff)["verdict"], "held")
643
+ self.assertEqual(self.check("8b 1e 00 02 81 e3 ff 7f c1 fb 04", "le", 0x07fe)["verdict"], "undecided")
644
+ # sar bx,4 of an unmasked word may shift ones in from the top.
645
+ self.assertEqual(self.check("8b 1e 00 02 c1 fb 04", "le", 0xfffe)["verdict"], "undecided")
646
+
647
+ def test_or_keeps_its_constant_bits_and_the_operands_highest_bit(self):
648
+ # movzx bx,byte [0200h]; or bx,10h
649
+ self.assertEqual(self.check("0f b6 1e 00 02 83 cb 10", "ge", 0x10)["verdict"], "held")
650
+ self.assertEqual(self.check("0f b6 1e 00 02 83 cb 10", "le", 0xff)["verdict"], "held")
651
+ self.assertEqual(self.check("0f b6 1e 00 02 83 cb 10", "le", 0xfe)["verdict"], "undecided")
652
+
653
+ def test_an_assumed_range_bounds_the_masked_operand(self):
654
+ # mov bx,cx; and bx,0FFh, with CX assumed at most 7.
655
+ c = Code().emit("89 cb 81 e3 ff 00").label("return").emit("c3")
656
+ rule = control("bound", "relation", at={"site": c.labels["return"], "event": "checkpoint"}, op="le",
657
+ left={"field": "registers.bx"}, right=7)
658
+ self.assertEqual(verdict(run(c, [rule], registers=FRAME), "bound")["verdict"], "undecided")
659
+ assumed = {**rule, "assume": [{"value": {"entryRegister": "cx"}, "min": 0, "max": 7, "evidence": "synthetic caller range"}]}
660
+ self.assertEqual(verdict(run(c, [assumed], registers=FRAME), "bound")["verdict"], "held")
661
+
662
+ def test_an_assumption_on_a_masked_value_keeps_the_narrower_range(self):
663
+ # mov bx,[0200h]; and bx,3, with BX itself assumed at most 100: the mask still bounds it by 3.
664
+ c = Code().emit("8b 1e 00 02 81 e3 03 00").label("return").emit("c3")
665
+
666
+ def bound(op, right, lo, hi):
667
+ rule = control("bound", "relation", at={"site": c.labels["return"], "event": "checkpoint"}, op=op,
668
+ left={"field": "registers.bx"}, right=right,
669
+ assume=[{"value": {"field": "registers.bx"}, "min": lo, "max": hi, "evidence": "synthetic range"}])
670
+ return verdict(run(c, [rule], registers=FRAME), "bound")
671
+
672
+ self.assertEqual(bound("le", 3, 0, 100)["verdict"], "held")
673
+ self.assertEqual(bound("le", 1, 0, 1)["verdict"], "held")
674
+ # A range the mask rules out would make any relation hold, so the occurrence is undecided.
675
+ excluded = bound("ge", 5, 5, 10)
676
+ self.assertEqual(excluded["verdict"], "undecided")
677
+ self.assertIn("outside the range 0..3", excluded["paths"][0]["occurrences"][0]["reason"])
678
+
679
+ def test_a_stopped_path_leaves_a_masked_bound_undecided(self):
680
+ # One path calls through BX and stops before the masked load.
681
+ result = self.check("8b 1e 00 02 81 e3 03 00", "le", 3, before="85 c0 74 02 ff d3")
682
+ self.assertEqual(result["verdict"], "undecided")
683
+ self.assertIn("stopped", " ".join(result["reasons"]))
684
+
685
+
597
686
  class OriginTests(unittest.TestCase):
598
687
  def recursion(self, local=""):
599
688
  # The helper counts AX down and returns FFFF from its base case; the root tests the result.