scientific-method-engine 13.1.0__tar.gz → 13.2.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 (78) hide show
  1. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/cli.py +4 -1
  4. scientific_method_engine-13.2.0/src/scientific_method_engine/x86/reach.py +246 -0
  5. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/reports.py +5 -3
  6. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/trace.py +17 -8
  7. scientific_method_engine-13.2.0/tests/test_reach.py +173 -0
  8. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/.gitignore +0 -0
  9. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/LICENSE +0 -0
  10. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/README.md +0 -0
  11. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/__init__.py +0 -0
  12. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/__main__.py +0 -0
  13. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  14. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  15. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  16. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  17. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  18. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  19. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  20. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  21. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  22. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  23. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  24. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  25. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  26. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  27. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  28. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  29. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  30. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  31. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  32. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  33. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  34. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  35. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  36. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  37. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  38. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  39. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  40. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  41. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  42. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  43. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  44. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  45. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +0 -0
  46. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  47. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  48. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  49. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  50. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/image.py +0 -0
  51. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/loops.py +0 -0
  52. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/machine.py +0 -0
  53. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  54. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  55. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  56. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/pe.py +0 -0
  57. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/relational.py +0 -0
  58. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  59. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/values.py +0 -0
  60. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/oracle.py +0 -0
  61. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_continuation_budget.py +0 -0
  62. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_dispatch.py +0 -0
  63. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_effect_order.py +0 -0
  64. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_enter_frames.py +0 -0
  65. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_entry_frame.py +0 -0
  66. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_indirect_far_transfers.py +0 -0
  67. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_interrupt_models.py +0 -0
  68. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_loops.py +0 -0
  69. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_memory_scopes.py +0 -0
  70. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_nested_frame_request.py +0 -0
  71. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_oracle.py +0 -0
  72. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_pe.py +0 -0
  73. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_relational_controls.py +0 -0
  74. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_return_checks.py +0 -0
  75. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_successor_rule.py +0 -0
  76. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_table_continuations.py +0 -0
  77. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.0}/tests/test_term_limit.py +0 -0
  78. {scientific_method_engine-13.1.0 → scientific_method_engine-13.2.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: 13.1.0
3
+ Version: 13.2.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
@@ -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 = "13.1.0"
8
+ version = "13.2.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"
@@ -13,7 +13,7 @@ PREPARED_CONFIG_LIMIT = 16 * 1024 * 1024
13
13
  # The header names the decoder and instruction semantics that actually ran, not the pins in pyproject.toml.
14
14
  DECODER = "capstone " + capstone.__version__
15
15
  INSTRUCTION_SEMANTICS = f"pypcode {pypcode.__version__} (Ghidra SLEIGH x86)"
16
- USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bounds|owner|callees|trace|uses|arguments|"
16
+ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bounds|owner|callees|reach|trace|uses|arguments|"
17
17
  "effects|returns|memory|incoming|call-order|guards|allocation|dispatch> <config.json|->\n"
18
18
  "effects includes ordered path writes/calls and local restoration witnesses; transactionality remains unestablished.\n"
19
19
  "callees compares its edges with an ExportCallEdges.java export given as ghidraCallEdges;\n"
@@ -21,6 +21,9 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
21
21
  "agreed is false where Ghidra ends the function at an instruction the engine reads past (ghidraEndsFunction),\n"
22
22
  "continues past one the engine stops at (ghidraContinues),\n"
23
23
  "or continues at another address than the next instruction (ghidraFallsThroughElsewhere).\n"
24
+ "reach lists the target sites the starts reach over resolved calls and jumps, with the fewest-call chain\n"
25
+ "and the routines every read route passes, and lists every reached transfer it could not resolve;\n"
26
+ "a leaves routine is reached but not read, and its reason is repeated in the report.\n"
24
27
  "trace, arguments, effects, returns, guards, memory and allocation check relationalControls:\n"
25
28
  "a violated control fails the report; an undecided one is reported and never counts as held.\n"
26
29
  "A lastWriter control with an address inspects that memory at its checkpoint anchors without a read.\n"
@@ -0,0 +1,246 @@
1
+ """Transitive reachability from established starts to target sites over the entry-path CFG."""
2
+ from collections import deque
3
+ from .image import integer
4
+ from .trace import walk, cfg_step, base_mnemonic, unsupported_transfer, holding_instruction, INTERRUPTS, RETURNS
5
+ from .pcode_backend import interrupt_vector
6
+
7
+ # The virtual root of the dominator computation; no file offset is negative.
8
+ ROOT = -1
9
+ CALLS = ("call", "lcall")
10
+ UNSUPPORTED = "unsupported control-transfer frame encoding"
11
+ LEAF_OVERLAP = "leaf start inside a reached instruction; the leaf is not decoded, so its boundary is unchecked"
12
+
13
+
14
+ def _sites(value, label, image, limit=256):
15
+ if not isinstance(value, list) or not 1 <= len(value) <= limit or len(set(map(repr, value))) != len(value):
16
+ raise ValueError(f"{label} must be a list of 1..{limit} distinct file offsets")
17
+ for at in value:
18
+ integer(at, 0, len(image.data) - 1, label)
19
+ if image.region(at) is None:
20
+ raise ValueError(f"{label} {at} is outside declared code")
21
+ return list(value)
22
+
23
+
24
+ def _leaves(value, image, starts):
25
+ if not isinstance(value, list) or len(value) > 256:
26
+ raise ValueError("leaves must be a list of at most 256 objects")
27
+ leaves = {}
28
+ for leaf in value:
29
+ if not isinstance(leaf, dict) or set(leaf) != {"routine", "reason"}:
30
+ raise ValueError("Each leaf needs exactly routine and reason")
31
+ at = integer(leaf["routine"], 0, len(image.data) - 1, "leaf routine")
32
+ if image.region(at) is None:
33
+ raise ValueError(f"leaf routine {at} is outside declared code")
34
+ if not isinstance(leaf["reason"], str) or not leaf["reason"].strip():
35
+ raise ValueError("A leaf needs a nonempty reason")
36
+ if at in leaves:
37
+ raise ValueError("Duplicate leaf routine")
38
+ if at in starts:
39
+ raise ValueError("A start cannot be a leaf")
40
+ leaves[at] = leaf["reason"]
41
+ return leaves
42
+
43
+
44
+ def _kinds(at, ins, step):
45
+ """Each successor of ``step`` with how the CFG reaches it: call, return, table, interrupt, jump or fall."""
46
+ m, following = base_mnemonic(ins), at + ins.size
47
+ targets = {e["target"] for e in step.edges if e["target"] is not None}
48
+ rows, called = [], False
49
+ for successor in step.successors:
50
+ if step.supplied:
51
+ kind = "table"
52
+ elif m in CALLS:
53
+ # A call names its target first; a call to the next instruction lists that site twice.
54
+ kind = "call" if successor in targets and not called else "return"
55
+ called = called or kind == "call"
56
+ elif m in INTERRUPTS:
57
+ kind = "interrupt"
58
+ elif successor == following and m not in ("jmp", "ljmp") and (successor not in targets or len(rows) > 0):
59
+ kind = "fall"
60
+ else:
61
+ kind = "jump"
62
+ rows.append((successor, kind))
63
+ return rows
64
+
65
+
66
+ def _dominators(order, predecessors):
67
+ """Immediate dominators (Cooper, Harvey and Kennedy) of every node in ``order``, a reverse postorder from ROOT."""
68
+ index = {node: i for i, node in enumerate(order)}
69
+ idom = {ROOT: ROOT}
70
+
71
+ def intersect(a, b):
72
+ while a != b:
73
+ while index[a] > index[b]:
74
+ a = idom[a]
75
+ while index[b] > index[a]:
76
+ b = idom[b]
77
+ return a
78
+ changed = True
79
+ while changed:
80
+ changed = False
81
+ for node in order[1:]:
82
+ done = [p for p in predecessors[node] if p in idom]
83
+ new = done[0]
84
+ for p in done[1:]:
85
+ new = intersect(p, new)
86
+ if idom.get(node) != new:
87
+ idom[node] = new
88
+ changed = True
89
+ return idom
90
+
91
+
92
+ def reach(image, config):
93
+ """Which target sites the starts reach over resolved calls and jumps, by which chain, and what the walk could not read.
94
+
95
+ The walk decodes from ``starts`` (established region entries) and follows every resolved call
96
+ into its callee and on at its return site, every resolved jump and branch, the rows of a
97
+ declared indirect jump table, and every interrupt to the next instruction. A ``leaves`` routine
98
+ is reached but never decoded. Each reached target gets one chain with the fewest calls, the
99
+ assumptions its route rests on, and the routines on every route to it within the read graph.
100
+ """
101
+ from .reports import entries
102
+ starts = _sites(config.get("starts"), "starts", image)
103
+ established = set(entries(image))
104
+ for at in starts:
105
+ if at not in established:
106
+ raise ValueError(f"Reach start {at} must be an established region entry")
107
+ targets = _sites(config.get("targets"), "targets", image)
108
+ leaves = _leaves(config.get("leaves", []), image, set(starts))
109
+ controls = config.get("controls", [])
110
+ if (not isinstance(controls, list) or len(controls) > 256 or any(type(at) is not int for at in controls)
111
+ or len(set(controls)) != len(controls)):
112
+ raise ValueError("Positive controls must be at most 256 distinct file offsets")
113
+ limit = integer(config.get("limit", 1000), 1, 10000, "result limit")
114
+ instruction_limit = config.get("instructionLimit", 10000)
115
+ seen, walk_gaps, _, _, contested = walk(image, starts, instruction_limit, follow_interrupts=True, stops=frozenset(leaves))
116
+
117
+ graph, unresolved, interrupts, resolved_calls = {}, [], [], {}
118
+ for at, ins in sorted(seen.items()):
119
+ step = cfg_step(image, at, ins, follow_interrupts=True)
120
+ graph[at] = [(s, kind) for s, kind in _kinds(at, ins, step) if s in seen or s in leaves]
121
+ m = base_mnemonic(ins)
122
+ text = (ins.mnemonic + " " + ins.op_str).strip()
123
+ kind = "call" if m in CALLS else "return" if m in RETURNS else "jump"
124
+ if unsupported_transfer(image, ins):
125
+ unresolved.append({"site": at, "instruction": text, "kind": kind, "reason": UNSUPPORTED})
126
+ for edge in step.edges:
127
+ if edge["target"] is None:
128
+ unresolved.append({"site": at, "instruction": text, "kind": kind,
129
+ "reason": edge["provenance"].get("reason", "target outside declared regions")})
130
+ elif m in CALLS:
131
+ resolved_calls[at] = edge["target"]
132
+ if m in INTERRUPTS:
133
+ vector, conditional = interrupt_vector(image.flat, ins, at)
134
+ interrupts.append({"site": at, "instruction": text, "vector": vector, "conditional": conditional})
135
+ for at in leaves:
136
+ graph.setdefault(at, [])
137
+
138
+ # Fewest calls first: entering a callee costs one, every other edge nothing (0-1 breadth-first search).
139
+ distance, parent, routine = {}, {}, {}
140
+ queue = deque()
141
+ for at in starts:
142
+ distance[at], parent[at], routine[at] = 0, None, at
143
+ queue.append((0, at))
144
+ while queue:
145
+ cost, at = queue.popleft()
146
+ if cost > distance[at]:
147
+ continue
148
+ for successor, kind in graph.get(at, []):
149
+ step_cost = cost + (kind == "call")
150
+ if successor not in distance or step_cost < distance[successor]:
151
+ distance[successor], parent[successor] = step_cost, (at, kind)
152
+ routine[successor] = successor if kind == "call" else routine[at]
153
+ (queue.append if kind == "call" else queue.appendleft)((step_cost, successor))
154
+
155
+ # Dominators over everything reached, from a virtual root that leads to every start.
156
+ successors = {ROOT: list(starts)} | {at: [s for s, _ in graph.get(at, [])] for at in distance}
157
+ order, visited, stack = [], {ROOT}, [(ROOT, iter(successors[ROOT]))]
158
+ while stack:
159
+ node, children = stack[-1]
160
+ child = next(children, None)
161
+ if child is None:
162
+ order.append(node)
163
+ stack.pop()
164
+ elif child not in visited:
165
+ visited.add(child)
166
+ stack.append((child, iter(successors[child])))
167
+ order.reverse()
168
+ predecessors = {node: [] for node in order}
169
+ for node in order:
170
+ for child in successors[node]:
171
+ predecessors[child].append(node)
172
+ idom = _dominators(order, predecessors)
173
+ routine_starts = set(starts) | {target for at, target in resolved_calls.items() if target in distance}
174
+
175
+ def chain(target):
176
+ hops, assumed_returns, tables, continued = [], [], [], []
177
+ at = target
178
+ while parent[at] is not None:
179
+ previous, kind = parent[at]
180
+ if kind == "call":
181
+ hops.append({"callSite": previous, "routine": at})
182
+ elif kind == "return":
183
+ assumed_returns.append(previous)
184
+ elif kind == "table":
185
+ tables.append({"site": previous, "target": at})
186
+ elif kind == "interrupt":
187
+ continued.append(previous)
188
+ at = previous
189
+ hops.append({"routine": at})
190
+ return {"chain": hops[::-1], "calls": distance[target],
191
+ "route": {"assumedReturns": assumed_returns[::-1], "declaredTableJumps": tables[::-1],
192
+ "interruptsContinued": continued[::-1]}}
193
+
194
+ rows = []
195
+ for target in targets:
196
+ row = {"target": target}
197
+ if target in distance:
198
+ cut, at = [], idom[target]
199
+ while at != ROOT:
200
+ if at in routine_starts:
201
+ cut.append(at)
202
+ at = idom[at]
203
+ row |= {"reached": True, "routine": routine[target], "leaf": target in leaves, **chain(target),
204
+ "throughEveryRoute": cut[::-1]}
205
+ else:
206
+ holder = holding_instruction(seen, target)
207
+ row |= {"reached": False, "status": "inside a reached instruction" if holder is not None
208
+ else "start of a contested instruction" if target in contested else "not reached",
209
+ **({"insideInstruction": holder} if holder is not None else {})}
210
+ rows.append(row)
211
+
212
+ for row in unresolved + interrupts:
213
+ row["routine"] = routine.get(row["site"])
214
+ unresolved_sites = {row["site"] for row in unresolved}
215
+ gaps = [g for g in walk_gaps if g["site"] not in unresolved_sites and g["site"] not in contested]
216
+ # The walk never decodes a leaf, so its overlap check cannot see a leaf start inside a decoded instruction.
217
+ gaps += [{"site": at, "reason": LEAF_OVERLAP, "insideInstruction": holding_instruction(seen, at)}
218
+ for at in sorted(leaves) if at in distance and holding_instruction(seen, at) is not None]
219
+ for at in controls:
220
+ if at not in resolved_calls:
221
+ raise ValueError(f"Positive control {at} missed or not resolved")
222
+ call_sites = {}
223
+ for site, target in sorted(resolved_calls.items()):
224
+ call_sites.setdefault(target, []).append(site)
225
+ leaf_rows = [{"routine": at, "reason": reason, "reached": at in distance, "callSites": call_sites.get(at, [])}
226
+ for at, reason in leaves.items()]
227
+ counts = {"routines": len(routine_starts), "instructions": len(seen), "unresolved": len(unresolved),
228
+ "interrupts": len(interrupts), "gaps": len(gaps), "contested": len(contested)}
229
+ return {"starts": starts, "targets": rows, "leaves": leaf_rows,
230
+ "reachedRoutines": sorted(routine_starts), "counts": counts,
231
+ "unresolved": unresolved[:limit], "interrupts": interrupts[:limit], "gaps": gaps[:limit],
232
+ "contested": sorted(contested)[:limit],
233
+ "truncated": any(len(x) > limit for x in (unresolved, interrupts, gaps, contested)),
234
+ "controls": [{"site": at, "target": resolved_calls[at]} for at in controls],
235
+ "negativeUsable": bool(controls) and not (unresolved or gaps or contested),
236
+ "assumptions": ["each reached call returns to its next instruction",
237
+ "each reached interrupt returns to its next instruction; interrupt handlers are not read",
238
+ "each leaf calls nothing, for the reason it gives",
239
+ "each declared indirect jump table holds the routes its declaration gives"],
240
+ "exclusions": ["computed call and jump targets (listed in unresolved)", "unrelocated far calls",
241
+ "code reached only from outside the starts", "runtime reachability"],
242
+ "interpretation": "Routes over the decoded entry-path CFG from the starts. A chain has the fewest calls; "
243
+ "throughEveryRoute lists the routine starts every read route to the target passes, "
244
+ "and an unresolved transfer may add a route that passes none of them. "
245
+ "negativeUsable needs controls and no unresolved transfer, gap or contested instruction, "
246
+ "and still rests on the listed assumptions and leaves."}
@@ -12,7 +12,7 @@ from .argument_frames import WINDOW_BYTES, argument_frames, stack_cleanup
12
12
  from .memory_scopes import model_scopes
13
13
  from .result_flow import return_flows
14
14
  from .image import Image, integer
15
- from .trace import (trace, walk, cfg_step, call_target, unsupported_transfer, uncovered, base_mnemonic, OVERLAP_REASON, CONTESTED_REASON,
15
+ from .trace import (trace, walk, cfg_step, call_target, unsupported_transfer, uncovered, holding_instruction, base_mnemonic, OVERLAP_REASON, CONTESTED_REASON,
16
16
  RETURNS, INTERRUPTS, PORTS, PORT_INPUTS, port_width, budget_input)
17
17
  from .pcode_backend import interrupt_vector
18
18
 
@@ -176,8 +176,7 @@ def incoming(image, config):
176
176
  if site in contested:
177
177
  row["position"] = {"meaning": "start of a contested instruction"}
178
178
  continue
179
- # An x86 instruction is at most 15 bytes, so only the starts just before the site can hold it.
180
- inside = next((at for at in range(max(site - 14, 0), site) if at in seen and site < at + seen[at].size), None)
179
+ inside = holding_instruction(seen, site)
181
180
  if inside is not None:
182
181
  row["position"] = {"insideInstruction": inside, "meaning": "bytes of a reached instruction; a call here needs an overlapping start"}
183
182
  continue
@@ -1729,6 +1728,9 @@ def _run_report(image, config, command):
1729
1728
  return owner(image, config)
1730
1729
  if command == "callees":
1731
1730
  return callees(image, config)
1731
+ if command == "reach":
1732
+ from .reach import reach
1733
+ return reach(image, config)
1732
1734
  if command == "call-order":
1733
1735
  return call_order(image, config)
1734
1736
  if command == "incoming":
@@ -160,11 +160,12 @@ class Step(NamedTuple):
160
160
  supplied: bool = False
161
161
 
162
162
 
163
- def cfg_step(image, at, ins, follow_flat_ports=False, step_over_calls=False):
163
+ def cfg_step(image, at, ins, follow_flat_ports=False, step_over_calls=False, follow_interrupts=False):
164
164
  """The successors of ``ins`` decoded at ``at``, under the rule ``walk`` and the ``uses`` caller continuation share.
165
165
 
166
- An unsupported transfer encoding, a return, an unconditional jump without a resolved target, an
167
- interrupt, ``hlt`` and, unless ``follow_flat_ports``, a PE32 port access end the branch. A
166
+ An unsupported transfer encoding, a return, an unconditional jump without a resolved target,
167
+ ``hlt``, an interrupt unless ``follow_interrupts`` (which continues at the next instruction, as
168
+ ``body()`` does) and, unless ``follow_flat_ports``, a PE32 port access end the branch. A
168
169
  conditional jump or loop continues at its resolved target and at the next instruction. A declared
169
170
  indirect jump continues at its table rows only. A call continues at its resolved target and at
170
171
  its return site; with ``step_over_calls`` it continues at its return site only and its target
@@ -197,7 +198,7 @@ def cfg_step(image, at, ins, follow_flat_ports=False, step_over_calls=False):
197
198
  successors.append(target)
198
199
  if m in ("jmp", "ljmp"):
199
200
  return Step(successors, False, None, gaps, edges)
200
- if m in INTERRUPTS or m == "hlt":
201
+ if m == "hlt" or (m in INTERRUPTS and not follow_interrupts):
201
202
  gaps.append({"site": at, "reason": "hardware or interrupt boundary"})
202
203
  return Step(successors, False, None, gaps, edges)
203
204
  # In the flat model I/O privilege decides whether a port access faults, so the walk claims nothing after it.
@@ -210,12 +211,14 @@ def cfg_step(image, at, ins, follow_flat_ports=False, step_over_calls=False):
210
211
  return Step(successors, False, return_site, gaps, edges)
211
212
 
212
213
 
213
- def walk(image, entries, limit=10000, follow_flat_ports=False):
214
+ def walk(image, entries, limit=10000, follow_flat_ports=False, follow_interrupts=False, stops=frozenset()):
214
215
  """Decode the CFG reached from ``entries`` and check its instruction boundaries.
215
216
 
216
217
  A port access in the flat model records a gap and ends that branch, as ``trace`` stops there.
217
218
  ``follow_flat_ports`` continues past it instead, for callers that name each port access their
218
- results depend on.
219
+ results depend on. ``follow_interrupts`` continues past an interrupt at the next instruction,
220
+ for callers that list each interrupt as an assumption. A site in ``stops`` is never decoded:
221
+ the walk reaches it and goes no further, so it is in no returned set.
219
222
  """
220
223
  integer(limit, 1, 100000, "instruction limit")
221
224
  pending, seen, gaps, edges = list(entries), {}, [], []
@@ -224,7 +227,7 @@ def walk(image, entries, limit=10000, follow_flat_ports=False):
224
227
  successors, returns, supplied_edges = {}, set(), set()
225
228
  while pending:
226
229
  at = pending.pop()
227
- if at in seen:
230
+ if at in seen or at in stops:
228
231
  continue
229
232
  if len(seen) >= limit:
230
233
  gaps.append({"site": at, "reason": "instruction limit"})
@@ -234,7 +237,7 @@ def walk(image, entries, limit=10000, follow_flat_ports=False):
234
237
  gaps.append({"site": at, "reason": "undecoded or unmapped edge"})
235
238
  continue
236
239
  seen[at] = ins
237
- step = cfg_step(image, at, ins, follow_flat_ports)
240
+ step = cfg_step(image, at, ins, follow_flat_ports, follow_interrupts=follow_interrupts)
238
241
  successors[at] = step.successors
239
242
  gaps.extend(step.gaps)
240
243
  edges.extend(step.edges)
@@ -322,6 +325,12 @@ def walk(image, entries, limit=10000, follow_flat_ports=False):
322
325
  return seen, gaps, edges, undecoded, contested
323
326
 
324
327
 
328
+ def holding_instruction(seen, site):
329
+ """The start of the instruction in ``seen`` whose bytes cover ``site`` past its first byte, or None."""
330
+ # An x86 instruction is at most 15 bytes, so only the starts just before the site can hold it.
331
+ return next((at for at in range(max(site - 14, 0), site) if at in seen and site < at + seen[at].size), None)
332
+
333
+
325
334
  def uncovered(start, end, spans):
326
335
  """The ranges of start..end that no span covers; spans are clipped to the bounds."""
327
336
  missing, cursor = [], start
@@ -0,0 +1,173 @@
1
+ """Synthetic machine code only. No original binaries or analysis artifacts."""
2
+ from pathlib import Path
3
+ import sys
4
+ import unittest
5
+
6
+ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
7
+ from scientific_method_engine.x86.reports import run_report
8
+
9
+ # One resident segment. 0000 calls 000B, then 0018, then a far pointer in memory. 000B dispatches
10
+ # through a two-word table at 0030 (rows 0024 and 0020) under `cmp bx, 1; ja`. 0018 and 0020 both
11
+ # call 0028, which stores a word. The word at 0034 follows the table and is no row of it.
12
+ DISPATCH = bytes.fromhex(
13
+ "e80800" # 0000 call 000B
14
+ "e81200" # 0003 call 0018
15
+ "ff1e0002" # 0006 call far [0200]
16
+ "c3" # 000A ret
17
+ "83fb01" # 000B cmp bx, 1
18
+ "7707" # 000E ja 0017
19
+ "d1e3" # 0010 shl bx, 1
20
+ "2effa73000" # 0012 jmp cs:[bx+0030]
21
+ "c3" # 0017 ret
22
+ "e80d00" # 0018 call 0028
23
+ "c3" # 001B ret
24
+ "90909090" # 001C padding
25
+ "e80500" # 0020 call 0028
26
+ "c3" # 0023 ret
27
+ "c3" # 0024 ret
28
+ "909090" # 0025 padding
29
+ "c70600010100" # 0028 mov word [0100], 1
30
+ "c3" # 002E ret
31
+ "90" # 002F padding
32
+ "24002000" # 0030 table rows 0024, 0020
33
+ "2800" # 0034 a word after the table
34
+ )
35
+ TABLE = {"site": 0x12, "exhaustive": True, "evidence": "synthetic: bx is gated to 0..1 before the jump",
36
+ "table": {"start": 0x30, "count": 2, "stride": 2, "evidence": "synthetic: two rows under cmp bx, 1"}}
37
+
38
+
39
+ def config(data=DISPATCH, entries=(0,), **extra):
40
+ return {"regions": [{"name": "synthetic", "start": 0, "end": len(data), "ip": 0, "segment": 0x1000, "resident": True,
41
+ "entries": list(entries), "evidence": "synthetic declared code extent"}],
42
+ "starts": [0], "targets": [0x28], **extra}
43
+
44
+
45
+ def reach(data=DISPATCH, entries=(0,), **extra):
46
+ return run_report(data, config(data, entries, **extra), "reach")
47
+
48
+
49
+ class ReachTests(unittest.TestCase):
50
+ def test_declared_table_and_direct_calls_both_reach_the_target(self):
51
+ r = reach(indirectJumps=[TABLE], controls=[0x3, 0x20])
52
+ target = r["targets"][0]
53
+ self.assertTrue(target["reached"])
54
+ self.assertEqual(target["calls"], 2)
55
+ self.assertEqual(target["routine"], 0x28)
56
+ # Both chains have two calls; the report gives one and every route passes only the start and 0028.
57
+ self.assertEqual(target["throughEveryRoute"], [0x0])
58
+ self.assertEqual(r["reachedRoutines"], [0x0, 0x0B, 0x18, 0x28])
59
+ self.assertEqual(r["counts"]["routines"], 4)
60
+ # The far call through memory is listed with its operand, never followed.
61
+ self.assertEqual([(u["site"], u["kind"], u["routine"]) for u in r["unresolved"]], [(0x6, "call", 0x0)])
62
+ self.assertIn("[0x200]", r["unresolved"][0]["instruction"])
63
+ self.assertFalse(r["negativeUsable"])
64
+ self.assertEqual(r["controls"], [{"site": 0x3, "target": 0x18}, {"site": 0x20, "target": 0x28}])
65
+
66
+ def test_a_leaf_is_reached_unread_and_its_reason_is_repeated(self):
67
+ reason = "synthetic: returns before any call while its flag holds its start value"
68
+ r = reach(indirectJumps=[TABLE], leaves=[{"routine": 0x18, "reason": reason}])
69
+ target = r["targets"][0]
70
+ self.assertEqual([h.get("callSite") for h in target["chain"]], [None, 0x0, 0x20])
71
+ self.assertEqual([h["routine"] for h in target["chain"]], [0x0, 0x0B, 0x28])
72
+ self.assertEqual(target["route"]["declaredTableJumps"], [{"site": 0x12, "target": 0x20}])
73
+ # Only the table route is left, so 000B is on every route; 0018 is reached but its call is not read.
74
+ self.assertEqual(target["throughEveryRoute"], [0x0, 0x0B])
75
+ self.assertEqual(r["leaves"], [{"routine": 0x18, "reason": reason, "reached": True, "callSites": [0x3]}])
76
+ self.assertNotIn(0x18, [u["site"] for u in r["unresolved"]])
77
+
78
+ def test_an_undeclared_table_jump_is_unresolved_and_no_table_word_is_read(self):
79
+ r = reach(leaves=[{"routine": 0x18, "reason": "synthetic leaf"}])
80
+ target = r["targets"][0]
81
+ self.assertFalse(target["reached"])
82
+ self.assertEqual(target["status"], "not reached")
83
+ self.assertEqual([u["site"] for u in r["unresolved"]], [0x6, 0x12])
84
+ self.assertEqual(r["unresolved"][1]["routine"], 0x0B)
85
+ self.assertNotIn(0x20, r["reachedRoutines"])
86
+ self.assertFalse(r["negativeUsable"])
87
+
88
+ def test_a_leaf_start_inside_a_reached_instruction_is_a_gap(self):
89
+ # 0000 calls 0007, which jumps through a one-row table to 0005, inside the mov at 0003 (the return site).
90
+ data = bytes.fromhex("e80400" "b890c3" "c3" "2effa71000" "90909090" "0500")
91
+ table = {"site": 7, "exhaustive": True, "evidence": "synthetic: one row",
92
+ "table": {"start": 0x10, "count": 1, "stride": 2, "evidence": "synthetic: one row"}}
93
+ r = run_report(data, config(data, targets=[5], controls=[0], indirectJumps=[table],
94
+ leaves=[{"routine": 5, "reason": "synthetic leaf"}]), "reach")
95
+ self.assertIn({"site": 5, "reason": "leaf start inside a reached instruction; the leaf is not decoded, so its "
96
+ "boundary is unchecked", "insideInstruction": 3}, r["gaps"])
97
+ self.assertFalse(r["negativeUsable"])
98
+
99
+ def test_a_negative_is_usable_only_with_controls_and_nothing_unresolved(self):
100
+ # 0000 calls 0004, which returns; nothing reaches 0005.
101
+ data = bytes.fromhex("e80100c3c3c3")
102
+ r = run_report(data, config(data, starts=[0], targets=[5], controls=[0]), "reach")
103
+ self.assertFalse(r["targets"][0]["reached"])
104
+ self.assertTrue(r["negativeUsable"])
105
+ r = run_report(data, config(data, starts=[0], targets=[5]), "reach")
106
+ self.assertFalse(r["negativeUsable"])
107
+
108
+ def test_a_target_inside_a_reached_instruction_is_not_reached(self):
109
+ r = reach(indirectJumps=[TABLE], targets=[0x29])
110
+ self.assertEqual(r["targets"][0]["status"], "inside a reached instruction")
111
+ self.assertEqual(r["targets"][0]["insideInstruction"], 0x28)
112
+
113
+ def test_an_interrupt_is_continued_and_listed_and_the_route_names_it(self):
114
+ # 0000 int 21h; call 0006; ret. 0006 is the target.
115
+ data = bytes.fromhex("cd21e80100c3c3")
116
+ r = run_report(data, config(data, targets=[6]), "reach")
117
+ target = r["targets"][0]
118
+ self.assertTrue(target["reached"])
119
+ self.assertEqual(target["route"]["interruptsContinued"], [0])
120
+ self.assertEqual([(i["site"], i["vector"]) for i in r["interrupts"]], [(0, 0x21)])
121
+
122
+ def test_a_route_past_a_returning_call_names_the_assumed_return(self):
123
+ r = reach(indirectJumps=[TABLE], targets=[0x18])
124
+ self.assertEqual(r["targets"][0]["route"]["assumedReturns"], [0x0])
125
+ self.assertEqual(r["targets"][0]["chain"], [{"routine": 0x0}, {"callSite": 0x3, "routine": 0x18}])
126
+
127
+ def test_an_unrelocated_far_call_is_unresolved(self):
128
+ data = bytes.fromhex("9a00000010c3")
129
+ r = run_report(data, config(data, targets=[5]), "reach")
130
+ self.assertEqual(r["unresolved"][0]["reason"], "no declared relocation/fixup")
131
+
132
+ def test_an_unsupported_return_is_unresolved_as_a_return(self):
133
+ # 0000 calls 0004, an o32 ret: an operand-size override the frame model does not cover.
134
+ data = bytes.fromhex("e80100c366c3")
135
+ r = run_report(data, config(data, targets=[3], controls=[0]), "reach")
136
+ self.assertEqual([(u["site"], u["kind"], u["routine"]) for u in r["unresolved"]], [(4, "return", 4)])
137
+ self.assertEqual(r["gaps"], [])
138
+ self.assertFalse(r["negativeUsable"])
139
+
140
+ def test_an_undecodable_edge_is_a_gap(self):
141
+ data = bytes.fromhex("e80100c30f")
142
+ r = run_report(data, config(data, targets=[3]), "reach")
143
+ self.assertEqual(r["gaps"], [{"site": 4, "reason": "undecoded or unmapped edge"}])
144
+ self.assertFalse(r["negativeUsable"])
145
+
146
+ def test_the_instruction_limit_is_a_gap(self):
147
+ r = reach(indirectJumps=[TABLE], instructionLimit=3)
148
+ self.assertIn("instruction limit", [g["reason"] for g in r["gaps"]])
149
+ self.assertFalse(r["negativeUsable"])
150
+
151
+ def test_the_result_limit_truncates_lists_and_keeps_counts(self):
152
+ data = bytes.fromhex("ffd0ffd3c3") # call ax; call bx; ret
153
+ r = run_report(data, config(data, targets=[4], limit=1), "reach")
154
+ self.assertEqual(len(r["unresolved"]), 1)
155
+ self.assertEqual(r["counts"]["unresolved"], 2)
156
+ self.assertTrue(r["truncated"])
157
+
158
+ def test_rejected_inputs(self):
159
+ for extra, message in [({"starts": [0x18]}, "established region entry"),
160
+ ({"starts": []}, "starts must be"),
161
+ ({"targets": [0x1000]}, "targets"),
162
+ ({"leaves": [{"routine": 0x18}]}, "routine and reason"),
163
+ ({"leaves": [{"routine": 0x18, "reason": " "}]}, "nonempty reason"),
164
+ ({"leaves": [{"routine": 0, "reason": "x"}]}, "start cannot be a leaf"),
165
+ ({"controls": [0x3, 0x3]}, "distinct file offsets"),
166
+ ({"controls": [0x6]}, "Positive control 6 missed"),
167
+ ({"controls": [0x10]}, "Positive control 16 missed")]:
168
+ with self.subTest(extra=extra), self.assertRaisesRegex(ValueError, message):
169
+ reach(**extra)
170
+
171
+
172
+ if __name__ == "__main__":
173
+ unittest.main()