scientific-method-engine 7.4.0__tar.gz → 8.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 (70) hide show
  1. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/PKG-INFO +9 -1
  2. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/README.md +8 -0
  3. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/cli.py +2 -0
  5. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/argument_frames.py +51 -13
  6. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/machine.py +4 -1
  7. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/memory_scopes.py +18 -1
  8. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/relational.py +4 -4
  9. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/trace.py +91 -29
  10. scientific_method_engine-8.1.0/tests/test_interrupt_models.py +219 -0
  11. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_relational_controls.py +67 -0
  12. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_x86.py +112 -13
  13. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/.gitignore +0 -0
  14. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/LICENSE +0 -0
  15. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/__init__.py +0 -0
  16. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/__main__.py +0 -0
  17. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  18. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  19. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  20. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  21. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  22. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  23. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  24. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  25. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  26. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  27. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  28. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  29. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  30. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  31. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  32. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  33. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  34. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  35. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  36. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  37. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  38. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  39. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  40. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  41. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  42. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  43. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  44. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  45. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  46. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  47. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  48. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  49. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  50. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  51. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/image.py +0 -0
  52. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/loops.py +0 -0
  53. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  54. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  55. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
  56. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/reports.py +0 -0
  57. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  58. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/values.py +0 -0
  59. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/oracle.py +0 -0
  60. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_continuation_budget.py +0 -0
  61. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_dispatch.py +0 -0
  62. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_effect_order.py +0 -0
  63. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_entry_frame.py +0 -0
  64. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_loops.py +0 -0
  65. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_memory_scopes.py +0 -0
  66. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_nested_frame_request.py +0 -0
  67. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_oracle.py +0 -0
  68. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_pe.py +0 -0
  69. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_successor_rule.py +0 -0
  70. {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_table_continuations.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 7.4.0
3
+ Version: 8.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 call model may also sit at an `INT n` instruction in the real-mode model. The interrupt is
149
+ still reported as a hardware boundary with its vector, the handler is not executed, and each case
150
+ returns to the next instruction with SP and CS as before the interrupt. Registers, flags and memory
151
+ the model does not preserve or set are unknown. `leavesFlags: true` describes a service that returns
152
+ with a far return and leaves the interrupt's FLAGS word on the stack. Without a model, and at INT1,
153
+ INT3 (in either encoding), INTO or any PE32 interrupt, the path stops at the interrupt as before. See
154
+ [ADR 0017](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/decisions/0017-call-models-at-interrupt-sites.md).
155
+
148
156
  A call model may declare `preservesMemory`: up to 32 scopes (4,096 bytes in total), each naming a
149
157
  segment register, an address-width base register, an optional displacement, a byte count and the
150
158
  evidence for assuming the service leaves those bytes alone. Scopes resolve against the pre-call
@@ -129,6 +129,14 @@ boundary and continuation limits remain explicit gaps or stops. Partial-table sp
129
129
  partial evidence, never complete dispatch or native-reachability claims. See the
130
130
  [table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).
131
131
 
132
+ A call model may also sit at an `INT n` instruction in the real-mode model. The interrupt is
133
+ still reported as a hardware boundary with its vector, the handler is not executed, and each case
134
+ returns to the next instruction with SP and CS as before the interrupt. Registers, flags and memory
135
+ the model does not preserve or set are unknown. `leavesFlags: true` describes a service that returns
136
+ with a far return and leaves the interrupt's FLAGS word on the stack. Without a model, and at INT1,
137
+ INT3 (in either encoding), INTO or any PE32 interrupt, the path stops at the interrupt as before. See
138
+ [ADR 0017](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/decisions/0017-call-models-at-interrupt-sites.md).
139
+
132
140
  A call model may declare `preservesMemory`: up to 32 scopes (4,096 bytes in total), each naming a
133
141
  segment register, an address-width base register, an optional displacement, a byte count and the
134
142
  evidence for assuming the service leaves those bytes alone. Scopes resolve against the pre-call
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  name = "scientific-method-engine"
7
7
  # The release workflow writes the published version from the package's release tag.
8
- version = "7.4.0"
8
+ version = "8.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"
@@ -27,6 +27,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
27
27
  "Declared table continuations are separate conditional paths that spend continuationBudget\n"
28
28
  "(paths, totalSteps, maxSteps, visitLimit, stringIterations); ordinary computed transfers remain stopped.\n"
29
29
  "Port accesses and interrupts are hardware-boundary events; portInputs supplies port reads as assumptions.\n"
30
+ "A callModels entry at an INT n site (real mode) returns past the interrupt under its cases (leavesFlags: true\n"
31
+ "keeps the interrupt's FLAGS word on the stack); other interrupts stop.\n"
30
32
  "callModels[].preservesMemory keeps explicit, bounded pre-call byte scopes across a modeled call; other memory stays unknown.\n"
31
33
  "A scope needs a concrete segment; its base may be symbolic, such as BP in an entryFrame query.\n"
32
34
  "Each traced path's loops record lists restart edges and what changed between iterations (loopIterationLimit).\n"
@@ -7,6 +7,8 @@ amount never join or split slots. Whatever a read did not settle on the path sta
7
7
  """
8
8
  from capstone.x86 import X86_OP_IMM, X86_OP_REG
9
9
 
10
+ from .machine import NO_WRITE
11
+
10
12
  # The argument bytes one frame maps; a wider frame is mapped up to here and stays open.
11
13
  WINDOW_BYTES = 256
12
14
 
@@ -131,12 +133,27 @@ def _frame(image, events, index):
131
133
  # A read byte with no known caller writer, one the callee stored to first, or one whose producers
132
134
  # lack the slot's writer saw something other than the caller's bytes. The store check catches an
133
135
  # overwrite derived from the argument itself, which keeps the writer among its producers.
134
- stale = [i for i, at in enumerate(span) if by_byte[at]["writerSite"] is None or first_store.get(at, read["order"]) < read["order"]
135
- or by_byte[at]["writerSite"] not in read["byteProducers"][i]["producers"]]
136
+ stale, unknown = [], []
137
+ for i, at in enumerate(span):
138
+ slot = by_byte[at]
139
+ if first_store.get(at, read["order"]) < read["order"]:
140
+ stale.append(i)
141
+ elif slot["writerSite"] is None:
142
+ stale.append(i)
143
+ # Nothing on the path wrote a byte with no write, so the caller did not. A byte a modeled
144
+ # call invalidated or another address may have stored could still hold the caller's value.
145
+ if slot["reason"] != NO_WRITE:
146
+ unknown.append(i)
147
+ elif slot["writerSite"] not in read["byteProducers"][i]["producers"]:
148
+ # No callee store through the frame's segment and base explains the missing writer: a callee
149
+ # write through another address or a modeled call in the callee may or may not have replaced it.
150
+ stale.append(i)
151
+ unknown.append(i)
136
152
  partial = [s["offset"] for s in covered if s["offset"] < offset or s["offset"] + s["width"] > offset + read["argument"]["width"]]
137
153
  groupings.append({"readSite": read["site"], "readOrder": read["order"], "offset": offset, "width": read["argument"]["width"],
138
154
  "grouping": read["argument"]["grouping"], "slotOffsets": [s["offset"] for s in covered],
139
- "partialSlots": partial, "bytesNotFromSlotWriter": stale})
155
+ "partialSlots": partial, "bytesNotFromSlotWriter": stale,
156
+ "bytesOfUnknownOrigin": unknown})
140
157
  if stale:
141
158
  open_reasons.append(f"bytes {stale} of the read at {read['site']} do not come from the slot's writer")
142
159
  if partial:
@@ -182,12 +199,17 @@ def argument_frames(report, image):
182
199
 
183
200
  A path gets one map per traced call, from caller-written slots to callee reads. A site's
184
201
  groupings agree only when every path that traced a call there settled on the same read widths
185
- and groupings. Separately, a site's widths are consistent when its paths read at least one byte
186
- the caller wrote and no two reads with a different offset, width or grouping both saw one shared
187
- byte from the caller; a path that skipped a read leaves the site consistent but not agreed.
188
- A read that saw bytes the callee stored itself, or bytes with no known caller writer, stays
189
- listed and marked with the paths it was made on that way, and its conflicts stay listed, but
190
- those bytes do not decide whether the widths are consistent. The report must come from
202
+ and groupings. Separately, a site's widths are consistent (``True``) when its paths read at
203
+ least one byte the caller wrote and no two reads with a different offset, width or grouping
204
+ both saw one shared byte from the caller; a path that skipped a read leaves the site consistent
205
+ but not agreed. Bytes the callee stored itself and bytes no write on the path stored are not
206
+ the caller's and do not decide consistency. A byte of unknown origin (invalidated by a modeled
207
+ call, possibly stored through another address, or missing the slot writer among its producers
208
+ without a callee store) may be the caller's, and so may a read byte past the mapped window: a
209
+ pair of reads that would conflict on such a byte is listed in ``undecidedWidths`` and leaves the
210
+ site's ``widthsConsistent`` ``None`` unless another pair conflicts on the caller's bytes. A site
211
+ with no such pair whose reads saw no byte the caller wrote is ``None`` when some read saw a byte
212
+ of unknown origin and ``False`` otherwise. The report must come from
191
213
  ``trace`` with ``argument_window=WINDOW_BYTES``: each traced call's slots come from its
192
214
  ``argumentSlots`` record, which this removes from every path, declared continuations included.
193
215
  """
@@ -207,7 +229,7 @@ def argument_frames(report, image):
207
229
  widths = sorted({tuple(sorted({(g["offset"], g["width"], g["grouping"]) for g in f["groupings"]})) for _, f in rows})
208
230
  # Each read's paths, split by whether every byte it saw came from the caller's slot writer, and the
209
231
  # frame bytes it saw from the slot writer on any path.
210
- read_on, from_caller, not_from_caller, caller_bytes = {}, {}, {}, {}
232
+ read_on, from_caller, not_from_caller, caller_bytes, unknown_bytes = {}, {}, {}, {}, {}
211
233
  for i, f in rows:
212
234
  for g in f["groupings"]:
213
235
  key = (g["offset"], g["width"], g["grouping"])
@@ -215,14 +237,29 @@ def argument_frames(report, image):
215
237
  (not_from_caller if g["bytesNotFromSlotWriter"] else from_caller).setdefault(key, set()).add(i)
216
238
  mapped = range(min(g["width"], f["mappedBytes"] - g["offset"]))
217
239
  caller_bytes.setdefault(key, set()).update(g["offset"] + at for at in mapped if at not in g["bytesNotFromSlotWriter"])
240
+ # A read byte past the window was never mapped, so it may be the caller's too.
241
+ unmapped = range(max(0, f["mappedBytes"] - g["offset"]), g["width"])
242
+ unknown_bytes.setdefault(key, set()).update(g["offset"] + at for at in [*g["bytesOfUnknownOrigin"], *unmapped])
218
243
  reads = sorted(read_on)
219
244
  # Distinct reads that share a byte conflict: different intervals, or one interval grouped two ways.
220
245
  pairs = [(a, b) for n, a in enumerate(reads) for b in reads[n + 1:] if _overlap(a, b)]
221
246
  conflicting = [[{"offset": o, "width": w, "grouping": k} for o, w, k in pair] for pair in pairs]
222
- # Only the caller's bytes decide consistency: a pair counts when both reads saw one shared byte from
247
+ # Only the caller's bytes decide consistency: a pair conflicts when both reads saw one shared byte from
223
248
  # the slot writer. A callee reusing its argument slot as a local neither breaks nor supplies the
224
- # width the caller's argument is read at, but a read past the caller's bytes still reads them.
249
+ # width the caller's argument is read at, but a read past the caller's bytes still reads them. A pair
250
+ # that would conflict if bytes of unknown origin were the caller's is undecided.
225
251
  caller_conflict = any(caller_bytes[a] & caller_bytes[b] for a, b in pairs)
252
+ undecided = [(a, b) for a, b in pairs if not caller_bytes[a] & caller_bytes[b]
253
+ and (caller_bytes[a] | unknown_bytes[a]) & (caller_bytes[b] | unknown_bytes[b])]
254
+ if caller_conflict:
255
+ consistent = False
256
+ elif undecided:
257
+ consistent = None
258
+ elif any(caller_bytes.values()):
259
+ consistent = True
260
+ else:
261
+ # No read saw a byte from the slot writers; one of unknown origin leaves open whether any read did.
262
+ consistent = None if any(unknown_bytes.values()) else False
226
263
  report["argumentFrameSites"].append({
227
264
  "callSite": site, "paths": sorted({i for i, _ in rows}), "frames": len(rows),
228
265
  "unsettledPaths": sorted({i for i, f in rows if not f["settledOnThisPath"]}),
@@ -231,7 +268,8 @@ def argument_frames(report, image):
231
268
  "fromCallerOnPaths": sorted(from_caller.get((o, w, k), ())),
232
269
  "notFromCallerOnPaths": sorted(not_from_caller.get((o, w, k), ()))} for o, w, k in reads],
233
270
  "conflictingWidths": conflicting,
234
- "widthsConsistent": any(caller_bytes.values()) and not caller_conflict,
271
+ "undecidedWidths": [[{"offset": o, "width": w, "grouping": k} for o, w, k in pair] for pair in undecided],
272
+ "widthsConsistent": consistent,
235
273
  "agreed": len(widths) == 1 and all(f["settledOnThisPath"] for _, f in rows),
236
274
  "interpretation": "read widths per traced path; paths that never reached this call are not represented"})
237
275
  return report
@@ -25,6 +25,9 @@ FLAT_PORT_REASON = "port access in the flat model depends on I/O privilege, whic
25
25
  # The write-log key that marks a point where the model forgot all memory.
26
26
  MEMORY_CLEARED = ("memory-cleared",)
27
27
 
28
+ # The ``unwritten`` cause of a byte that no write on the path stored.
29
+ NO_WRITE = "no write on this path"
30
+
28
31
 
29
32
  class WriteLog:
30
33
  """Append-only list of (key, previous value) pairs, one per register or memory byte a write changes.
@@ -299,7 +302,7 @@ class State:
299
302
  return dict(lost)
300
303
  if self.memory_cleared is not None:
301
304
  return {"cause": "dropped by a modeled call", "order": self.memory_cleared}
302
- return {"cause": "no write on this path", "order": None}
305
+ return {"cause": NO_WRITE, "order": None}
303
306
 
304
307
  def byte_writer(self, index, key):
305
308
  """The byteProducers row of one accessed byte: its producers and the write that stored it."""
@@ -56,7 +56,7 @@ def validate_scopes(model, bits, flat):
56
56
  ranges.append((displacement, displacement + size))
57
57
 
58
58
 
59
- def capture_scopes(state, model):
59
+ def capture_scopes(state, model, frame_bytes=0):
60
60
  """Resolve each scope against the pre-call state and snapshot its bytes.
61
61
 
62
62
  Returns ``(values, unread, descriptions)``: the cached bytes, the unknown term names of bytes
@@ -68,8 +68,23 @@ def capture_scopes(state, model):
68
68
  share a linear byte (segment aliases included). A symbolic base may address any byte of its
69
69
  segment, so it may alias every scope whose segment range overlaps that segment. An uncached
70
70
  byte stays uncached after the call.
71
+
72
+ ``frame_bytes`` is the size of the return frame the processor writes below SS:SP when the modeled
73
+ instruction runs: the return address of a call, or FLAGS, CS and IP of an interrupt. Those bytes
74
+ no longer hold their pre-call values, so a scope that shares a byte with that frame on the same
75
+ segment and base raises ``StopPath``. A scope that only may alias the frame stays the query's
76
+ hypothesis.
71
77
  """
72
78
  values, unread, descriptions, resolved = {}, {}, [], []
79
+ frame = None
80
+ if frame_bytes:
81
+ try:
82
+ frame_seg, frame_base, _, frame_keys = state.keys(
83
+ state.segment("ss"), op("sub", state.reg(state.sp), const(frame_bytes, state.bits)), frame_bytes)
84
+ frame = ((frame_seg, frame_base), set(frame_keys))
85
+ except StopPath:
86
+ # A frame that wraps past offset zero of the stack segment is not checked.
87
+ frame = None
73
88
  for scope in model.get("preservesMemory", []):
74
89
  segment, base = state.segment(scope["segment"]), state.reg(scope["base"])
75
90
  if segment.number is None:
@@ -91,6 +106,8 @@ def capture_scopes(state, model):
91
106
  shared = domains_may_overlap(prior_domain, domain)
92
107
  if shared:
93
108
  raise StopPath("preservesMemory intervals overlap or alias")
109
+ if frame is not None and frame[0] == (seg, group_base) and not frame[1].isdisjoint(keys):
110
+ raise StopPath("preservesMemory scope covers the return frame the processor writes below SP")
94
111
  resolved.append(((seg, group_base), set(keys), domain))
95
112
  linear = seg == ("linear",)
96
113
  cached = 0
@@ -6,7 +6,7 @@ whose paths were not all read (a stop, a limit, a dropped path) is undecided, ne
6
6
  """
7
7
  from bisect import bisect_right
8
8
  from .image import integer
9
- from .machine import ALIASES, State
9
+ from .machine import ALIASES, NO_WRITE, State
10
10
 
11
11
  KINDS = ("reach", "order", "lastWriter", "containment", "relation", "origin")
12
12
  OPERATORS = ("eq", "ne", "lt", "le", "gt", "ge")
@@ -333,7 +333,7 @@ class _Path:
333
333
  # Orders of modeled call returns, ascending.
334
334
  self.modeled = []
335
335
  # Unknown memory term name -> the first order of a read that showed its bytes had no
336
- # modeled value for a reason other than "no write on this path".
336
+ # modeled value for a reason other than NO_WRITE.
337
337
  self.first_drop = {}
338
338
  # For each event, the most recent branch earlier in the same frame (same entry and depth,
339
339
  # completed callee frames skipped), or None.
@@ -343,7 +343,7 @@ class _Path:
343
343
  self.by_site.setdefault((e["site"], e["kind"]), []).append(e["order"])
344
344
  if e["kind"] == "call-return" and e.get("modeled"):
345
345
  self.modeled.append(e["order"])
346
- if e["kind"] == "read" and any((r.get("unwritten") or {}).get("cause", "no write on this path") != "no write on this path"
346
+ if e["kind"] == "read" and any((r.get("unwritten") or {}).get("cause", NO_WRITE) != NO_WRITE
347
347
  for r in e.get("byteProducers", ())):
348
348
  for n in _leaves(e["value"]["expression"], set()):
349
349
  if n.startswith("memory:"):
@@ -525,7 +525,7 @@ def _occurrence(control, path, anchor, image):
525
525
  "writer": {"site": writer["site"], "order": writer["order"], "entry": writer["entry"], "depth": writer["depth"]}})
526
526
  else:
527
527
  unwritten = row.get("unwritten") or {"cause": "unknown", "order": None}
528
- verdict = (("held" if ENTRY_STATE in allowed else "violated") if unwritten["cause"] == "no write on this path"
528
+ verdict = (("held" if ENTRY_STATE in allowed else "violated") if unwritten["cause"] == NO_WRITE
529
529
  else "undecided")
530
530
  rows.append({"index": row["index"], "verdict": verdict, "writer": None, "unwritten": unwritten})
531
531
  verdicts.append(verdict)
@@ -10,6 +10,7 @@ from .values import const, unknown, sources, op, Value
10
10
  from .result_flow import validate_contracts, result_contracts
11
11
  from .loops import LoopTracker
12
12
  from .memory_scopes import validate_scopes, capture_scopes, retain_scopes, scope_history
13
+ from .pcode_backend import interrupt_vector
13
14
 
14
15
  def call_target(image, site, ins):
15
16
  if ins.mnemonic in ("lcall", "ljmp"):
@@ -27,6 +28,19 @@ PORTS = ("in", "out", "insb", "insw", "insd", "outsb", "outsw", "outsd")
27
28
  PORT_INPUTS = ("in", "insb", "insw", "insd")
28
29
 
29
30
 
31
+ def modeled_interrupt(image, ins, site):
32
+ """The vector of the ``INT n`` at ``site`` that a call model there describes, or None.
33
+
34
+ Only an ``INT n`` in the real-mode model takes a model. INT1, INT3 (also when encoded as
35
+ ``INT 1`` or ``INT 3``), INTO and every interrupt in the PE32 flat model keep stopping the path,
36
+ with or without a model at their site (ADR 0017). The vector can be 0, so test it against None.
37
+ """
38
+ if ins is None or ins.mnemonic != "int" or image.flat:
39
+ return None
40
+ vector, _ = interrupt_vector(image.flat, ins, site)
41
+ return None if vector in (1, 3) else vector
42
+
43
+
30
44
  def base_mnemonic(ins):
31
45
  # Capstone names REP/REPNE/BND prefixes in the mnemonic ("repz ret", "rep insb", "bnd jmp").
32
46
  return ins.mnemonic.split()[-1]
@@ -453,6 +467,11 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
453
467
  raise ValueError("A model requires 1..16 return cases")
454
468
  if "returnBytes" in model and (type(model["returnBytes"]) is not int or model["returnBytes"] not in (2, 4)):
455
469
  raise ValueError("Modeled returnBytes must be 2 or 4")
470
+ if "returnBytes" in model and modeled_interrupt(image, image.decode(model["site"]), model["site"]) is not None:
471
+ raise ValueError("An interrupt model takes no returnBytes: the interrupt returns past its own FLAGS, CS and IP")
472
+ if "leavesFlags" in model and (model["leavesFlags"] is not True
473
+ or modeled_interrupt(image, image.decode(model["site"]), model["site"]) is None):
474
+ raise ValueError("leavesFlags must be true and needs an INT n site in the real-mode model")
456
475
  if any(r not in REGISTERS for r in model.get("preserves", [])):
457
476
  raise ValueError("Model preserves must name full registers")
458
477
  validate_scopes(model, image.bits, image.flat)
@@ -460,6 +479,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
460
479
  for r, n in case.get("registers", {}).items():
461
480
  if r not in ALIASES or type(n) is not int or not 0 <= n < 1 << ALIASES[r][2]:
462
481
  raise ValueError("Invalid model register")
482
+ model_at = {model["site"]: model for model in models}
463
483
  explicit_continuation_budget = validate_continuation_budget(config)
464
484
  observed_frame = entry_frame(image, config, entry) if arrive is None else None
465
485
  root = State(entry, image, config)
@@ -515,6 +535,52 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
515
535
  gap["callStack"] = open_calls(s)
516
536
  global_gaps.append(gap)
517
537
 
538
+ def capture_model_scopes(s, model, frame_bytes):
539
+ # Scopes resolve against the state before the modeled instruction runs. frame_bytes is the
540
+ # return frame the processor writes below SP, which no scope may claim to preserve.
541
+ values, unread, scopes = capture_scopes(s, model, frame_bytes)
542
+ return values, unread, scopes, scope_history(s, values, unread)
543
+
544
+ def model_returns(s, model, captured, following, assumption, limit_reason, target, **marks):
545
+ # One child per case, each a conditional return under the query's model. ``marks`` extend
546
+ # the conditionalModels entry and the modeled call-return event (an interrupt's vector).
547
+ nonlocal created
548
+ at = s.at
549
+ kept_values, kept_unread, preserved_scopes, kept_history = captured
550
+ for case in model["cases"]:
551
+ if created >= max_paths:
552
+ path_limit(at, s, limit_reason)
553
+ break
554
+ child = deepcopy(s)
555
+ created += 1
556
+ for r in REGISTERS:
557
+ if r not in model.get("preserves", []) and r not in ("esp", "cs"):
558
+ child.setreg(r, unknown(f"modeled-call:{at}:{r}", ALIASES[r][2]), at)
559
+ child.clear_memory()
560
+ retain_scopes(child, kept_values, kept_unread, kept_history)
561
+ if model.get("leavesFlags"):
562
+ # The handler returned with a far return over the interrupt's FLAGS word, which stays on
563
+ # the stack. Its word is the pre-interrupt FLAGS snapshot, so a later POPF restores them.
564
+ child.save_flags(16)
565
+ child.forget_flags()
566
+ child.direction_flag = unknown(f"modeled-call:{at}:DF:{child.flag_serial}", 1, at)
567
+ child.interrupt_flag = unknown(f"modeled-call:{at}:IF:{child.flag_serial}", 1, at)
568
+ for r, n in case.get("registers", {}).items():
569
+ child.setreg(r, const(n, ALIASES[r][2], at), at)
570
+ child.conditional.append({"site": at, "evidence": model["evidence"], **marks,
571
+ "assumption": assumption + "; memory effects unresolved"
572
+ + (" outside explicit scopes" if preserved_scopes else ""),
573
+ "preservedMemoryScopes": preserved_scopes})
574
+ # The scopes are reported once, on the path's conditionalModels entry; the event cites its index.
575
+ child.event("call-return", callSite=at, callerEntry=s.frames[-1]["entry"],
576
+ # A modeled call's result contracts are its target's; an interrupt's target is None,
577
+ # which no contract names.
578
+ resultContracts=result_contracts(child, contracts, target),
579
+ registers=snapshot(child), modeled=True, **marks,
580
+ unknownMemoryEffects=True, conditionalModel=len(child.conditional) - 1)
581
+ child.at = following
582
+ pending.append(child)
583
+
518
584
  def finish(s, reason=None, returned=False):
519
585
  if continuing and reason and reason.startswith(STRING_BUDGET_STOP):
520
586
  # machine.py names no budget; a continuation's string iterations come from continuationBudget.
@@ -712,6 +778,27 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
712
778
  string_step(state, ins, count)
713
779
  state.at = following
714
780
  continue
781
+ interrupt_model = model_at.get(at) if m == "int" else None
782
+ vector = modeled_interrupt(image, ins, at) if interrupt_model else None
783
+ if vector is not None:
784
+ # The handler is not executed. The boundary event is kept, and each case returns to the
785
+ # next instruction under the query's model, with CS as before the interrupt and SP as before it or,
786
+ # under leavesFlags, one FLAGS word below (ADR 0017).
787
+ # Scopes resolve first, so a path that stops on them reports the boundary unmodeled.
788
+ try:
789
+ captured = capture_model_scopes(state, interrupt_model, 6)
790
+ except StopPath:
791
+ state.event("hardware-boundary", boundary="interrupt", mnemonic=m, vector=vector,
792
+ interpretation="the interrupt handler and its effects are not modeled")
793
+ raise
794
+ state.event("hardware-boundary", boundary="interrupt", mnemonic=m, vector=vector, modeled=True,
795
+ interpretation="the interrupt handler is not executed; a callModels case supplies its return")
796
+ model_returns(state, interrupt_model, captured, following,
797
+ "interrupt returns to the next instruction with its FLAGS word left on the stack and CS unchanged"
798
+ if interrupt_model.get("leavesFlags") else
799
+ "interrupt returns to the next instruction with balanced stack and CS unchanged",
800
+ "path limit at modeled interrupt", None, boundary="interrupt", vector=vector)
801
+ break
715
802
  if m in ("call", "lcall"):
716
803
  target, provenance = call_target(image, at, ins)
717
804
  indirect_value = None
@@ -730,7 +817,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
730
817
  push_cs = (not image.flat and m == "call" and previous is not None and previous.mnemonic == "push"
731
818
  and previous.size + state.path[-2] == at and previous.operands[0].type == X86_OP_REG
732
819
  and previous.reg_name(previous.operands[0].reg) == "cs" and previous.operands[0].size == 2)
733
- model = next((x for x in models if x["site"] == at), None)
820
+ model = model_at.get(at)
734
821
  if model:
735
822
  return_bytes = model.get("returnBytes", 4 if m == "lcall" else image.bits // 8)
736
823
  # The encoding before the call decides validity; a path that reaches the call
@@ -745,38 +832,13 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
745
832
  raise StopPath("push-CS/near-call model requires an explicit four-byte return contract")
746
833
  # Scopes resolve against the pre-call state: before the modeled frame consumes an
747
834
  # already-pushed CS word and before a case replaces registers.
748
- kept_values, kept_unread, preserved_scopes = capture_scopes(state, model)
749
- kept_history = scope_history(state, kept_values, kept_unread)
835
+ captured = capture_model_scopes(state, model, 4 if m == "lcall" else image.bits // 8)
750
836
  if push_cs:
751
837
  actual_cs = state.pop(2)
752
838
  if actual_cs.term != state.reg("cs").term:
753
839
  raise StopPath("modeled far return segment changed")
754
- for case in model["cases"]:
755
- if created >= max_paths:
756
- path_limit(at, state, "path limit at modeled call")
757
- break
758
- child = deepcopy(state)
759
- created += 1
760
- for r in REGISTERS:
761
- if r not in model.get("preserves", []) and r not in ("esp", "cs"):
762
- child.setreg(r, unknown(f"modeled-call:{at}:{r}", ALIASES[r][2]), at)
763
- child.clear_memory()
764
- retain_scopes(child, kept_values, kept_unread, kept_history)
765
- child.forget_flags()
766
- child.direction_flag = unknown(f"modeled-call:{at}:DF:{child.flag_serial}", 1, at)
767
- child.interrupt_flag = unknown(f"modeled-call:{at}:IF:{child.flag_serial}", 1, at)
768
- for r, n in case.get("registers", {}).items():
769
- child.setreg(r, const(n, ALIASES[r][2], at), at)
770
- child.conditional.append({"site": at, "evidence": model["evidence"],
771
- "assumption": "call returns with balanced stack; memory effects unresolved"
772
- + (" outside explicit scopes" if preserved_scopes else ""),
773
- "preservedMemoryScopes": preserved_scopes})
774
- # The scopes are reported once, on the path's conditionalModels entry; the event cites its index.
775
- child.event("call-return", callSite=at, callerEntry=state.frames[-1]["entry"],
776
- resultContracts=result_contracts(child, contracts, target), registers=snapshot(child), modeled=True,
777
- unknownMemoryEffects=True, conditionalModel=len(child.conditional) - 1)
778
- child.at = following
779
- pending.append(child)
840
+ model_returns(state, model, captured, following, "call returns with balanced stack",
841
+ "path limit at modeled call", target)
780
842
  break
781
843
  if target is None:
782
844
  raise StopPath("unresolved call: " + provenance.get("reason", "outside mapped code"))