scientific-method-engine 6.1.1__tar.gz → 6.3.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 (68) hide show
  1. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/PKG-INFO +9 -1
  2. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/README.md +8 -0
  3. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/cli.py +1 -0
  5. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/argument_frames.py +27 -2
  6. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/machine.py +23 -0
  7. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/relational.py +8 -0
  8. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/reports.py +4 -0
  9. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/trace.py +69 -9
  10. scientific_method_engine-6.3.0/tests/test_entry_frame.py +156 -0
  11. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/tests/test_x86.py +43 -1
  12. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/.gitignore +0 -0
  13. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/LICENSE +0 -0
  14. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/__init__.py +0 -0
  15. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/__main__.py +0 -0
  16. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  17. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  18. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  19. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  20. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  21. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  22. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  23. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  24. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  25. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  26. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  27. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  28. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  29. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  30. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  31. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  32. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  33. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  34. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  35. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  36. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  37. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  38. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  39. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  40. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  41. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  42. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  43. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  44. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  45. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  46. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  47. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  48. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  49. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  50. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/image.py +0 -0
  51. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/loops.py +0 -0
  52. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  53. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  54. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  55. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/pe.py +0 -0
  56. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  57. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/src/scientific_method_engine/x86/values.py +0 -0
  58. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/tests/oracle.py +0 -0
  59. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/tests/test_continuation_budget.py +0 -0
  60. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/tests/test_dispatch.py +0 -0
  61. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/tests/test_effect_order.py +0 -0
  62. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/tests/test_loops.py +0 -0
  63. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/tests/test_memory_scopes.py +0 -0
  64. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/tests/test_nested_frame_request.py +0 -0
  65. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/tests/test_oracle.py +0 -0
  66. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/tests/test_pe.py +0 -0
  67. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/tests/test_relational_controls.py +0 -0
  68. {scientific_method_engine-6.1.1 → scientific_method_engine-6.3.0}/tests/test_table_continuations.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 6.1.1
3
+ Version: 6.3.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
@@ -161,3 +161,11 @@ control fails the report. A control left undecided by a stop, a limit or an unre
161
161
  reported as `undecided` and never counts as held. Access reports also give each byte's
162
162
  `writeOrder`, or why it has no modeled value. See the
163
163
  [controls contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#relational-controls).
164
+
165
+ A trace-family query whose entry lies inside a function body names the function's entry in
166
+ `entryFrame: { "from": <site> }`. The engine traces from there to the query's entry and, when SP
167
+ sits at one offset from the function's entry SP at every arrival, starts the query in that frame,
168
+ so the function's return balances and its paths can be read to the end. The report's `entryFrame`
169
+ gives the offsets, or the reasons the frame is not established, in which case the query runs as
170
+ it would without the input. See the
171
+ [narrower entry contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#a-narrower-entry-inside-its-functions-frame).
@@ -145,3 +145,11 @@ control fails the report. A control left undecided by a stop, a limit or an unre
145
145
  reported as `undecided` and never counts as held. Access reports also give each byte's
146
146
  `writeOrder`, or why it has no modeled value. See the
147
147
  [controls contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#relational-controls).
148
+
149
+ A trace-family query whose entry lies inside a function body names the function's entry in
150
+ `entryFrame: { "from": <site> }`. The engine traces from there to the query's entry and, when SP
151
+ sits at one offset from the function's entry SP at every arrival, starts the query in that frame,
152
+ so the function's return balances and its paths can be read to the end. The report's `entryFrame`
153
+ gives the offsets, or the reasons the frame is not established, in which case the query runs as
154
+ it would without the input. See the
155
+ [narrower entry contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#a-narrower-entry-inside-its-functions-frame).
@@ -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 = "6.1.1"
8
+ version = "6.3.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"
@@ -20,6 +20,7 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
20
20
  "agreed is false where Ghidra ends the function at a call, conditional jump or interrupt the engine reads past (ghidraEndsFunction).\n"
21
21
  "trace, arguments, effects, returns, guards, memory and allocation check relationalControls:\n"
22
22
  "a violated control fails the report; an undecided one is reported and never counts as held.\n"
23
+ "entryFrame {from} starts an entry inside the function at from, in the frame a trace from there observed.\n"
23
24
  "Declared table continuations are separate conditional paths that spend continuationBudget\n"
24
25
  "(paths, totalSteps, maxSteps, visitLimit, stringIterations); ordinary computed transfers remain stopped.\n"
25
26
  "Port accesses and interrupts are hardware-boundary events; portInputs supplies port reads as assumptions.\n"
@@ -24,6 +24,11 @@ def stack_cleanup(ins):
24
24
  return amount if 0 < amount < 1 << (bits - 1) else None
25
25
 
26
26
 
27
+ def _overlap(a, b):
28
+ """Whether the reads or intervals `a` and `b`, each starting (offset, width, ...), share a byte."""
29
+ return a[0] < b[0] + b[1] and b[0] < a[0] + a[1]
30
+
31
+
27
32
  def _covered(event, segment, base, start, width, modulus):
28
33
  """The frame offsets below `width` that a write event stored, counted from stack byte `start`."""
29
34
  interval = event.get("interval")
@@ -171,9 +176,16 @@ def _frame(image, events, index, models):
171
176
  "offsetFromEntrySP": event["argument"]["offsetFromEntrySP"], "bytes": hits})
172
177
 
173
178
  intervals = sorted({(g["offset"], g["width"]) for g in groupings})
174
- competing = [[list(a), list(b)] for i, a in enumerate(intervals) for b in intervals[i + 1:] if a[0] < b[0] + b[1] and b[0] < a[0] + a[1]]
179
+ competing = [[list(a), list(b)] for i, a in enumerate(intervals) for b in intervals[i + 1:] if _overlap(a, b)]
175
180
  if competing:
176
181
  open_reasons.append("reads of different widths overlap")
182
+ # A far-pointer load and a plain dword of the same bytes do not settle one grouping either.
183
+ grouped_as = {}
184
+ for g in groupings:
185
+ grouped_as.setdefault((g["offset"], g["width"]), set()).add(g["grouping"])
186
+ for (offset, read_width), kinds in sorted(grouped_as.items()):
187
+ if len(kinds) > 1:
188
+ open_reasons.append(f"the {read_width} bytes at {offset} are read with more than one grouping")
177
189
  for slot in slots:
178
190
  if slot["writerSite"] is not None and not slot["consumedBy"]:
179
191
  open_reasons.append(f"the slot at {slot['offset']} was not read by the callee on this path")
@@ -190,7 +202,9 @@ def argument_frames(report, image):
190
202
 
191
203
  A path gets one map per traced call, from caller-written slots to callee reads. A site's
192
204
  groupings agree only when every path that traced a call there settled on the same read widths
193
- and groupings.
205
+ and groupings. Separately, a site's widths are consistent when its paths made at least one read
206
+ and no two reads on any of them cover the same byte with a different offset, width or grouping;
207
+ a path that skipped a read leaves the site consistent but not agreed.
194
208
  """
195
209
  sites = {}
196
210
  for path_index, path in enumerate(report["paths"]):
@@ -203,10 +217,21 @@ def argument_frames(report, image):
203
217
  for site, rows in sorted(sites.items()):
204
218
  # A set holds each read's grouping too: a far-pointer load and a plain dword over the same bytes disagree.
205
219
  widths = sorted({tuple(sorted({(g["offset"], g["width"], g["grouping"]) for g in f["groupings"]})) for _, f in rows})
220
+ read_on = {}
221
+ for i, f in rows:
222
+ for g in f["groupings"]:
223
+ read_on.setdefault((g["offset"], g["width"], g["grouping"]), set()).add(i)
224
+ reads = sorted(read_on)
225
+ # Distinct reads that share a byte conflict: different intervals, or one interval grouped two ways.
226
+ conflicting = [[{"offset": o, "width": w, "grouping": k} for o, w, k in (a, b)]
227
+ for n, a in enumerate(reads) for b in reads[n + 1:] if _overlap(a, b)]
206
228
  report["argumentFrameSites"].append({
207
229
  "callSite": site, "paths": sorted({i for i, _ in rows}), "frames": len(rows),
208
230
  "unsettledPaths": sorted({i for i, f in rows if not f["settledOnThisPath"]}),
209
231
  "readWidthSets": [[{"offset": o, "width": w, "grouping": k} for o, w, k in group] for group in widths],
232
+ "readWidths": [{"offset": o, "width": w, "grouping": k, "paths": sorted(read_on[(o, w, k)])} for o, w, k in reads],
233
+ "conflictingWidths": conflicting,
234
+ "widthsConsistent": bool(reads) and not conflicting,
210
235
  "agreed": len(widths) == 1 and all(f["settledOnThisPath"] for _, f in rows),
211
236
  "interpretation": "read widths per traced path; paths that never reached this call are not represented"})
212
237
  return report
@@ -171,6 +171,29 @@ class State:
171
171
  self.event("flag-assumption", flag="DF", value=self.direction_flag.report(),
172
172
  evidence="explicit query starting hypothesis, not native state")
173
173
 
174
+ def enter_frame(self, frame):
175
+ """Place the entry inside the enclosing function's frame that an entryFrame trace established.
176
+
177
+ The root frame keeps the function's entry SP, so the function's own return balances against
178
+ it. SP, and BP when the trace found it at one offset, become offsets from that SP. A frame
179
+ that is absent or not established leaves the state as it was.
180
+ """
181
+ if not frame or not frame["established"]:
182
+ return
183
+ base = self.frames[0]["sp"]
184
+ self.setreg(self.sp, op("add", base, const(frame["sp"], self.bits)), None)
185
+ if frame["bp"] is not None:
186
+ self.setreg(self.bp, op("add", base, const(frame["bp"], self.bits)), None)
187
+
188
+ def frame_offset(self, value):
189
+ """A register value as a signed offset from the current frame's entry SP, or None when it is not one."""
190
+ base, delta = address_parts(self.frames[-1]["sp"])
191
+ other, other_delta = address_parts(value)
192
+ if other != base or base == ("absolute",):
193
+ return None
194
+ offset = (other_delta - delta) % (1 << self.bits)
195
+ return offset - (1 << self.bits) if offset >> (self.bits - 1) else offset
196
+
174
197
  def forget_flags(self, keep_carry=False):
175
198
  carry = self.carry_value() if keep_carry else None
176
199
  self.flags = None
@@ -661,7 +661,13 @@ def evaluate_controls(report, config, image):
661
661
  limit = integer(config.get("controlOccurrenceLimit", 4096), 1, 100000, "control occurrence limit")
662
662
  spent = 0
663
663
  entry_state = State(config["entry"], image, config)
664
+ frame = report.get("entryFrame")
665
+ # Entry register references read the entry as the trace started it, inside the observed frame.
666
+ entry_state.enter_frame(frame)
664
667
  supplied = {ALIASES[r][0] for r in config.get("registers", {})}
668
+ if frame and frame["established"] and frame["bp"] is not None:
669
+ # The frame states BP as an offset from the entry SP, so no unknown input names BP.
670
+ supplied.add("ebp")
665
671
  case_supplied = {(m["site"], ALIASES[r][0]) for m in config.get("callModels", [])
666
672
  for case in m["cases"] for r in case.get("registers", {})}
667
673
  paths = [_Path(p, entry_state, supplied, case_supplied) for p in report["paths"]]
@@ -716,6 +722,8 @@ def evaluate_controls(report, config, image):
716
722
  if capped:
717
723
  break
718
724
  reasons = []
725
+ if frame and not frame["established"] and any(not r["returned"] for r in rows):
726
+ reasons.append("entryFrame was not established: " + "; ".join(frame["reasons"]))
719
727
  if unread:
720
728
  reasons.append("paths the trace did not read: " + "; ".join(g["reason"] for g in unread))
721
729
  if capped:
@@ -1538,6 +1538,8 @@ def _run_report(image, config, command):
1538
1538
  raise ValueError("relationalControls apply only to " + ", ".join(TRACE_COMMANDS))
1539
1539
  if "controlOccurrenceLimit" in config and command not in TRACE_COMMANDS:
1540
1540
  raise ValueError("controlOccurrenceLimit applies only to " + ", ".join(TRACE_COMMANDS))
1541
+ if "entryFrame" in config and command not in TRACE_COMMANDS:
1542
+ raise ValueError("entryFrame applies only to " + ", ".join(TRACE_COMMANDS))
1541
1543
  if command == "operand":
1542
1544
  return operand_provenance(image, config)
1543
1545
  if command == "target":
@@ -1577,6 +1579,8 @@ def _run_report(image, config, command):
1577
1579
  report = argument_frames(report, image)
1578
1580
  if command == "allocation":
1579
1581
  result = allocations(report, config)
1582
+ if "entryFrame" in report:
1583
+ result["entryFrame"] = report["entryFrame"]
1580
1584
  if controls is not None:
1581
1585
  result["relationalControls"] = controls
1582
1586
  return result
@@ -323,7 +323,55 @@ def validate_continuation_budget(config):
323
323
  for key, value in budget.items()}
324
324
 
325
325
 
326
- def trace(image, config, continue_declared_jumps=True, track_loops=True):
326
+ # The stop of an entryFrame trace's path at its first arrival at the query's entry.
327
+ ENTRY_ARRIVAL = "reached the query's entry"
328
+
329
+
330
+ def entry_frame(image, config, entry):
331
+ """The query entry's place in the frame of the function that holds it, observed on a trace from that function's entry.
332
+
333
+ Returns None without an ``entryFrame`` input. Each path from ``entryFrame.from`` stops at its first
334
+ arrival at the entry, since the query itself traces everything after it. The frame is established
335
+ when every path was read until it arrived or returned, at least one arrived, every arrival was in
336
+ a frame of that function, and SP sat at one offset from that frame's entry SP at all of them. BP is
337
+ stated only when it also sat at one offset at all of them.
338
+ """
339
+ spec = config.get("entryFrame")
340
+ if spec is None:
341
+ return None
342
+ if not isinstance(spec, dict) or set(spec) != {"from"}:
343
+ raise ValueError("entryFrame takes only from, the entry of the function that holds the query's entry")
344
+ start = integer(spec["from"], 0, len(image.data) - 1, "entryFrame.from")
345
+ registers = config.get("registers", {})
346
+ if isinstance(registers, dict) and any(ALIASES.get(r, ("",))[0] in ("esp", "ebp") for r in registers):
347
+ raise ValueError("entryFrame observes SP and BP at the entry; registers cannot also supply them")
348
+ # Checkpoints and return contracts only add report detail, which this trace never reports.
349
+ prefix = {k: v for k, v in config.items()
350
+ if k not in ("entryFrame", "relationalControls", "controlOccurrenceLimit", "checkpoints", "returnContracts")}
351
+ report = trace(image, {**prefix, "entry": start}, continue_declared_jumps=False, track_loops=False, arrive=entry)
352
+ arrivals = [p["arrival"] for p in report["paths"] if p["stop"] == ENTRY_ARRIVAL]
353
+ reasons = [f"a path from {start} stopped at {p['stopSite']} before reaching the entry: {p['stop']}"
354
+ for p in report["paths"] if not p["returned"] and p["stop"] != ENTRY_ARRIVAL]
355
+ reasons += [f"the trace from {start} left paths unread: {g['reason']}" for g in report["gaps"]]
356
+ reasons += [f"the entry was reached inside a call to {a['frameEntry']}" for a in arrivals if a["frameEntry"] != start]
357
+ if not arrivals:
358
+ reasons.append(f"no path from {start} reached the entry")
359
+ offsets = sorted({a["sp"] for a in arrivals if a["sp"] is not None})
360
+ if any(a["sp"] is None for a in arrivals):
361
+ reasons.append("SP at an arrival is not an offset from the function's entry SP")
362
+ elif len(offsets) > 1:
363
+ reasons.append("arrivals reach the entry with SP at different offsets: " + ", ".join(map(str, offsets)))
364
+ established = not reasons
365
+ bp = {a["bp"] for a in arrivals}
366
+ return {"from": start, "established": established, "sp": offsets[0] if established else None,
367
+ "bp": next(iter(bp)) if established and len(bp) == 1 else None,
368
+ "arrivals": len(arrivals), "pathsRead": len(report["paths"]), "stepsUsed": report["stepsUsed"],
369
+ "reasons": reasons,
370
+ "meaning": "offsets from the entry SP of the function at from, observed at each first arrival on the "
371
+ "traced paths under the query's own inputs; bp null leaves BP unknown"}
372
+
373
+
374
+ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=None):
327
375
  """Trace bounded paths, preserving declared-table continuations as separate conditional evidence.
328
376
 
329
377
  Ordinary paths run first. A path stopped at a declared indirect jump is then
@@ -332,7 +380,8 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
332
380
  what the ordinary paths spend never leaves the continuations without budget.
333
381
  Callers that read only ordinary paths pass continue_declared_jumps=False.
334
382
  Callers that never report the paths pass track_loops=False, and their paths
335
- carry no ``loops`` record.
383
+ carry no ``loops`` record. entry_frame passes arrive, the query entry:
384
+ each path stops at its first arrival at the site with an ``arrival`` record.
336
385
  """
337
386
  entry = integer(config.get("entry"), 0, len(image.data) - 1, "entry")
338
387
  if not any(entry in r["entries"] for r in image.regions):
@@ -369,7 +418,9 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
369
418
  if r not in ALIASES or type(n) is not int or not 0 <= n < 1 << ALIASES[r][2]:
370
419
  raise ValueError("Invalid model register")
371
420
  explicit_continuation_budget = validate_continuation_budget(config)
421
+ observed_frame = entry_frame(image, config, entry) if arrive is None else None
372
422
  root = State(entry, image, config)
423
+ root.enter_frame(observed_frame)
373
424
  # Each path carries its own loop record; forks copy it with the rest of the state.
374
425
  root.loops = (LoopTracker(integer(config.get("loopIterationLimit", 64), 1, 1024, "loopIterationLimit"))
375
426
  if track_loops else None)
@@ -417,6 +468,9 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
417
468
  path = {"returned": returned, "stop": reason, "stopSite": None if returned else s.at, "steps": s.steps,
418
469
  "instructionPath": s.path, "guards": s.guards, "events": s.events,
419
470
  "registers": snapshot(s), "conditionalModels": s.conditional}
471
+ if reason == ENTRY_ARRIVAL:
472
+ path["arrival"] = {"frameEntry": s.frames[-1]["entry"], "sp": s.frame_offset(s.reg(s.sp)),
473
+ "bp": s.frame_offset(s.reg(s.bp))}
420
474
  if s.loops is not None:
421
475
  path["loops"] = s.loops.report()
422
476
  assumptions = getattr(s, "declared_jump_assumptions", [])
@@ -524,6 +578,9 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
524
578
  state = pending.pop()
525
579
  try:
526
580
  while True:
581
+ if arrive is not None and state.at == arrive:
582
+ finish(state, ENTRY_ARRIVAL)
583
+ break
527
584
  if continuing:
528
585
  if state.continuation_steps >= continuation_budget["maxSteps"]:
529
586
  raise StopPath("continuation step limit; loop progress unresolved")
@@ -808,10 +865,13 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
808
865
  else:
809
866
  ordinary_steps, ordinary_string_steps = total_steps, total_string_steps
810
867
  continuation_steps = continuation_string_steps = 0
811
- return {"paths": outputs, "declaredContinuationPaths": conditional_outputs, "gaps": global_gaps,
812
- "hardwareBoundaries": hardware_placement(outputs, conditional_outputs, global_gaps[:first_continuation_gap]),
813
- "completeWithinModel": not global_gaps[:first_continuation_gap] and bool(outputs) and all(p["returned"] for p in outputs),
814
- "nativeReachability": "unconfirmed", "stepsUsed": ordinary_steps, "stringIterationsUsed": ordinary_string_steps,
815
- "continuationStepsUsed": continuation_steps, "continuationStringIterationsUsed": continuation_string_steps,
816
- "limits": {"steps": max_steps, "paths": ordinary_max_paths, "depth": max_depth,
817
- "continuation": continuation_budget}}
868
+ result = {"paths": outputs, "declaredContinuationPaths": conditional_outputs, "gaps": global_gaps,
869
+ "hardwareBoundaries": hardware_placement(outputs, conditional_outputs, global_gaps[:first_continuation_gap]),
870
+ "completeWithinModel": not global_gaps[:first_continuation_gap] and bool(outputs) and all(p["returned"] for p in outputs),
871
+ "nativeReachability": "unconfirmed", "stepsUsed": ordinary_steps, "stringIterationsUsed": ordinary_string_steps,
872
+ "continuationStepsUsed": continuation_steps, "continuationStringIterationsUsed": continuation_string_steps,
873
+ "limits": {"steps": max_steps, "paths": ordinary_max_paths, "depth": max_depth,
874
+ "continuation": continuation_budget}}
875
+ if observed_frame is not None:
876
+ result["entryFrame"] = observed_frame
877
+ return result
@@ -0,0 +1,156 @@
1
+ """A narrower entry inside a function's frame, observed from the function's entry (entryFrame). Synthetic code only."""
2
+ import unittest
3
+ from test_x86 import Code, report
4
+
5
+ STACK = {"ss": 0x3000, "ds": 0x2000}
6
+ # push bp; mov bp, sp; sub sp, 4; push si
7
+ PROLOGUE = "55 8b ec 83 ec 04 56"
8
+ # pop si; mov sp, bp; pop bp; ret
9
+ EPILOGUE = "5e 8b e5 5d c3"
10
+
11
+
12
+ def cleanup():
13
+ """A guard skips the assignment to [bp-2]; the cleanup read takes it on both edges."""
14
+ return (Code().emit(PROLOGUE).label("narrow").emit("85 c0").branch("74", "skip").label("assign")
15
+ .emit("c7 46 fe 01 00").label("skip").label("read").emit("8b 46 fe " + EPILOGUE))
16
+
17
+
18
+ def run(c, command="trace", entries=("narrow",), **extra):
19
+ data = c.bytes()
20
+ regions = [{"name": "synthetic", "start": 0, "end": len(data), "ip": 0, "segment": 0x1000, "resident": True,
21
+ "entries": [0, *(c.labels[e] for e in entries)], "evidence": "synthetic declared code extent"}]
22
+ return report(c, command, regions=regions, entry=c.labels[entries[0]], **{"registers": STACK, **extra})
23
+
24
+
25
+ def slot(c, *writers):
26
+ return [{"name": "slot", "kind": "lastWriter", "at": {"site": c.labels["read"], "event": "read"},
27
+ "writers": [c.labels["assign"], *writers]}]
28
+
29
+
30
+ def verdict(result):
31
+ return result["relationalControls"]["controls"][0]
32
+
33
+
34
+ class EntryFrameTests(unittest.TestCase):
35
+ def test_without_an_entry_frame_the_function_return_stops_every_path(self):
36
+ c = cleanup()
37
+ r = run(c, relationalControls=slot(c, "entryState"))
38
+ self.assertNotIn("entryFrame", r)
39
+ self.assertEqual({p["stop"] for p in r["paths"]}, {"return frame or stack balance differs from the call"})
40
+ self.assertEqual(verdict(r)["verdict"], "undecided")
41
+
42
+ def test_the_observed_frame_lets_the_function_return_and_the_control_hold(self):
43
+ c = cleanup()
44
+ r = run(c, relationalControls=slot(c, "entryState"), entryFrame={"from": 0})
45
+ frame = r["entryFrame"]
46
+ self.assertTrue(frame["established"])
47
+ self.assertEqual((frame["sp"], frame["bp"], frame["arrivals"], frame["reasons"]), (-8, -2, 1, []))
48
+ self.assertTrue(r["completeWithinModel"])
49
+ self.assertTrue(all(p["returned"] for p in r["paths"]))
50
+ result = verdict(r)
51
+ self.assertEqual(result["verdict"], "held")
52
+ edges = {o["via"]["taken"]: o["bytes"][0] for p in result["paths"] for o in p["occurrences"]}
53
+ self.assertEqual(edges[False]["writer"]["site"], c.labels["assign"])
54
+ self.assertEqual(edges[True]["unwritten"]["cause"], "no write on this path")
55
+
56
+ def test_a_skipped_assignment_violates_the_control_inside_the_observed_frame(self):
57
+ c = cleanup()
58
+ with self.assertRaisesRegex(ValueError, "slot violated on path"):
59
+ run(c, relationalControls=slot(c), entryFrame={"from": 0})
60
+
61
+ def test_arguments_count_from_the_function_entry_sp(self):
62
+ # The narrower entry reads the function's first argument through BP.
63
+ c = Code().emit(PROLOGUE).label("narrow").emit("8b 46 04 " + EPILOGUE)
64
+ r = run(c, "arguments", entryFrame={"from": 0})
65
+ read = next(e for e in r["paths"][0]["events"] if e["kind"] == "read" and e["site"] == c.labels["narrow"])
66
+ self.assertEqual(read["argument"]["offsetFromEntrySP"], 2)
67
+
68
+ def test_arrivals_with_different_sp_leave_the_frame_unestablished(self):
69
+ # One edge pushes an extra word before the narrower entry.
70
+ c = (Code().emit("55 8b ec 85 c0").branch("74", "join").emit("53").label("join").label("narrow")
71
+ .emit("8b e5 5d c3").label("dead").emit("90"))
72
+ r = run(c, entryFrame={"from": 0}, relationalControls=[
73
+ {"name": "dead", "kind": "reach", "at": {"site": c.labels["dead"]}, "expect": "never"}])
74
+ frame = r["entryFrame"]
75
+ self.assertFalse(frame["established"])
76
+ self.assertEqual((frame["sp"], frame["arrivals"]), (None, 2))
77
+ self.assertIn("different offsets: -4, -2", " ".join(frame["reasons"]))
78
+ self.assertEqual({p["stop"] for p in r["paths"]}, {"return frame or stack balance differs from the call"})
79
+ result = verdict(r)
80
+ self.assertEqual(result["verdict"], "undecided")
81
+ self.assertIn("entryFrame was not established", " ".join(result["reasons"]))
82
+
83
+ def test_a_stop_before_the_entry_leaves_the_frame_unestablished(self):
84
+ # An unresolved call on one edge stops that path before it reaches the narrower entry.
85
+ c = Code().emit("55 8b ec 85 c0").branch("74", "narrow").emit("ff d3").label("narrow").emit("5d c3")
86
+ frame = run(c, entryFrame={"from": 0})["entryFrame"]
87
+ self.assertFalse(frame["established"])
88
+ self.assertIn("before reaching the entry", " ".join(frame["reasons"]))
89
+
90
+ def test_a_path_limit_before_the_entry_leaves_the_frame_unestablished(self):
91
+ c = Code().emit("55 8b ec 85 c0").branch("74", "narrow").emit("90").label("narrow").emit("5d c3")
92
+ frame = run(c, entryFrame={"from": 0}, maxPaths=1)["entryFrame"]
93
+ self.assertFalse(frame["established"])
94
+ self.assertIn("left paths unread: path limit", " ".join(frame["reasons"]))
95
+
96
+ def test_only_the_first_arrival_counts_and_a_stop_after_it_is_the_query_s_own(self):
97
+ # After the narrower entry an unresolved call stops one edge; the query reports that stop itself.
98
+ c = (Code().emit(PROLOGUE).label("narrow").emit("85 c0").branch("74", "out").emit("ff d3").label("out")
99
+ .emit(EPILOGUE))
100
+ r = run(c, entryFrame={"from": 0})
101
+ self.assertTrue(r["entryFrame"]["established"])
102
+ self.assertEqual(r["entryFrame"]["pathsRead"], 1)
103
+ self.assertEqual(sorted(p["returned"] for p in r["paths"]), [False, True])
104
+
105
+ def test_an_entry_no_path_reaches_leaves_the_frame_unestablished(self):
106
+ c = Code().emit("55 8b ec 5d c3").label("narrow").emit("c3")
107
+ frame = run(c, entryFrame={"from": 0})["entryFrame"]
108
+ self.assertEqual((frame["established"], frame["arrivals"]), (False, 0))
109
+ self.assertIn("no path from 0 reached the entry", frame["reasons"])
110
+
111
+ def test_an_entry_reached_inside_another_function_leaves_the_frame_unestablished(self):
112
+ c = Code().emit("55 8b ec").branch("e8", "helper").emit("5d c3").label("helper").label("narrow").emit("c3")
113
+ frame = run(c, entryFrame={"from": 0})["entryFrame"]
114
+ self.assertFalse(frame["established"])
115
+ self.assertIn(f"inside a call to {c.labels['helper']}", " ".join(frame["reasons"]))
116
+
117
+ def test_bp_that_is_not_a_frame_offset_stays_unknown(self):
118
+ # BP holds a loaded word at the narrower entry, so only SP is stated.
119
+ c = Code().emit("55 8b 2e 20 00").label("narrow").emit("5d c3")
120
+ r = run(c, entryFrame={"from": 0})
121
+ self.assertEqual((r["entryFrame"]["established"], r["entryFrame"]["sp"], r["entryFrame"]["bp"]), (True, -2, None))
122
+ self.assertTrue(r["paths"][0]["returned"])
123
+
124
+ def test_an_entry_bp_input_the_frame_states_is_undecided(self):
125
+ # BP enters as an offset from the entry SP, so no unknown input names it; that never violates.
126
+ c = (Code().emit(PROLOGUE).label("narrow").emit("89 e8 85 c0").label("branch").branch("74", "out").label("out")
127
+ .emit(EPILOGUE))
128
+ rule = {"name": "frame pointer", "kind": "origin", "at": {"site": c.labels["branch"], "event": "branch"},
129
+ "value": {"field": "left"}, "expect": {"inputs": {"include": [{"entryRegister": "bp"}]}}}
130
+ r = run(c, relationalControls=[rule], entryFrame={"from": 0})
131
+ self.assertEqual(r["entryFrame"]["bp"], -2)
132
+ result = verdict(r)
133
+ self.assertEqual(result["verdict"], "undecided")
134
+ self.assertIn("supplies its entry value", result["paths"][0]["occurrences"][0]["reason"])
135
+ # SP stays an unknown input, so a value derived from it holds.
136
+ held = run(c, relationalControls=[{**rule, "expect": {"inputs": {"include": [{"entryRegister": "sp"}]}}}],
137
+ entryFrame={"from": 0})
138
+ self.assertEqual(verdict(held)["verdict"], "held")
139
+
140
+ def test_rejected_inputs(self):
141
+ c = cleanup()
142
+ for value, message in (({"from": 0, "sp": -8}, "takes only from"), (0, "takes only from"),
143
+ ({"from": -1}, "entryFrame.from")):
144
+ with self.assertRaisesRegex(ValueError, message):
145
+ run(c, entryFrame=value)
146
+ with self.assertRaisesRegex(ValueError, "registers cannot also supply them"):
147
+ run(c, entryFrame={"from": 0}, registers={**STACK, "bp": 0x100})
148
+ with self.assertRaisesRegex(ValueError, "entryFrame applies only to"):
149
+ run(c, "bounds", entryFrame={"from": 0}, query={"entry": 0})
150
+ # The function entry must itself be an established entry.
151
+ with self.assertRaisesRegex(ValueError, "established region entry"):
152
+ run(c, entryFrame={"from": c.labels["assign"]})
153
+
154
+
155
+ if __name__ == "__main__":
156
+ unittest.main()
@@ -421,7 +421,7 @@ class ArgumentFrameTests(unittest.TestCase):
421
421
  self.assertEqual(r["argumentFrameSites"][0]["readWidthSets"], [[{"offset": 0, "width": 2, "grouping": "consumed width only"},
422
422
  {"offset": 2, "width": 4, "grouping": "far-pointer"},
423
423
  {"offset": 6, "width": 2, "grouping": "consumed width only"}]])
424
- self.assertTrue(all(site["agreed"] for site in r["argumentFrameSites"]))
424
+ self.assertTrue(all(site["agreed"] and site["widthsConsistent"] for site in r["argumentFrameSites"]))
425
425
 
426
426
  def test_the_report_keeps_the_writes_its_slots_cite(self):
427
427
  c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3").label("callee").emit("55 89 e5 8b 46 04 8b 46 06 5d c3")
@@ -586,6 +586,25 @@ class ArgumentFrameTests(unittest.TestCase):
586
586
  [{"offset": 0, "width": 4, "grouping": "far-pointer"}]])
587
587
  self.assertFalse(site["agreed"])
588
588
  self.assertEqual(len(site["unsettledPaths"]), 1)
589
+ self.assertFalse(site["widthsConsistent"])
590
+ self.assertEqual(site["conflictingWidths"], [[{"offset": 0, "width": 2, "grouping": "consumed width only"},
591
+ {"offset": 0, "width": 4, "grouping": "far-pointer"}]])
592
+
593
+ def test_a_path_that_skips_a_read_leaves_the_site_consistent_but_not_agreed(self):
594
+ # The callee always reads the first word and reads the second only when SI is nonzero.
595
+ c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3")
596
+ c.label("callee").emit("55 89 e5 8b 46 04 85 f6").branch("74", "skip").emit("8b 5e 06").label("skip").emit("5d c3")
597
+ r, frames = self.frames(c)
598
+ self.assertEqual(len(frames), 2)
599
+ site = r["argumentFrameSites"][0]
600
+ self.assertFalse(site["agreed"])
601
+ bypass = next(i for i, path in enumerate(r["paths"]) if not path["argumentFrames"][0]["settledOnThisPath"])
602
+ self.assertEqual(site["unsettledPaths"], [bypass])
603
+ self.assertIn("the slot at 2 was not read by the callee on this path", r["paths"][bypass]["argumentFrames"][0]["openReasons"])
604
+ self.assertTrue(site["widthsConsistent"])
605
+ self.assertEqual(site["conflictingWidths"], [])
606
+ self.assertEqual(site["readWidths"], [{"offset": 0, "width": 2, "grouping": "consumed width only", "paths": [0, 1]},
607
+ {"offset": 2, "width": 2, "grouping": "consumed width only", "paths": [1 - bypass]}])
589
608
 
590
609
  def test_paths_that_group_the_same_bytes_differently_keep_the_site_open(self):
591
610
  # Both paths read four bytes at offset 0: one as a far pointer with LES, one as a 32-bit dword.
@@ -599,6 +618,29 @@ class ArgumentFrameTests(unittest.TestCase):
599
618
  self.assertEqual(site["readWidthSets"], [[{"offset": 0, "width": 4, "grouping": "consumed width only"}],
600
619
  [{"offset": 0, "width": 4, "grouping": "far-pointer"}]])
601
620
  self.assertFalse(site["agreed"])
621
+ self.assertFalse(site["widthsConsistent"])
622
+ self.assertEqual(len(site["conflictingWidths"]), 1)
623
+
624
+ def test_one_path_that_groups_the_same_bytes_two_ways_stays_open(self):
625
+ # The callee loads the first four bytes with LES and then reads them again as a 32-bit dword.
626
+ c = Code().emit("6a 01 6a 02").branch("e8", "callee").emit("83 c4 04 c3")
627
+ c.label("callee").emit("55 89 e5 c4 5e 04 66 8b 46 04 5d c3")
628
+ r, frames = self.frames(c)
629
+ self.assertEqual(frames[0]["competingWidths"], [])
630
+ self.assertFalse(frames[0]["settledOnThisPath"])
631
+ self.assertIn("the 4 bytes at 0 are read with more than one grouping", frames[0]["openReasons"])
632
+ site = r["argumentFrameSites"][0]
633
+ self.assertFalse(site["agreed"])
634
+ self.assertFalse(site["widthsConsistent"])
635
+
636
+ def test_a_site_whose_callee_reads_nothing_is_not_consistent(self):
637
+ # A pushed word the callee never reads leaves no read to be consistent with.
638
+ c = Code().emit("6a 01").branch("e8", "callee").emit("83 c4 02 c3").label("callee").emit("c3")
639
+ r, _ = self.frames(c)
640
+ site = r["argumentFrameSites"][0]
641
+ self.assertEqual(site["readWidths"], [])
642
+ self.assertFalse(site["widthsConsistent"])
643
+ self.assertFalse(site["agreed"])
602
644
 
603
645
  def test_a_write_through_another_address_drops_the_slot_writer(self):
604
646
  # A DS write between the push and the call may alias the symbolic stack, so the pushed word