scientific-method-engine 18.0.0__tar.gz → 18.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 (86) hide show
  1. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/cli.py +3 -1
  4. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/reach.py +64 -20
  5. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/trace.py +3 -1
  6. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_reach.py +74 -2
  7. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/.gitignore +0 -0
  8. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/LICENSE +0 -0
  9. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/README.md +0 -0
  10. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/__init__.py +0 -0
  11. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/__main__.py +0 -0
  12. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  13. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  14. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  15. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  16. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  17. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  18. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  19. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  20. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  21. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  22. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  23. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  24. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  25. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  26. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  27. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  28. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  29. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  30. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  31. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  32. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  33. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  34. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  35. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  36. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  37. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  38. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportRangeBoundaries.java +0 -0
  39. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  40. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  41. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  42. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  43. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  44. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  45. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +0 -0
  46. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/ghidra/scientificmethod/Xxh3.java +0 -0
  47. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  48. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  49. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  50. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  51. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/image.py +0 -0
  52. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/inventory.py +0 -0
  53. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/loops.py +0 -0
  54. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/machine.py +0 -0
  55. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  56. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  57. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  58. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
  59. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/relational.py +0 -0
  60. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/reports.py +0 -0
  61. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  62. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/src/scientific_method_engine/x86/values.py +0 -0
  63. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/oracle.py +0 -0
  64. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_config_encoding.py +0 -0
  65. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_continuation_budget.py +0 -0
  66. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_dispatch.py +0 -0
  67. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_effect_order.py +0 -0
  68. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_enter_frames.py +0 -0
  69. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_entry_frame.py +0 -0
  70. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_indirect_far_transfers.py +0 -0
  71. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_interrupt_models.py +0 -0
  72. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_inventory_check.py +0 -0
  73. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_join_terms.py +0 -0
  74. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_loops.py +0 -0
  75. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_memory_scopes.py +0 -0
  76. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_nested_frame_request.py +0 -0
  77. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_oracle.py +0 -0
  78. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_pe.py +0 -0
  79. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_relational_controls.py +0 -0
  80. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_return_checks.py +0 -0
  81. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_successor_rule.py +0 -0
  82. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_table_continuations.py +0 -0
  83. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_term_limit.py +0 -0
  84. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_upstream_gaps.py +0 -0
  85. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_volatile_memory.py +0 -0
  86. {scientific_method_engine-18.0.0 → scientific_method_engine-18.1.0}/tests/test_x86.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 18.0.0
3
+ Version: 18.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
@@ -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 = "18.0.0"
8
+ version = "18.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"
@@ -23,7 +23,9 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
23
23
  "or continues at another address than the next instruction (ghidraFallsThroughElsewhere).\n"
24
24
  "reach lists the target sites the starts reach over resolved calls and jumps, with the fewest-call chain\n"
25
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"
26
+ "a leaves routine is reached but not read, and its reason is repeated in the report;\n"
27
+ "controls are call sites the walk must reach and resolve, instructionControls sites it must decode,\n"
28
+ "and a failed control fails the report saying whether it was reached.\n"
27
29
  "inventory-check places every resolved direct call target in the notation of the function inventory TSV\n"
28
30
  "that inventory names and lists each target no row starts at: inside another row's body or outside every row,\n"
29
31
  "with one calling site, near or far, and whether an entry-path call, a contested one or only raw bytes call it;\n"
@@ -1,7 +1,8 @@
1
1
  """Transitive reachability from established starts to target sites over the entry-path CFG."""
2
2
  from collections import deque
3
3
  from .image import integer
4
- from .trace import walk, cfg_step, base_mnemonic, unsupported_transfer, holding_instruction, INTERRUPTS, RETURNS, LIMIT_REASON
4
+ from .trace import (walk, cfg_step, base_mnemonic, unsupported_transfer, holding_instruction, INTERRUPTS, RETURNS,
5
+ LIMIT_REASON, OVERLAP_REASON, UNDECODED_REASON)
5
6
  from .pcode_backend import interrupt_vector
6
7
 
7
8
  # The virtual root of the dominator computation; no file offset is negative.
@@ -11,9 +12,13 @@ UNSUPPORTED = "unsupported control-transfer frame encoding"
11
12
  LEAF_OVERLAP = "leaf start inside a reached instruction; the leaf is not decoded, so its boundary is unchecked"
12
13
 
13
14
 
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")
15
+ def _text(ins):
16
+ return (ins.mnemonic + " " + ins.op_str).strip()
17
+
18
+
19
+ def _sites(value, label, image, limit=256, least=1):
20
+ if not isinstance(value, list) or not least <= len(value) <= limit or len(set(map(repr, value))) != len(value):
21
+ raise ValueError(f"{label} must be a list of {least}..{limit} distinct file offsets")
17
22
  for at in value:
18
23
  integer(at, 0, len(image.data) - 1, label)
19
24
  if image.region(at) is None:
@@ -106,10 +111,20 @@ def reach(image, config):
106
111
  raise ValueError(f"Reach start {at} must be an established region entry")
107
112
  targets = _sites(config.get("targets"), "targets", image)
108
113
  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")
114
+ controls = _sites(config.get("controls", []), "controls", image, least=0)
115
+ instruction_controls = _sites(config.get("instructionControls", []), "instructionControls", image, least=0)
116
+ # The walk decodes a site as image.decode does, so a control whose bytes are no call can never pass.
117
+ for at in controls:
118
+ ins = image.decode(at)
119
+ if ins is None or base_mnemonic(ins) not in CALLS:
120
+ decoded = f"decodes as {_text(ins)}" if ins is not None else "does not decode"
121
+ raise ValueError(f"control {at} is not a call site ({decoded}); controls are call sites the walk must "
122
+ "reach and resolve, and instructionControls are sites the walk must decode")
123
+ # The walk decodes every start it is given, so a start as an instruction control would pass whatever the walk misses.
124
+ for at in instruction_controls:
125
+ if at in starts:
126
+ raise ValueError(f"instruction control {at} is a start; the walk decodes every start, so it shows nothing "
127
+ "the walk found")
113
128
  limit = integer(config.get("limit", 1000), 1, 10000, "result limit")
114
129
  instruction_limit = config.get("instructionLimit", 10000)
115
130
  seen, walk_gaps, _, _, contested = walk(image, starts, instruction_limit, follow_interrupts=True, stops=frozenset(leaves))
@@ -119,7 +134,7 @@ def reach(image, config):
119
134
  step = cfg_step(image, at, ins, follow_interrupts=True)
120
135
  graph[at] = [(s, kind) for s, kind in _kinds(at, ins, step) if s in seen or s in leaves]
121
136
  m = base_mnemonic(ins)
122
- text = (ins.mnemonic + " " + ins.op_str).strip()
137
+ text = _text(ins)
123
138
  kind = "call" if m in CALLS else "return" if m in RETURNS else "jump"
124
139
  if unsupported_transfer(image, ins):
125
140
  unresolved.append({"site": at, "instruction": text, "kind": kind, "reason": UNSUPPORTED})
@@ -191,6 +206,19 @@ def reach(image, config):
191
206
  "route": {"assumedReturns": assumed_returns[::-1], "declaredTableJumps": tables[::-1],
192
207
  "interruptsContinued": continued[::-1]}}
193
208
 
209
+ # The walk decodes both instructions of an unresolved overlap and keeps neither, so their starts are not in seen.
210
+ overlapping = {g["site"] for g in walk_gaps if g["reason"] == OVERLAP_REASON}
211
+ # A site an edge leads to whose bytes do not decode is reached, though no instruction starts there.
212
+ undecodable = {g["site"] for g in walk_gaps if g["reason"] == UNDECODED_REASON}
213
+
214
+ def unreached(site):
215
+ holder = holding_instruction(seen, site)
216
+ if holder is not None:
217
+ return {"status": "inside a reached instruction", "insideInstruction": holder}
218
+ return {"status": "start of a contested instruction" if site in contested
219
+ else "start of an unresolved overlapping instruction" if site in overlapping
220
+ else "reached but not decodable" if site in undecodable else "not reached"}
221
+
194
222
  rows = []
195
223
  for target in targets:
196
224
  row = {"target": target}
@@ -203,10 +231,7 @@ def reach(image, config):
203
231
  row |= {"reached": True, "routine": routine[target], "leaf": target in leaves, **chain(target),
204
232
  "throughEveryRoute": cut[::-1]}
205
233
  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 {})}
234
+ row |= {"reached": False, **unreached(target)}
210
235
  rows.append(row)
211
236
 
212
237
  for row in unresolved + interrupts:
@@ -216,16 +241,33 @@ def reach(image, config):
216
241
  # The walk never decodes a leaf, so its overlap check cannot see a leaf start inside a decoded instruction.
217
242
  gaps += [{"site": at, "reason": LEAF_OVERLAP, "insideInstruction": holding_instruction(seen, at)}
218
243
  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")
244
+ # Kept apart from the gap rows, which the result limit can cut.
245
+ stopped = any(g["reason"] == LIMIT_REASON for g in walk_gaps)
246
+ # Not reached and reached-but-unresolved need different fixes, so each failure says which it is.
247
+ failures = []
248
+ for label, sites, passed in (("control", controls, resolved_calls), ("instruction control", instruction_controls, seen)):
249
+ for at in sites:
250
+ if at in passed:
251
+ continue
252
+ # Only a call-site control can be decoded and still fail.
253
+ if at in seen:
254
+ reasons = sorted({row["reason"] for row in unresolved if row["site"] == at})
255
+ failures.append(f"{label} {at} is reached but its call target is unresolved ({'; '.join(reasons)})")
256
+ elif at in leaves and at in distance:
257
+ failures.append(f"{label} {at} is the start of a leaf, which the walk reaches but does not decode")
258
+ else:
259
+ state = unreached(at)
260
+ detail = (f"inside the reached instruction at {state['insideInstruction']}" if "insideInstruction" in state
261
+ else "the " + state["status"] if state["status"].startswith("start") else state["status"])
262
+ failures.append(f"{label} {at} is {detail}"
263
+ + (" (the walk stopped at its instruction limit)" if stopped else ""))
264
+ if failures:
265
+ raise ValueError("Positive controls failed: " + "; ".join(failures))
222
266
  call_sites = {}
223
267
  for site, target in sorted(resolved_calls.items()):
224
268
  call_sites.setdefault(target, []).append(site)
225
269
  leaf_rows = [{"routine": at, "reason": reason, "reached": at in distance, "callSites": call_sites.get(at, [])}
226
270
  for at, reason in leaves.items()]
227
- # Kept apart from the gap rows, which the result limit can cut.
228
- stopped = any(g["reason"] == LIMIT_REASON for g in walk_gaps)
229
271
  counts = {"routines": len(routine_starts), "instructions": len(seen), "unresolved": len(unresolved),
230
272
  "interrupts": len(interrupts), "gaps": len(gaps), "contested": len(contested)}
231
273
  return {"starts": starts, "targets": rows, "leaves": leaf_rows,
@@ -235,7 +277,9 @@ def reach(image, config):
235
277
  "truncated": any(len(x) > limit for x in (unresolved, interrupts, gaps, contested)),
236
278
  "instructionLimitReached": stopped,
237
279
  "controls": [{"site": at, "target": resolved_calls[at]} for at in controls],
238
- "negativeUsable": bool(controls) and not (stopped or unresolved or gaps or contested),
280
+ "instructionControls": [{"site": at, "instruction": _text(seen[at]), "routine": routine.get(at)}
281
+ for at in instruction_controls],
282
+ "negativeUsable": bool(controls or instruction_controls) and not (stopped or unresolved or gaps or contested),
239
283
  "assumptions": ["each reached call returns to its next instruction",
240
284
  "each reached interrupt returns to its next instruction; interrupt handlers are not read",
241
285
  "each leaf calls nothing, for the reason it gives",
@@ -245,7 +289,7 @@ def reach(image, config):
245
289
  "interpretation": "Routes over the decoded entry-path CFG from the starts. A chain has the fewest calls; "
246
290
  "throughEveryRoute lists the routine starts every read route to the target passes, "
247
291
  "and an unresolved transfer may add a route that passes none of them. "
248
- "negativeUsable needs controls, a walk that did not stop at its instruction limit, "
292
+ "negativeUsable needs a control of either kind, a walk that did not stop at its instruction limit, "
249
293
  "and no unresolved transfer, gap or contested instruction, "
250
294
  "and still rests on the listed assumptions and leaves. "
251
295
  "When instructionLimitReached holds, the walk stopped before reading all it reaches: "
@@ -88,6 +88,8 @@ def far_pointer_transfer(state, image):
88
88
  # The gap reason walk() records when it stops at its instruction limit with code left to read.
89
89
  LIMIT_REASON = "instruction limit"
90
90
  OVERLAP_REASON = "overlapping entry-path instructions; boundary unresolved"
91
+ # The gap reason walk() records at a site it reaches but cannot decode.
92
+ UNDECODED_REASON = "undecoded or unmapped edge"
91
93
  RETURNS = {"ret": "near return", "retf": "far return", "iret": "interrupt return", "iretd": "interrupt return"}
92
94
  INTERRUPTS = ("int", "int1", "int3", "into")
93
95
  PORTS = ("in", "out", "insb", "insw", "insd", "outsb", "outsw", "outsd")
@@ -259,7 +261,7 @@ def walk(image, entries, limit=10000, follow_flat_ports=False, follow_interrupts
259
261
  break
260
262
  ins = image.decode(at)
261
263
  if ins is None:
262
- gaps.append({"site": at, "reason": "undecoded or unmapped edge"})
264
+ gaps.append({"site": at, "reason": UNDECODED_REASON})
263
265
  continue
264
266
  seen[at] = ins
265
267
  step = cfg_step(image, at, ins, follow_flat_ports, follow_interrupts=follow_interrupts,
@@ -172,7 +172,75 @@ class ReachTests(unittest.TestCase):
172
172
  self.assertEqual(r["counts"]["unresolved"], 2)
173
173
  self.assertTrue(r["truncated"])
174
174
 
175
+ def test_a_control_that_is_no_call_is_refused_before_the_walk_and_an_instruction_control_takes_it(self):
176
+ # 0000 calls 0004, which stores AX at [0100] and returns.
177
+ data = bytes.fromhex("e80100c3" "a30001" "c3")
178
+ with self.assertRaisesRegex(ValueError, r"control 4 is not a call site \(decodes as mov .*\); controls are "
179
+ r"call sites the walk must reach and resolve"):
180
+ run_report(data, config(data, targets=[7], controls=[4]), "reach")
181
+ r = run_report(data, config(data, targets=[7], instructionControls=[4]), "reach")
182
+ self.assertEqual(r["instructionControls"], [{"site": 4, "instruction": "mov word ptr [0x100], ax", "routine": 4}])
183
+ self.assertEqual(r["controls"], [])
184
+ self.assertTrue(r["negativeUsable"])
185
+ # The call that enters the store's routine passes as a call-site control.
186
+ r = run_report(data, config(data, targets=[7], controls=[0]), "reach")
187
+ self.assertEqual(r["controls"], [{"site": 0, "target": 4}])
188
+ self.assertEqual(r["instructionControls"], [])
189
+
190
+ def test_a_control_that_does_not_decode_is_refused_before_the_walk(self):
191
+ data = bytes.fromhex("e80100c3" "0f")
192
+ with self.assertRaisesRegex(ValueError, r"control 4 is not a call site \(does not decode\)"):
193
+ run_report(data, config(data, targets=[3], controls=[4]), "reach")
194
+
195
+ def test_a_site_the_walk_reaches_but_cannot_decode_is_not_called_unreached(self):
196
+ # 0000 calls 0004, whose single byte does not decode.
197
+ data = bytes.fromhex("e80100c3" "0f")
198
+ r = run_report(data, config(data, targets=[4]), "reach")
199
+ self.assertEqual(r["targets"][0]["status"], "reached but not decodable")
200
+ with self.assertRaisesRegex(ValueError, r"Positive controls failed: instruction control 4 is reached but not "
201
+ r"decodable$"):
202
+ run_report(data, config(data, targets=[3], instructionControls=[4]), "reach")
203
+
204
+ def test_each_failed_control_says_whether_it_was_reached(self):
205
+ LEAF = {"routine": 0x18, "reason": "synthetic leaf"}
206
+ cases = [({"controls": [0x6]}, "control 6 is reached but its call target is unresolved "
207
+ r"\(computed transfer remains unresolved\)"),
208
+ # Without the table declaration the walk never arrives at 0020.
209
+ ({"controls": [0x20]}, r"control 32 is not reached$"),
210
+ # With 0018 a leaf and no table, nothing reaches 0028.
211
+ ({"instructionControls": [0x28], "leaves": [LEAF]}, r"instruction control 40 is not reached$"),
212
+ ({"indirectJumps": [TABLE], "instructionControls": [0x29]},
213
+ "instruction control 41 is inside the reached instruction at 40"),
214
+ ({"indirectJumps": [TABLE], "instructionControls": [0x18], "leaves": [LEAF]},
215
+ "instruction control 24 is the start of a leaf, which the walk reaches but does not decode"),
216
+ ({"indirectJumps": [TABLE], "instructionLimit": 3, "instructionControls": [0x28]},
217
+ r"instruction control 40 is not reached \(the walk stopped at its instruction limit\)")]
218
+ for extra, message in cases:
219
+ with self.subTest(extra=extra), self.assertRaisesRegex(ValueError, "Positive controls failed: " + message):
220
+ reach(**extra)
221
+ # No table declaration means nothing reaches 0020, so the leaf there is not reached either.
222
+ with self.assertRaisesRegex(ValueError, r"Positive controls failed: control 32 is not reached$"):
223
+ reach(controls=[0x20], leaves=[{"routine": 0x20, "reason": "synthetic leaf"}])
224
+ # Every failed control is named at once, in both lists.
225
+ with self.assertRaisesRegex(ValueError, "control 6 is reached but .*; control 32 is not reached; "
226
+ "instruction control 40 is not reached"):
227
+ reach(controls=[0x3, 0x6, 0x20], instructionControls=[0x3, 0x28], leaves=[LEAF])
228
+
229
+ def test_the_starts_of_an_unresolved_overlap_are_decoded_and_not_called_unreached(self):
230
+ # 0000 calls 0007, which jumps through a one-row table to 0005, inside the mov at 0003 (the return site).
231
+ # Neither boundary is proven, so the walk keeps neither instruction.
232
+ data = bytes.fromhex("e80400" "b890c3" "c3" "2effa71000" "90909090" "0500")
233
+ table = {"site": 7, "exhaustive": True, "evidence": "synthetic: one row",
234
+ "table": {"start": 0x10, "count": 1, "stride": 2, "evidence": "synthetic: one row"}}
235
+ r = run_report(data, config(data, targets=[3, 5], indirectJumps=[table]), "reach")
236
+ self.assertEqual([t["status"] for t in r["targets"]], ["start of an unresolved overlapping instruction"] * 2)
237
+ with self.assertRaisesRegex(ValueError, "Positive controls failed: instruction control 3 is the start of an "
238
+ "unresolved overlapping instruction; instruction control 5 is the "
239
+ "start of an unresolved overlapping instruction$"):
240
+ run_report(data, config(data, targets=[6], indirectJumps=[table], instructionControls=[3, 5]), "reach")
241
+
175
242
  def test_rejected_inputs(self):
243
+ too_many = list(range(257))
176
244
  for extra, message in [({"starts": [0x18]}, "established region entry"),
177
245
  ({"starts": []}, "starts must be"),
178
246
  ({"targets": [0x1000]}, "targets"),
@@ -180,8 +248,12 @@ class ReachTests(unittest.TestCase):
180
248
  ({"leaves": [{"routine": 0x18, "reason": " "}]}, "nonempty reason"),
181
249
  ({"leaves": [{"routine": 0, "reason": "x"}]}, "start cannot be a leaf"),
182
250
  ({"controls": [0x3, 0x3]}, "distinct file offsets"),
183
- ({"controls": [0x6]}, "Positive control 6 missed"),
184
- ({"controls": [0x10]}, "Positive control 16 missed")]:
251
+ ({"controls": [0x1000]}, "controls must be an integer"),
252
+ ({"instructionControls": [0x3, 0x3]}, "distinct file offsets"),
253
+ ({"instructionControls": [0x1000]}, "instructionControls must be an integer"),
254
+ ({"instructionControls": [0x0]}, "instruction control 0 is a start"),
255
+ ({"controls": too_many}, r"controls must be a list of 0\.\.256"),
256
+ ({"instructionControls": too_many}, r"instructionControls must be a list of 0\.\.256")]:
185
257
  with self.subTest(extra=extra), self.assertRaisesRegex(ValueError, message):
186
258
  reach(**extra)
187
259