scientific-method-engine 19.4.0__tar.gz → 19.5.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 (92) hide show
  1. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/cli.py +5 -2
  4. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/reach.py +157 -25
  5. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_reach.py +123 -0
  6. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/.gitignore +0 -0
  7. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/LICENSE +0 -0
  8. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/README.md +0 -0
  9. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/__init__.py +0 -0
  10. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/__main__.py +0 -0
  11. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  12. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  13. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  14. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  15. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  16. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  17. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  18. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  19. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  20. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  21. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  22. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  23. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  24. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  25. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  26. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  27. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  28. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  29. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  30. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  31. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  32. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  33. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  34. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  35. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  36. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  37. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportRangeBoundaries.java +0 -0
  38. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  39. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  40. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  41. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  42. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  43. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  44. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +0 -0
  45. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/ghidra/scientificmethod/Xxh3.java +0 -0
  46. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  47. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  48. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/derived_counts.py +0 -0
  49. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  50. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  51. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/image.py +0 -0
  52. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/inventory.py +0 -0
  53. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/loops.py +0 -0
  54. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/machine.py +0 -0
  55. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  56. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  57. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  58. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/pe.py +0 -0
  59. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/ranges.py +0 -0
  60. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/relational.py +0 -0
  61. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/reports.py +0 -0
  62. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  63. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/table_bounds.py +0 -0
  64. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/trace.py +0 -0
  65. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/src/scientific_method_engine/x86/values.py +0 -0
  66. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/oracle.py +0 -0
  67. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_config_encoding.py +0 -0
  68. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_continuation_budget.py +0 -0
  69. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_derived_counts.py +0 -0
  70. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_dispatch.py +0 -0
  71. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_effect_order.py +0 -0
  72. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_enter_frames.py +0 -0
  73. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_entry_frame.py +0 -0
  74. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_indirect_far_transfers.py +0 -0
  75. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_interrupt_models.py +0 -0
  76. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_inventory_check.py +0 -0
  77. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_join_terms.py +0 -0
  78. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_loops.py +0 -0
  79. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_memory_scopes.py +0 -0
  80. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_nested_frame_request.py +0 -0
  81. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_oracle.py +0 -0
  82. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_pe.py +0 -0
  83. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_ranges.py +0 -0
  84. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_relational_controls.py +0 -0
  85. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_return_checks.py +0 -0
  86. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_successor_rule.py +0 -0
  87. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_table_bounds.py +0 -0
  88. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_table_continuations.py +0 -0
  89. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_term_limit.py +0 -0
  90. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_upstream_gaps.py +0 -0
  91. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.0}/tests/test_volatile_memory.py +0 -0
  92. {scientific_method_engine-19.4.0 → scientific_method_engine-19.5.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: 19.4.0
3
+ Version: 19.5.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 = "19.4.0"
8
+ version = "19.5.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"
@@ -22,7 +22,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
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
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"
25
+ "and the routines every read route passes, and the starts each target is reached from (reachedFrom),\n"
26
+ "and lists every reached transfer it could not resolve;\n"
26
27
  "a leaves routine is reached but not read, and its reason is repeated in the report;\n"
27
28
  "a call to a noReturn routine, a noReturn call and a noReturn interrupt do not continue at the next\n"
28
29
  "instruction, a noReturn routine with a return, or a jump into a returning leaf, on its own read paths\n"
@@ -39,7 +40,9 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
39
40
  "the proven one is refused, and a walk edge that enters the routine other than at its start is a gap;\n"
40
41
  "controls are call sites the walk must reach and resolve, instructionControls sites it must decode,\n"
41
42
  "and a failed control fails the report saying whether it was reached;\n"
42
- "decodedRanges true lists every instruction the walk decoded as half-open ranges with their routine.\n"
43
+ "decodedRanges true lists every instruction the walk decoded as half-open ranges with their routine;\n"
44
+ "startRoutes true gives each reached target, for each start it is reached from, the fewest calls and the\n"
45
+ "routines every read route from that start passes.\n"
43
46
  "inventory-check places every resolved direct call target in the notation of the function inventory TSV\n"
44
47
  "that inventory names and lists each target no row starts at: inside another row's body or outside every row,\n"
45
48
  "with one calling site, near or far, and whether an entry-path call, a contested one or only raw bytes call it;\n"
@@ -312,6 +312,136 @@ def _dominators(order, predecessors):
312
312
  return idom
313
313
 
314
314
 
315
+ def route_dominators(graph, starts, reached):
316
+ """Immediate dominators of every site in ``reached`` over ``graph``, from a virtual ROOT that leads to every start.
317
+
318
+ ``graph`` maps a site to its ``successor_kinds`` rows and ``reached`` holds the sites ``graph``
319
+ reaches from ``starts``.
320
+ """
321
+ successors = {ROOT: list(starts)} | {at: [s for s, _ in graph.get(at, [])] for at in reached}
322
+ order, visited, stack = [], {ROOT}, [(ROOT, iter(successors[ROOT]))]
323
+ while stack:
324
+ node, children = stack[-1]
325
+ child = next(children, None)
326
+ if child is None:
327
+ order.append(node)
328
+ stack.pop()
329
+ elif child not in visited:
330
+ visited.add(child)
331
+ stack.append((child, iter(successors[child])))
332
+ order.reverse()
333
+ predecessors = {node: [] for node in order}
334
+ for node in order:
335
+ for child in successors[node]:
336
+ predecessors[child].append(node)
337
+ return _dominators(order, predecessors)
338
+
339
+
340
+ def through_every_route(idom, routine_starts, target):
341
+ """The routine starts, outermost first, that dominate ``target`` under ``idom``, the target itself excluded."""
342
+ cut, at = [], idom[target]
343
+ while at != ROOT:
344
+ if at in routine_starts:
345
+ cut.append(at)
346
+ at = idom[at]
347
+ return cut[::-1]
348
+
349
+
350
+ def reaching_starts(graph, starts, reached, targets):
351
+ """Each of ``targets`` mapped to the ``starts``, in their order, from which ``graph`` reaches it.
352
+
353
+ ``reached`` holds every site ``graph`` reaches from ``starts``, and each target is one of them.
354
+ The sets come from one pass over the strongly connected components, so the cost does not grow
355
+ with the number of starts the way a walk from each start would.
356
+ """
357
+ def successors(at):
358
+ return [s for s, _ in graph.get(at, [])]
359
+ # Tarjan's components, without recursion; a component is completed only after every component it leads to.
360
+ index, low, on_stack, stack, components = {}, {}, set(), [], []
361
+ for root in reached:
362
+ if root in index:
363
+ continue
364
+ index[root] = low[root] = len(index)
365
+ stack.append(root)
366
+ on_stack.add(root)
367
+ work = [(root, iter(successors(root)))]
368
+ while work:
369
+ node, children = work[-1]
370
+ child = next(children, None)
371
+ if child is not None:
372
+ if child not in index:
373
+ index[child] = low[child] = len(index)
374
+ stack.append(child)
375
+ on_stack.add(child)
376
+ work.append((child, iter(successors(child))))
377
+ elif child in on_stack:
378
+ low[node] = min(low[node], index[child])
379
+ continue
380
+ work.pop()
381
+ if work:
382
+ low[work[-1][0]] = min(low[work[-1][0]], low[node])
383
+ if low[node] == index[node]:
384
+ component = []
385
+ while True:
386
+ at = stack.pop()
387
+ on_stack.discard(at)
388
+ component.append(at)
389
+ if at == node:
390
+ break
391
+ components.append(component)
392
+ component_of = {at: i for i, component in enumerate(components) for at in component}
393
+ # One bit per start; a component passes its bits on to the components it leads to, which come earlier.
394
+ masks = [0] * len(components)
395
+ for bit, start in enumerate(starts):
396
+ masks[component_of[start]] |= 1 << bit
397
+ for i in range(len(components) - 1, -1, -1):
398
+ for at in components[i]:
399
+ for successor in successors(at):
400
+ if component_of[successor] != i:
401
+ masks[component_of[successor]] |= masks[i]
402
+ return {target: [start for bit, start in enumerate(starts) if masks[component_of[target]] >> bit & 1]
403
+ for target in targets}
404
+
405
+
406
+ def start_routes(graph, starts, from_starts, called):
407
+ """For each target in ``from_starts``, a row per start that ``reaching_starts`` gives it, in ``starts`` order.
408
+
409
+ A row gives the ``start``, the fewest ``calls`` on a route from it and the routine starts every
410
+ route from it passes (``throughEveryRoute``), over the routes ``graph`` holds. A row's routine
411
+ starts are its own start and the call targets in ``called``, as a walk from that start alone
412
+ counts them, so another start that the routes enter only by a jump is not listed. Each start
413
+ that reaches a target costs one walk over its part of ``graph``.
414
+ """
415
+ found = {target: [] for target in from_starts}
416
+ # Every route to a target runs through sites that lead to one, so the rest of the graph changes neither
417
+ # the fewest calls nor what every route passes.
418
+ predecessors = {}
419
+ for at, rows in graph.items():
420
+ for successor, _ in rows:
421
+ predecessors.setdefault(successor, []).append(at)
422
+ leading, stack = set(from_starts), list(from_starts)
423
+ while stack:
424
+ for at in predecessors.get(stack.pop(), []):
425
+ if at not in leading:
426
+ leading.add(at)
427
+ stack.append(at)
428
+ graph = {at: [row for row in graph.get(at, []) if row[0] in leading] for at in leading}
429
+ targets_of = {}
430
+ for target, found_starts in from_starts.items():
431
+ for start in found_starts:
432
+ targets_of.setdefault(start, []).append(target)
433
+ for start in starts:
434
+ if start not in targets_of:
435
+ continue
436
+ distance, _, _ = fewest_calls(graph, [start])
437
+ idom = route_dominators(graph, [start], distance)
438
+ routine_starts = called | {start}
439
+ for target in targets_of[start]:
440
+ found[target].append({"start": start, "calls": distance[target],
441
+ "throughEveryRoute": through_every_route(idom, routine_starts, target)})
442
+ return found
443
+
444
+
315
445
  def reach(image, config):
316
446
  """Which target sites the starts reach over resolved calls and jumps, by which chain, and what the walk could not read.
317
447
 
@@ -326,7 +456,9 @@ def reach(image, config):
326
456
  ``stops`` site is decoded and nothing after it is followed. A stop narrows the query and claims
327
457
  nothing about the build, so it is neither checked nor listed among the assumptions.
328
458
  Each reached target gets one chain with the fewest calls, the assumptions its route rests on,
329
- and the routines on every route to it within the read graph. With ``decodedRanges`` the report
459
+ the routines on every route to it within the read graph, and the starts it is reached from. With
460
+ ``startRoutes`` each reached target also gives, for each of those starts, the fewest calls from it
461
+ and the routines on every route from it. With ``decodedRanges`` the report
330
462
  also gives every instruction the walk decoded, as ``decoded_ranges`` groups them.
331
463
  """
332
464
  from .reports import entries
@@ -361,6 +493,9 @@ def reach(image, config):
361
493
  with_ranges = config.get("decodedRanges", False)
362
494
  if not isinstance(with_ranges, bool):
363
495
  raise ValueError("decodedRanges must be a boolean")
496
+ with_start_routes = config.get("startRoutes", False)
497
+ if not isinstance(with_start_routes, bool):
498
+ raise ValueError("startRoutes must be a boolean")
364
499
  instruction_limit = config.get("instructionLimit", 10000)
365
500
  no_return_routines, no_return_interrupts, no_return_sites, declared = no_return_inputs(
366
501
  config.get("noReturn", []), image, indirect_calls)
@@ -405,24 +540,10 @@ def reach(image, config):
405
540
  distance, parent, routine = fewest_calls(graph, starts)
406
541
 
407
542
  # Dominators over everything reached, from a virtual root that leads to every start.
408
- successors = {ROOT: list(starts)} | {at: [s for s, _ in graph.get(at, [])] for at in distance}
409
- order, visited, stack = [], {ROOT}, [(ROOT, iter(successors[ROOT]))]
410
- while stack:
411
- node, children = stack[-1]
412
- child = next(children, None)
413
- if child is None:
414
- order.append(node)
415
- stack.pop()
416
- elif child not in visited:
417
- visited.add(child)
418
- stack.append((child, iter(successors[child])))
419
- order.reverse()
420
- predecessors = {node: [] for node in order}
421
- for node in order:
422
- for child in successors[node]:
423
- predecessors[child].append(node)
424
- idom = _dominators(order, predecessors)
425
- routine_starts = set(starts) | {target for found in call_targets.values() for target in found if target in distance}
543
+ idom = route_dominators(graph, starts, distance)
544
+ called = {target for found in call_targets.values() for target in found if target in distance}
545
+ routine_starts = set(starts) | called
546
+ from_starts = reaching_starts(graph, starts, distance, [target for target in targets if target in distance])
426
547
 
427
548
  def chain(target):
428
549
  hops, assumed_returns, tables, declared_calls, continued = [], [], [], [], []
@@ -462,14 +583,10 @@ def reach(image, config):
462
583
  for target in targets:
463
584
  row = {"target": target}
464
585
  if target in distance:
465
- cut, at = [], idom[target]
466
- while at != ROOT:
467
- if at in routine_starts:
468
- cut.append(at)
469
- at = idom[at]
470
586
  row |= {"reached": True, "routine": routine[target], "leaf": target in leaves,
471
587
  "stop": target in stop_routines or target in stop_sites, **chain(target),
472
- "throughEveryRoute": cut[::-1]}
588
+ "throughEveryRoute": through_every_route(idom, routine_starts, target),
589
+ "reachedFrom": from_starts[target]}
473
590
  else:
474
591
  row |= {"reached": False, **unreached(target)}
475
592
  rows.append(row)
@@ -533,6 +650,16 @@ def reach(image, config):
533
650
  + (" (the walk stopped at its instruction limit)" if stopped else ""))
534
651
  if failures:
535
652
  raise ValueError("Positive controls failed: " + "; ".join(failures))
653
+ # Computed only once the controls pass, since each start costs a walk of its own.
654
+ if with_start_routes:
655
+ reached_rows = [row for row in rows if row["reached"]]
656
+ # With one start, its routes are all the routes, so the row's own fields serve.
657
+ by_start = (start_routes(graph, starts, from_starts, called) if len(starts) > 1
658
+ else {row["target"]: [{"start": starts[0], "calls": row["calls"],
659
+ "throughEveryRoute": list(row["throughEveryRoute"])}]
660
+ for row in reached_rows})
661
+ for row in reached_rows:
662
+ row["startRoutes"] = by_start[row["target"]]
536
663
  # Every call to each routine, and the calls to a noReturn routine that the declaration ended.
537
664
  call_sites, ended_sites = {}, {}
538
665
  for site, found in sorted(call_targets.items()):
@@ -623,6 +750,11 @@ def reach(image, config):
623
750
  "interpretation": "Routes over the decoded entry-path CFG from the starts. A chain has the fewest calls; "
624
751
  "throughEveryRoute lists the routine starts every read route to the target passes, "
625
752
  "and an unresolved transfer may add a route that passes none of them. "
753
+ "reachedFrom lists each start some read route reaches the target from, and startRoutes, "
754
+ "when asked for, gives each of them the fewest calls from it and the routine starts every "
755
+ "read route from it passes; a start reachedFrom does not list reaches the target by no "
756
+ "read route, which answers for that start only when negativeUsable holds, on the same "
757
+ "assumptions. "
626
758
  "negativeUsable needs a control of either kind, a walk that did not stop at its instruction limit, "
627
759
  "and no unresolved transfer, gap, returnCheckGaps row, contested instruction or contradicted noReturn "
628
760
  "routine, and still rests on the listed assumptions, leaves and noReturn declarations. "
@@ -852,5 +852,128 @@ class DeclaredIndirectCallTests(unittest.TestCase):
852
852
  computed(indirectCalls=[FAR_TARGETS] * 257)
853
853
 
854
854
 
855
+ # Three starts. A at 0000 calls H at 0010, which calls T at 001B and U at 001C. B at 0008 calls G at
856
+ # 0017, which calls T. C at 000C makes a computed call through BX.
857
+ STARTS = bytes.fromhex(
858
+ "e80d00" # 0000 A: call 0010
859
+ "c3" # 0003 ret
860
+ "90909090" # 0004 padding
861
+ "e80c00" # 0008 B: call 0017
862
+ "c3" # 000B ret
863
+ "ffd3" # 000C C: call bx
864
+ "c3" # 000E ret
865
+ "90" # 000F padding
866
+ "e80800" # 0010 H: call 001B
867
+ "e80600" # 0013 call 001C
868
+ "c3" # 0016 ret
869
+ "e80100" # 0017 G: call 001B
870
+ "c3" # 001A ret
871
+ "c3" # 001B T: ret
872
+ "c3" # 001C U: ret
873
+ )
874
+
875
+
876
+ def from_starts(data=STARTS, **extra):
877
+ return run_report(data, config(data, entries=(0, 8, 0x0C), **{"starts": [0, 8, 0x0C], "targets": [0x1B, 0x1C, 8],
878
+ "controls": [0, 8], **extra}), "reach")
879
+
880
+
881
+ RESOLVED = STARTS.replace(bytes.fromhex("ffd3c3"), bytes.fromhex("c39090"))
882
+
883
+
884
+ class ReachedFromTests(unittest.TestCase):
885
+ def test_each_reached_target_lists_the_starts_that_reach_it(self):
886
+ r = from_starts(RESOLVED)
887
+ t, u, b = r["targets"]
888
+ # The routes from A and from B share no routine, so no routine is on every route to T.
889
+ self.assertEqual(t["throughEveryRoute"], [])
890
+ self.assertEqual(t["reachedFrom"], [0, 8])
891
+ self.assertEqual(u["reachedFrom"], [0])
892
+ self.assertEqual(b["reachedFrom"], [8])
893
+ # C reaches nothing, the report is complete, and so C reaching none of the targets is a usable negative.
894
+ self.assertTrue(r["negativeUsable"])
895
+ self.assertNotIn("startRoutes", t)
896
+
897
+ def test_start_routes_give_each_start_its_own_calls_and_routines_on_every_route(self):
898
+ t, u, b = from_starts(RESOLVED, startRoutes=True)["targets"]
899
+ self.assertEqual(t["startRoutes"], [{"start": 0, "calls": 2, "throughEveryRoute": [0, 0x10]},
900
+ {"start": 8, "calls": 2, "throughEveryRoute": [8, 0x17]}])
901
+ self.assertEqual(u["startRoutes"], [{"start": 0, "calls": 2, "throughEveryRoute": [0, 0x10]}])
902
+ # A target at a start is reached from that start with no call, and is not on its own list.
903
+ self.assertEqual(b["startRoutes"], [{"start": 8, "calls": 0, "throughEveryRoute": []}])
904
+
905
+ def test_a_start_left_out_behind_an_unresolved_transfer_is_no_negative(self):
906
+ # C's computed call may reach T. It is unresolved, so C's absence from reachedFrom answers nothing.
907
+ r = from_starts(startRoutes=True)
908
+ self.assertEqual([(row["site"], row["routine"]) for row in r["unresolved"]], [(0x0C, 0x0C)])
909
+ self.assertEqual(r["targets"][0]["reachedFrom"], [0, 8])
910
+ self.assertEqual([row["start"] for row in r["targets"][0]["startRoutes"]], [0, 8])
911
+ self.assertFalse(r["negativeUsable"])
912
+
913
+ def test_a_start_whose_route_passes_another_start_lists_both(self):
914
+ # A calls B's entry instead of H, so T is reached from A through B and G, and U from no start.
915
+ data = RESOLVED.replace(bytes.fromhex("e80d00"), bytes.fromhex("e80500"), 1)
916
+ t, u, b = from_starts(data, controls=[0], startRoutes=True)["targets"]
917
+ self.assertEqual(t["reachedFrom"], [0, 8])
918
+ self.assertEqual(t["startRoutes"], [{"start": 0, "calls": 3, "throughEveryRoute": [0, 8, 0x17]},
919
+ {"start": 8, "calls": 2, "throughEveryRoute": [8, 0x17]}])
920
+ self.assertEqual(t["throughEveryRoute"], [8, 0x17])
921
+ self.assertEqual(t["chain"], [{"routine": 8}, {"callSite": 8, "routine": 0x17},
922
+ {"callSite": 0x17, "routine": 0x1B}])
923
+ self.assertEqual((u["reached"], u["status"]), (False, "not reached"))
924
+ self.assertEqual(b["reachedFrom"], [0, 8])
925
+ self.assertEqual(b["startRoutes"], [{"start": 0, "calls": 1, "throughEveryRoute": [0]},
926
+ {"start": 8, "calls": 0, "throughEveryRoute": []}])
927
+
928
+ def test_starts_in_one_loop_reach_each_other(self):
929
+ # A and B lie on one cycle, so each reaches the other, and both reach the return at 0006.
930
+ data = bytes.fromhex(
931
+ "eb02" # 0000 A: jmp 0004
932
+ "ebfc" # 0002 B: jmp 0000
933
+ "7401" # 0004 jz 0007
934
+ "c3" # 0006 ret
935
+ "ebf9" # 0007 jmp 0002
936
+ )
937
+ r = run_report(data, config(data, entries=(0, 2), starts=[0, 2], targets=[0, 2, 6], startRoutes=True),
938
+ "reach")
939
+ self.assertEqual([row["reachedFrom"] for row in r["targets"]], [[0, 2], [0, 2], [0, 2]])
940
+ # B's routes enter A by a jump, so A is no routine start on them, as in a walk from B alone. The
941
+ # row's own throughEveryRoute counts every start as a routine start.
942
+ self.assertEqual(r["targets"][2]["startRoutes"], [{"start": 0, "calls": 0, "throughEveryRoute": [0]},
943
+ {"start": 2, "calls": 0, "throughEveryRoute": [2]}])
944
+ alone = run_report(data, config(data, entries=(0, 2), starts=[2], targets=[6]), "reach")
945
+ self.assertEqual(alone["targets"][0]["throughEveryRoute"], [2])
946
+
947
+ def test_a_start_dropped_by_an_unresolved_overlap_is_no_negative(self):
948
+ # B's mov at 0008 holds A's jmp at 0009, and neither boundary is proven, so the shared walk keeps
949
+ # neither. A walk from A alone reaches T at 0010; the shared one lists only C, and the gap keeps
950
+ # A's absence from answering anything.
951
+ data = bytes.fromhex(
952
+ "9090909090909090" # 0000 padding
953
+ "b8eb05" # 0008 B: mov ax, 05EBh
954
+ "eb03" # 000B C: jmp 0010 (0009, inside B's mov, is A: jmp 0010)
955
+ "909090" # 000D padding
956
+ "c3" # 0010 T: ret
957
+ )
958
+ r = run_report(data, config(data, entries=(8, 9, 0x0B), starts=[8, 9, 0x0B], targets=[0x10],
959
+ instructionControls=[0x10]), "reach")
960
+ self.assertEqual(r["targets"][0]["reachedFrom"], [0x0B])
961
+ self.assertEqual(r["contested"], [])
962
+ self.assertEqual({g["site"] for g in r["gaps"]}, {8, 9})
963
+ self.assertFalse(r["negativeUsable"])
964
+ alone = run_report(data, config(data, entries=(8, 9, 0x0B), starts=[9], targets=[0x10]), "reach")
965
+ self.assertEqual(alone["targets"][0]["reachedFrom"], [9])
966
+
967
+ def test_a_single_start_lists_itself_with_the_report_route(self):
968
+ target = reach(indirectJumps=[TABLE], startRoutes=True)["targets"][0]
969
+ self.assertEqual(target["reachedFrom"], [0])
970
+ self.assertEqual(target["startRoutes"], [{"start": 0, "calls": target["calls"],
971
+ "throughEveryRoute": target["throughEveryRoute"]}])
972
+
973
+ def test_start_routes_must_be_a_boolean(self):
974
+ with self.assertRaisesRegex(ValueError, "startRoutes must be a boolean"):
975
+ reach(indirectJumps=[TABLE], startRoutes="yes")
976
+
977
+
855
978
  if __name__ == "__main__":
856
979
  unittest.main()