scientific-method-engine 19.4.0__tar.gz → 19.6.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.6.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/cli.py +8 -3
  4. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/dispatch.py +100 -11
  5. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/inventory.py +11 -6
  6. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/pcode_backend.py +5 -1
  7. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/reach.py +213 -42
  8. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/trace.py +4 -4
  9. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_inventory_check.py +28 -0
  10. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_reach.py +232 -6
  11. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/.gitignore +0 -0
  12. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/LICENSE +0 -0
  13. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/README.md +0 -0
  14. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/__init__.py +0 -0
  15. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/__main__.py +0 -0
  16. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  17. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  18. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  19. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  20. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  21. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  22. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  23. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  24. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  25. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  26. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  27. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  28. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  29. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  30. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  31. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  32. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  33. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  34. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  35. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  36. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  37. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  38. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  39. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  40. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  41. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  42. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportRangeBoundaries.java +0 -0
  43. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  44. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  45. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  46. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  47. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  48. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  49. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +0 -0
  50. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/scientificmethod/Xxh3.java +0 -0
  51. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  52. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  53. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/derived_counts.py +0 -0
  54. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  55. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/image.py +0 -0
  56. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/loops.py +0 -0
  57. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/machine.py +0 -0
  58. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  59. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  60. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/pe.py +0 -0
  61. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/ranges.py +0 -0
  62. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/relational.py +0 -0
  63. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/reports.py +0 -0
  64. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  65. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/table_bounds.py +0 -0
  66. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/values.py +0 -0
  67. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/oracle.py +0 -0
  68. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_config_encoding.py +0 -0
  69. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_continuation_budget.py +0 -0
  70. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_derived_counts.py +0 -0
  71. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_dispatch.py +0 -0
  72. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_effect_order.py +0 -0
  73. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_enter_frames.py +0 -0
  74. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_entry_frame.py +0 -0
  75. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_indirect_far_transfers.py +0 -0
  76. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_interrupt_models.py +0 -0
  77. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_join_terms.py +0 -0
  78. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_loops.py +0 -0
  79. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_memory_scopes.py +0 -0
  80. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_nested_frame_request.py +0 -0
  81. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_oracle.py +0 -0
  82. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_pe.py +0 -0
  83. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_ranges.py +0 -0
  84. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_relational_controls.py +0 -0
  85. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_return_checks.py +0 -0
  86. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_successor_rule.py +0 -0
  87. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_table_bounds.py +0 -0
  88. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_table_continuations.py +0 -0
  89. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_term_limit.py +0 -0
  90. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_upstream_gaps.py +0 -0
  91. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_volatile_memory.py +0 -0
  92. {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.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.6.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.6.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"
@@ -32,14 +33,18 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
32
33
  "is followed, and each is repeated with its reason and where it cut the walk, not checked or assumed;\n"
33
34
  "the noReturn check reads past the stops, and returnCheckGaps lists what it could not read there;\n"
34
35
  "indirectCalls declares the targets of a computed call as a table read from the build or a list,\n"
35
- "and the walk calls each of them; one not declared exhaustive stays unresolved;\n"
36
+ "and the walk calls each of them; one not declared exhaustive stays unresolved; outside names where the\n"
37
+ "call leaves the image (a saved vector, an interrupt's returned pointer or a description), which is not\n"
38
+ "read and is grouped in outsideTransfers, and an exhaustive empty targets list says the call never runs;\n"
36
39
  "an exhaustive indirectJumps or indirectCalls table can leave out count and give bound {routine}:\n"
37
40
  "the engine derives its rows from a value-range analysis of that routine and lists the derivation,\n"
38
41
  "a count it cannot prove leaves the site unresolved with its reasons, a declared count larger than\n"
39
42
  "the proven one is refused, and a walk edge that enters the routine other than at its start is a gap;\n"
40
43
  "controls are call sites the walk must reach and resolve, instructionControls sites it must decode,\n"
41
44
  "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"
45
+ "decodedRanges true lists every instruction the walk decoded as half-open ranges with their routine;\n"
46
+ "startRoutes true gives each reached target, for each start it is reached from, the fewest calls and the\n"
47
+ "routines every read route from that start passes.\n"
43
48
  "inventory-check places every resolved direct call target in the notation of the function inventory TSV\n"
44
49
  "that inventory names and lists each target no row starts at: inside another row's body or outside every row,\n"
45
50
  "with one calling site, near or far, and whether an entry-path call, a contested one or only raw bytes call it;\n"
@@ -1,6 +1,7 @@
1
1
  """Explicit, source-derived indirect jump tables and call targets for CFG discovery, and explicitly conditional path continuations."""
2
2
  from capstone.x86 import X86_OP_IMM, X86_OP_MEM
3
3
  from .image import integer
4
+ from .pcode_backend import interrupt_vector, INTERRUPTS
4
5
 
5
6
  CALL_NOT_EXHAUSTIVE = "indirect call targets are not declared exhaustive"
6
7
  JUMP_NOT_EXHAUSTIVE = "indirect jump table is not declared exhaustive"
@@ -214,7 +215,12 @@ def indirect_call_declarations(value, image):
214
215
 
215
216
  Each declaration names a ``site`` that decodes as an unprefixed segmented16 computed call (a near
216
217
  call through a word register or memory operand, or a far call through memory), its ``evidence``,
217
- an explicit boolean ``exhaustive``, and exactly one of ``table`` and ``targets``. A table's rows are
218
+ an explicit boolean ``exhaustive``, at most one of ``table`` and ``targets``, and ``outside`` when
219
+ it has neither (ADR 0042). ``outside`` states that the call can leave the declared code, for one
220
+ stated destination: a saved interrupt ``vector``, the far pointer an ``interrupt`` site returned,
221
+ or a ``description`` of other code outside the image; it is returned normalized by
222
+ ``outside_destination``. An exhaustive declaration may give an empty ``targets`` list, which states
223
+ that the call never runs. A table's rows are
218
224
  read from the source bytes as ``indirectJumps`` reads them: words placed through the call site's
219
225
  region mapping for a near call, and for a far call ``offset, segment`` word pairs whose segment
220
226
  word has a declared relocation, admitted as ``Image.far_pointer_target`` admits the pointer a
@@ -235,9 +241,11 @@ def indirect_call_declarations(value, image):
235
241
  result = {}
236
242
  image.derived_call_reads = {}
237
243
  for claim in value:
238
- keys = set(claim) if isinstance(claim, dict) else None
239
- if keys not in ({"site", "evidence", "exhaustive", "table"}, {"site", "evidence", "exhaustive", "targets"}):
240
- raise ValueError("Each indirect call needs site, evidence, exhaustive and exactly one of table and targets")
244
+ keys = set(claim) - {"outside"} if isinstance(claim, dict) else None
245
+ base = {"site", "evidence", "exhaustive"}
246
+ if keys not in (base | {"table"}, base | {"targets"}) and not (keys == base and "outside" in claim):
247
+ raise ValueError("Each indirect call needs site, evidence, exhaustive, at most one of table and targets, "
248
+ "and outside when it has neither")
241
249
  site = integer(claim["site"], 0, len(image.data) - 1, "indirect call site")
242
250
  if site in result:
243
251
  raise ValueError("Duplicate indirect call site")
@@ -254,7 +262,12 @@ def indirect_call_declarations(value, image):
254
262
  "or a far call through memory")
255
263
  declaration = {"site": site, "instruction": (ins.mnemonic + " " + ins.op_str).strip(),
256
264
  "evidence": claim["evidence"], "exhaustive": claim["exhaustive"]}
257
- if "table" in claim:
265
+ if "outside" in claim:
266
+ declaration["outside"] = outside_destination(claim["outside"], image, site, far)
267
+ if "table" not in claim and "targets" not in claim:
268
+ # An outside destination alone: the call names no target in declared code.
269
+ targets = []
270
+ elif "table" in claim:
258
271
  table, width = claim["table"], 4 if far else 2
259
272
  if not isinstance(table, dict) or not isinstance(table.get("evidence"), str) or not table["evidence"].strip():
260
273
  raise ValueError("An indirect call table needs layout/count evidence")
@@ -279,9 +292,15 @@ def indirect_call_declarations(value, image):
279
292
  targets = [row["target"] for row in rows]
280
293
  else:
281
294
  targets = claim["targets"]
282
- if (not isinstance(targets, list) or not 1 <= len(targets) <= 256
295
+ if (not isinstance(targets, list) or len(targets) > 256
283
296
  or len(set(map(repr, targets))) != len(targets)):
284
- raise ValueError("indirect call targets must be a list of 1..256 distinct file offsets")
297
+ raise ValueError("indirect call targets must be a list of 0..256 distinct file offsets")
298
+ # No targets says the call never runs, which only an exhaustive declaration without an outside
299
+ # destination can state; anything else would be an undeclared call with extra words.
300
+ if not targets and (not claim["exhaustive"] or "outside" in claim):
301
+ raise ValueError(f"indirect call {site} declares no targets, which states that the call never runs; "
302
+ "that needs exhaustive true and no outside (give outside alone for a call that "
303
+ "leaves the declared code)")
285
304
  for at in targets:
286
305
  integer(at, 0, len(image.data) - 1, "indirect call target")
287
306
  region = image.region(at)
@@ -298,6 +317,50 @@ def indirect_call_declarations(value, image):
298
317
  return result
299
318
 
300
319
 
320
+ def declared_interrupt(image, at, label, conditional_reason):
321
+ """``(ins, vector)`` for the unconditional interrupt instruction at ``at``, which a declaration names as ``label``.
322
+
323
+ ``at`` must lie in declared code and decode as an interrupt, whatever prefix capstone names in the
324
+ mnemonic; a conditional interrupt (INTO) is refused with ``conditional_reason``.
325
+ """
326
+ if image.region(at) is None:
327
+ raise ValueError(f"{label} {at} is outside declared code")
328
+ ins = image.decode(at)
329
+ if ins is None or ins.mnemonic.split()[-1] not in INTERRUPTS:
330
+ raise ValueError(f"{label} {at} is not an interrupt instruction")
331
+ vector, conditional = interrupt_vector(image.flat, ins, at)
332
+ if conditional:
333
+ raise ValueError(f"{label} {at} is conditional {conditional_reason}")
334
+ return ins, vector
335
+
336
+
337
+ def outside_destination(value, image, site, far):
338
+ """The normalized ``outside`` destination of the declared indirect call at ``site``.
339
+
340
+ ``value`` names exactly one of ``vector`` (0..255: the call enters the handler that held that
341
+ interrupt vector before the program replaced it), ``interrupt`` (a file offset in declared code
342
+ that decodes as an unconditional interrupt instruction: the call goes through the far pointer
343
+ that interrupt returned, and the result adds the interrupt's ``vector`` and ``instruction``) or
344
+ ``description`` (nonempty free text naming other code outside the image, such as code built on
345
+ the stack or a table a loaded driver fills). A saved vector and an interrupt's returned pointer
346
+ are far pointers, so those two need a far call.
347
+ """
348
+ if not isinstance(value, dict) or len(value) != 1 or set(value) - {"vector", "interrupt", "description"}:
349
+ raise ValueError(f"indirect call {site} outside needs exactly one of vector, interrupt and description")
350
+ kind, given = next(iter(value.items()))
351
+ if kind != "description" and not far:
352
+ raise ValueError(f"indirect call {site} outside {kind} names a far pointer, which a near call cannot use")
353
+ if kind == "vector":
354
+ return {"vector": integer(given, 0, 255, "outside vector")}
355
+ if kind == "description":
356
+ if not isinstance(given, str) or not given.strip():
357
+ raise ValueError(f"indirect call {site} outside description must be nonempty text")
358
+ return {"description": given}
359
+ at = integer(given, 0, len(image.data) - 1, "outside interrupt")
360
+ ins, vector = declared_interrupt(image, at, f"indirect call {site} outside interrupt", "and may return nothing")
361
+ return {"interrupt": at, "vector": vector, "instruction": (ins.mnemonic + " " + ins.op_str).strip()}
362
+
363
+
301
364
  def open_reason(declaration, call):
302
365
  """Why a declared table or call leaves its site unresolved, or None.
303
366
 
@@ -321,11 +384,37 @@ def derived_assumptions(image, indirect_calls):
321
384
  return []
322
385
 
323
386
 
387
+ def never_runs(declaration):
388
+ """Whether a declared indirect call states that it never runs: exhaustive, with an empty ``targets`` list
389
+ and no outside. A table whose count was not proven also has no targets, but it is unresolved, not empty."""
390
+ return (declaration["exhaustive"] and "table" not in declaration and not declaration["targets"]
391
+ and "outside" not in declaration)
392
+
393
+
324
394
  def declared_call_ends(declaration, no_return_calls):
325
- """Whether a declared indirect call ends its branch: nothing leaves it unresolved (``open_reason``) and
326
- every target is in ``no_return_calls``."""
327
- return open_reason(declaration, True) is None and all(target in no_return_calls
328
- for target in declaration["targets"])
395
+ """Whether a declared indirect call ends its branch: nothing leaves it unresolved (``open_reason``), it
396
+ has no ``outside`` destination (which the walk does not read, so it is assumed to return), and every
397
+ target is in ``no_return_calls``.
398
+
399
+ A declaration that ``never_runs`` ends its branch, since the next instruction is reached through the
400
+ call only once it has run.
401
+ """
402
+ return (open_reason(declaration, True) is None and "outside" not in declaration
403
+ and all(target in no_return_calls for target in declaration["targets"]))
404
+
405
+
406
+ def indirect_call_assumptions(indirect_calls):
407
+ """The assumptions the ``indirectCalls`` declarations add to a report."""
408
+ if not indirect_calls:
409
+ return []
410
+ found = ["each declared indirect call can call the targets its declaration gives, for the evidence it gives, "
411
+ "and only those when it is declared exhaustive"]
412
+ if any("outside" in declaration for declaration in indirect_calls.values()):
413
+ found.append("each declared outside destination is where its call can leave the declared code, for the "
414
+ "evidence it gives; the code there is not read, and it returns to the call's next instruction")
415
+ if any(never_runs(declaration) for declaration in indirect_calls.values()):
416
+ found.append("each indirect call declared exhaustive with no targets never runs, for the evidence it gives")
417
+ return found
329
418
 
330
419
 
331
420
  def call_ends(site, target, indirect_calls, no_return_calls):
@@ -4,7 +4,7 @@ from bisect import bisect_right
4
4
  from pathlib import Path
5
5
  from .image import integer
6
6
  from .trace import LIMIT_REASON, CONTESTED_REASON, OVERLAP_REASON, walk, holding_instruction
7
- from .dispatch import indirect_call_declarations, call_ends, derived_assumptions
7
+ from .dispatch import indirect_call_declarations, call_ends, never_runs, indirect_call_assumptions, derived_assumptions
8
8
 
9
9
  MAX_INVENTORY = 16 * 1024 * 1024
10
10
  MAX_ROWS = 200000
@@ -425,6 +425,11 @@ def inventory_check(image, config):
425
425
  def site_classification(at):
426
426
  return "entry-path instruction" if at in seen else CONTESTED_REASON if at in contested else "declared site"
427
427
  listed = {site for site, *_ in ends}
428
+ # A call declared never to run has no target, so no call row holds it, yet it ends the branch as an
429
+ # exhaustive call whose every target is noReturn does; it is listed as one with no routines.
430
+ never = [at for at, declaration in indirect_calls.items() if never_runs(declaration)]
431
+ ends += [(at, image.decode(at).size, "call", [], site_classification(at)) for at in never]
432
+ listed |= set(never)
428
433
  ends += [(at, row["following"] - at, "call site",
429
434
  site_targets[at][0] if len(site_targets[at]) == 1 else site_targets[at] or None, site_classification(at))
430
435
  for at, row in no_return_sites.items() if at not in listed]
@@ -528,15 +533,13 @@ def inventory_check(image, config):
528
533
  if target_stopped:
529
534
  summary += (" The walk that checks the targets of the noReturn calls stopped at its instruction limit, so it "
530
535
  "can miss returns.")
531
- assumptions = [call_assumption(no_return_routines, no_return_sites)]
536
+ assumptions = [call_assumption(no_return_routines, no_return_sites, indirect_calls)]
532
537
  if checked:
533
538
  assumptions.append("each interrupt the noReturn check reads returns to its next instruction"
534
539
  + (", except at a noReturn interrupt site" if no_return_interrupts else "")
535
540
  + "; interrupt handlers are not read")
536
541
  assumptions += no_return_assumptions(no_return_routines, no_return_interrupts, no_return_sites)
537
- if indirect_calls:
538
- assumptions.append("each declared indirect call can call the targets its declaration gives, for the evidence "
539
- "it gives, and only those when it is declared exhaustive")
542
+ assumptions += indirect_call_assumptions(indirect_calls)
540
543
  assumptions += derived_assumptions(image, indirect_calls)
541
544
  indirect_rows = [declaration | {"reached": site in seen} for site, declaration in indirect_calls.items()]
542
545
  return {"inventory": {"path": config["inventory"], "rows": len(rows)},
@@ -556,7 +559,9 @@ def inventory_check(image, config):
556
559
  "partialSearch": partial, "gaps": calls["gaps"],
557
560
  "exclusions": ["computed call targets no indirectCalls declaration gives (listed in unresolved when the "
558
561
  "walk reaches them)", "unrelocated far calls",
559
- "undeclared mappings", "prefix-started raw candidates off the entry path", "jump targets"],
562
+ "undeclared mappings", "prefix-started raw candidates off the entry path", "jump targets"]
563
+ + (["the code a declared outside destination names, and anything it calls"]
564
+ if any("outside" in declaration for declaration in indirect_calls.values()) else []),
560
565
  "interpretation": "Each distinct resolved direct call target in the searched regions, placed in the inventory's "
561
566
  "notation and compared with its rows. A target only raw byte candidates or contested "
562
567
  "instructions call is not shown to be code. The counts are lower bounds on the targets "
@@ -988,6 +988,10 @@ def port_access(state, ins, direction, port, value, size):
988
988
  return result
989
989
 
990
990
 
991
+ # The interrupt mnemonics, as capstone names them without a prefix.
992
+ INTERRUPTS = ("int", "int1", "int3", "into")
993
+
994
+
991
995
  def interrupt_vector(flat, ins, site):
992
996
  """The vector p-code's ``swi`` operation names, and whether the interrupt is conditional (INTO)."""
993
997
  ops, _ = LIFTER.ops(flat, bytes(ins.bytes), site)
@@ -1015,7 +1019,7 @@ for names, handler in ((("mov", "movzx", "movsx", "xchg"), move), (("nop",), nop
1015
1019
  (("shl", "sal", "shr", "sar"), shift), (("rol", "ror", "rcl", "rcr"), rotate),
1016
1020
  (("mul", "imul"), multiply), (("div", "idiv"), divide),
1017
1021
  (("cbw", "cwde", "cwd", "cdq"), conversion), (("cld", "std", "cli", "sti"), flag_write),
1018
- (("in", "out"), run_plain), (("int", "int1", "int3", "into"), interrupt)):
1022
+ (("in", "out"), run_plain), (INTERRUPTS, interrupt)):
1019
1023
  for name in names:
1020
1024
  HANDLERS[name] = handler
1021
1025