scientific-method-engine 18.3.0__tar.gz → 19.0.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 (89) hide show
  1. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/cli.py +5 -1
  4. scientific_method_engine-19.0.0/src/scientific_method_engine/x86/dispatch.py +168 -0
  5. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/inventory.py +123 -26
  6. scientific_method_engine-19.0.0/src/scientific_method_engine/x86/ranges.py +592 -0
  7. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/reach.py +60 -27
  8. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/reports.py +21 -4
  9. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/trace.py +26 -6
  10. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_inventory_check.py +108 -4
  11. scientific_method_engine-19.0.0/tests/test_ranges.py +419 -0
  12. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_reach.py +174 -0
  13. scientific_method_engine-18.3.0/src/scientific_method_engine/x86/dispatch.py +0 -51
  14. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/.gitignore +0 -0
  15. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/LICENSE +0 -0
  16. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/README.md +0 -0
  17. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/__init__.py +0 -0
  18. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/__main__.py +0 -0
  19. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  20. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  21. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  22. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  23. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  24. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  25. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  26. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  27. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  28. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  29. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  30. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  31. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  32. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  33. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  34. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  35. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  36. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  37. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  38. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  39. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  40. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  41. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  42. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  43. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  44. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  45. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportRangeBoundaries.java +0 -0
  46. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  47. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  48. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  49. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  50. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  51. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  52. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +0 -0
  53. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/ghidra/scientificmethod/Xxh3.java +0 -0
  54. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  55. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  56. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  57. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/image.py +0 -0
  58. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/loops.py +0 -0
  59. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/machine.py +0 -0
  60. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  61. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  62. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  63. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/pe.py +0 -0
  64. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/relational.py +0 -0
  65. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  66. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/src/scientific_method_engine/x86/values.py +0 -0
  67. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/oracle.py +0 -0
  68. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_config_encoding.py +0 -0
  69. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_continuation_budget.py +0 -0
  70. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_dispatch.py +0 -0
  71. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_effect_order.py +0 -0
  72. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_enter_frames.py +0 -0
  73. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_entry_frame.py +0 -0
  74. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_indirect_far_transfers.py +0 -0
  75. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_interrupt_models.py +0 -0
  76. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_join_terms.py +0 -0
  77. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_loops.py +0 -0
  78. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_memory_scopes.py +0 -0
  79. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_nested_frame_request.py +0 -0
  80. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_oracle.py +0 -0
  81. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_pe.py +0 -0
  82. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_relational_controls.py +0 -0
  83. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_return_checks.py +0 -0
  84. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_successor_rule.py +0 -0
  85. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_table_continuations.py +0 -0
  86. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_term_limit.py +0 -0
  87. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_upstream_gaps.py +0 -0
  88. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.0}/tests/test_volatile_memory.py +0 -0
  89. {scientific_method_engine-18.3.0 → scientific_method_engine-19.0.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.3.0
3
+ Version: 19.0.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.3.0"
8
+ version = "19.0.0"
9
9
  description = "Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code."
10
10
  readme = "README.md"
11
11
  requires-python = ">=3.12"
@@ -27,6 +27,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
27
27
  "a call to a noReturn routine and a noReturn interrupt do not continue at the next instruction,\n"
28
28
  "and a noReturn routine with a return, or a jump into a returning leaf, on its own read paths\n"
29
29
  "is reported contradicted;\n"
30
+ "indirectCalls declares the targets of a computed call as a table read from the build or a list,\n"
31
+ "and the walk calls each of them; one not declared exhaustive stays unresolved;\n"
30
32
  "controls are call sites the walk must reach and resolve, instructionControls sites it must decode,\n"
31
33
  "and a failed control fails the report saying whether it was reached.\n"
32
34
  "inventory-check places every resolved direct call target in the notation of the function inventory TSV\n"
@@ -34,10 +36,12 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
34
36
  "with one calling site, near or far, and whether an entry-path call, a contested one or only raw bytes call it;\n"
35
37
  "a target inside an instruction the entry-path walk established from another start names it as insideInstruction.\n"
36
38
  "It lists each row whose start lies inside an instruction the walk established (rowStarts), with the\n"
37
- "routine the walk read it in; a row start in bytes the walk did not decode is counted, not placed.\n"
39
+ "routine the walk read it in, and each row start at or inside an instruction of an overlap the walk left\n"
40
+ "unresolved, with the instructions it overlaps; a row start in bytes the walk did not decode is counted, not placed.\n"
38
41
  "noReturn takes reach's declarations: the walk stops at a call to a declared routine and at a declared\n"
39
42
  "interrupt, a declared routine with a return on its own read paths is reported contradicted, and\n"
40
43
  "rowsPastNoReturn lists each row whose body continues past such a call or interrupt.\n"
44
+ "indirectCalls takes reach's declarations: each declared target of a reached computed call is a call target.\n"
41
45
  "uses matches accesses whose footprint intersects query offset..offset+width; its rawCandidates give each unreached\n"
42
46
  "operand's encoded displacement, width, access, segment register and intersection, and never count as uses.\n"
43
47
  "trace, arguments, effects, returns, guards, memory and allocation check relationalControls:\n"
@@ -0,0 +1,168 @@
1
+ """Explicit, source-derived indirect jump tables and call targets for CFG discovery, and explicitly conditional path continuations."""
2
+ from capstone.x86 import X86_OP_IMM, X86_OP_MEM
3
+ from .image import integer
4
+
5
+ CALL_NOT_EXHAUSTIVE = "indirect call targets are not declared exhaustive"
6
+
7
+
8
+ def _word(image, at):
9
+ return int.from_bytes(image.data[at:at + 2], "little")
10
+
11
+
12
+ def _table_operands(image, table, width, label, field_label):
13
+ """The file offset of each row's target field in a declared ``table`` of ``width``-byte targets."""
14
+ start = integer(table.get("start"), 0, len(image.data) - 1, f"{label} start")
15
+ count = integer(table.get("count"), 1, 256, f"{label} count")
16
+ stride = integer(table.get("stride"), width, 65536, f"{label} stride")
17
+ field = integer(table.get("fieldOffset", 0), 0, stride - width, field_label)
18
+ if start + (count - 1) * stride + field + width > len(image.data):
19
+ raise ValueError(f"{label[0].upper()}{label[1:]} leaves source bounds")
20
+ return [start + index * stride + field for index in range(count)]
21
+
22
+
23
+ def read_indirect_jumps(image):
24
+ declarations = image.config.get("indirectJumps", [])
25
+ if not isinstance(declarations, list) or len(declarations) > 256:
26
+ raise ValueError("indirectJumps must contain at most 256 declarations")
27
+ if declarations and image.flat:
28
+ raise ValueError("indirectJumps currently requires segmented16")
29
+ result = {}
30
+ for claim in declarations:
31
+ if not isinstance(claim, dict):
32
+ raise ValueError("Each indirect jump needs an object")
33
+ site = integer(claim.get("site"), 0, len(image.data) - 1, "indirect jump site")
34
+ if site in result:
35
+ raise ValueError("Duplicate indirect jump site")
36
+ if not isinstance(claim.get("evidence"), str) or not claim["evidence"].strip():
37
+ raise ValueError("An indirect jump needs consumer/mapping evidence")
38
+ if type(claim.get("exhaustive")) is not bool:
39
+ raise ValueError("An indirect jump needs explicit exhaustive true or false")
40
+ ins = image.decode(site)
41
+ if (ins is None or ins.mnemonic != "jmp" or len(ins.operands) != 1
42
+ or ins.operands[0].type == X86_OP_IMM or ins.operands[0].size != 2
43
+ or 0x66 in ins.prefix or 0x67 in ins.prefix):
44
+ raise ValueError("indirectJumps site must decode as an unprefixed computed near word jump")
45
+ table = claim.get("table")
46
+ if not isinstance(table, dict) or not isinstance(table.get("evidence"), str) or not table["evidence"].strip():
47
+ raise ValueError("Indirect table needs layout/count evidence")
48
+ if type(table.get("width", 2)) is not int or table.get("width", 2) != 2:
49
+ raise ValueError("Indirect table targets must be word width 2")
50
+ rows = []
51
+ operands = _table_operands(image, table, 2, "indirect table", "indirect target field offset")
52
+ for index, operand in enumerate(operands):
53
+ raw = _word(image, operand)
54
+ target = image.near_target(site, raw)
55
+ if target is None:
56
+ raise ValueError("Indirect table target leaves declared code mappings")
57
+ rows.append({"index": index, "operandSite": operand, "rawOffset": raw, "target": target})
58
+ result[site] = {"site": site, "evidence": claim["evidence"], "table": table,
59
+ "exhaustive": claim["exhaustive"], "rows": rows,
60
+ "interpretation": "source words under supplied consumer, mapping and exhaustiveness evidence; "
61
+ "not executed dispatch or an overlap-boundary proof"}
62
+ return result
63
+
64
+
65
+ def indirect_call_declarations(value, image):
66
+ """The declared targets of computed calls, by call site, as ``reach`` and ``inventory-check`` take them.
67
+
68
+ Each declaration names a ``site`` that decodes as an unprefixed segmented16 computed call (a near
69
+ call through a word register or memory operand, or a far call through memory), its ``evidence``,
70
+ an explicit boolean ``exhaustive``, and exactly one of ``table`` and ``targets``. A table's rows are
71
+ read from the source bytes as ``indirectJumps`` reads them: words placed through the call site's
72
+ region mapping for a near call, and for a far call ``offset, segment`` word pairs whose segment
73
+ word has a declared relocation, admitted as ``Image.far_pointer_target`` admits the pointer a
74
+ traced far call reads; a far row whose pointer names an FBOV trampoline carries its
75
+ ``trampoline``. ``targets`` gives file offsets in declared code, which rest on the evidence
76
+ alone; a near call's targets must be bytes some IP in the call site's segment places. Each
77
+ declaration is returned with the call's ``instruction`` text, a table's ``rows``, and its
78
+ distinct ``targets`` in row order.
79
+ """
80
+ if not isinstance(value, list) or len(value) > 256:
81
+ raise ValueError("indirectCalls must be a list of at most 256 declarations")
82
+ if value and image.flat:
83
+ raise ValueError("indirectCalls currently requires segmented16")
84
+ result = {}
85
+ for claim in value:
86
+ keys = set(claim) if isinstance(claim, dict) else None
87
+ if keys not in ({"site", "evidence", "exhaustive", "table"}, {"site", "evidence", "exhaustive", "targets"}):
88
+ raise ValueError("Each indirect call needs site, evidence, exhaustive and exactly one of table and targets")
89
+ site = integer(claim["site"], 0, len(image.data) - 1, "indirect call site")
90
+ if site in result:
91
+ raise ValueError("Duplicate indirect call site")
92
+ if not isinstance(claim["evidence"], str) or not claim["evidence"].strip():
93
+ raise ValueError("An indirect call needs evidence that connects the call's operand to its targets")
94
+ if type(claim["exhaustive"]) is not bool:
95
+ raise ValueError("An indirect call needs explicit exhaustive true or false")
96
+ ins = image.decode(site)
97
+ far = ins is not None and ins.mnemonic == "lcall"
98
+ if (ins is None or ins.mnemonic not in ("call", "lcall") or len(ins.operands) != 1
99
+ or ins.operands[0].type == X86_OP_IMM or (far and ins.operands[0].type != X86_OP_MEM)
100
+ or (not far and ins.operands[0].size != 2) or 0x66 in ins.prefix or 0x67 in ins.prefix):
101
+ raise ValueError(f"indirect call site {site} must decode as an unprefixed computed near word call "
102
+ "or a far call through memory")
103
+ declaration = {"site": site, "instruction": (ins.mnemonic + " " + ins.op_str).strip(),
104
+ "evidence": claim["evidence"], "exhaustive": claim["exhaustive"]}
105
+ if "table" in claim:
106
+ table, width = claim["table"], 4 if far else 2
107
+ if not isinstance(table, dict) or not isinstance(table.get("evidence"), str) or not table["evidence"].strip():
108
+ raise ValueError("An indirect call table needs layout/count evidence")
109
+ if type(table.get("width", width)) is not int or table.get("width", width) != width:
110
+ raise ValueError(f"An indirect {'far' if far else 'near'} call table holds {width}-byte targets, "
111
+ f"so its width must be {width}")
112
+ rows = []
113
+ operands = _table_operands(image, table, width, "indirect call table", "indirect call target field offset")
114
+ for index, operand in enumerate(operands):
115
+ row = {"index": index, "operandSite": operand, "rawOffset": _word(image, operand)}
116
+ if far:
117
+ # The segment word is relocated at load time, and the pointer is admitted as a traced far
118
+ # call through memory admits the pointer it reads (Image.far_pointer_target).
119
+ fixup = image.fixups.get(operand + 2)
120
+ if fixup is None:
121
+ raise ValueError(f"Indirect call table row {index} has no declared relocation for its segment "
122
+ f"word at {operand + 2}")
123
+ target, admission = image.far_pointer_target(fixup["segment"], row["rawOffset"])
124
+ if target is None:
125
+ raise ValueError(f"Indirect call table row {index} target is not admitted: {admission['reason']}")
126
+ row |= {"rawSegment": _word(image, operand + 2), "resolvedSegment": fixup["segment"]}
127
+ # A pointer at an FBOV trampoline continues at its overlay entry, which the row names.
128
+ if "trampoline" in admission:
129
+ row["trampoline"] = admission["trampoline"]
130
+ else:
131
+ target = image.near_target(site, row["rawOffset"])
132
+ if target is None or image.region(target) is None:
133
+ raise ValueError(f"Indirect call table row {index} target leaves declared code mappings")
134
+ rows.append(row | {"target": target})
135
+ declaration |= {"table": table, "rows": rows}
136
+ targets = [row["target"] for row in rows]
137
+ else:
138
+ targets = claim["targets"]
139
+ if (not isinstance(targets, list) or not 1 <= len(targets) <= 256
140
+ or len(set(map(repr, targets))) != len(targets)):
141
+ raise ValueError("indirect call targets must be a list of 1..256 distinct file offsets")
142
+ for at in targets:
143
+ integer(at, 0, len(image.data) - 1, "indirect call target")
144
+ region = image.region(at)
145
+ if region is None:
146
+ raise ValueError(f"indirect call target {at} is outside declared code")
147
+ if not far:
148
+ # A near call keeps CS, so its target needs an IP that the call site's mapping places there.
149
+ linear = region["segment"] * 16 + region["ip"] + at - region["start"]
150
+ ip = linear - image.region(site)["segment"] * 16
151
+ if not 0 <= ip <= image.mask or image.near_target(site, ip) != at:
152
+ raise ValueError(f"indirect call target {at} is not placed by any IP in the near call "
153
+ f"site {site}'s segment")
154
+ result[site] = declaration | {"targets": list(dict.fromkeys(targets))}
155
+ return result
156
+
157
+
158
+ def declared_call_ends(declaration, no_return_calls):
159
+ """Whether a declared indirect call ends its branch: it is exhaustive and every target is in ``no_return_calls``."""
160
+ return declaration["exhaustive"] and all(target in no_return_calls for target in declaration["targets"])
161
+
162
+
163
+ def call_ends(site, target, indirect_calls, no_return_calls):
164
+ """Whether the call at ``site`` to ``target`` ends its branch, under ``declared_call_ends`` for a declared site."""
165
+ declaration = indirect_calls.get(site)
166
+ if declaration is not None:
167
+ return declared_call_ends(declaration, no_return_calls)
168
+ return target in no_return_calls
@@ -3,7 +3,8 @@ import re
3
3
  from bisect import bisect_right
4
4
  from pathlib import Path
5
5
  from .image import integer
6
- from .trace import LIMIT_REASON, CONTESTED_REASON, walk, holding_instruction
6
+ from .trace import LIMIT_REASON, CONTESTED_REASON, OVERLAP_REASON, walk, holding_instruction
7
+ from .dispatch import indirect_call_declarations, call_ends
7
8
 
8
9
  MAX_INVENTORY = 16 * 1024 * 1024
9
10
  MAX_ROWS = 200000
@@ -138,15 +139,53 @@ def _row_fields(row):
138
139
  return {k: row[k] for k in ("start", "size", "name") if k in row}
139
140
 
140
141
 
141
- def _row_starts(image, rows, starts, domains, seen, contested, routine_of):
142
- """Each row whose start lies inside an instruction the entry-path walk established, and counts of the rest.
142
+ def _routine_fields(image, starts, routine, prefix=""):
143
+ """The ``routine``, ``routineAddress`` and ``routineIsRow`` fields for a routine start, or none when it is None.
144
+
145
+ A ``prefix`` names the fields after it, as ``rowStartRoutine`` for ``prefix="rowStart"``.
146
+ """
147
+ if routine is None:
148
+ return {}
149
+ place = _target_place(image, routine)
150
+ name = prefix + "Routine" if prefix else "routine"
151
+ return {name: routine, name + "Address": place[2], name + "IsRow": place[:2] in starts}
152
+
153
+
154
+ def _overlaps(image, starts, at, decoded, routine_of):
155
+ """Every instruction in ``decoded`` other than the one at ``at`` whose bytes meet the bytes of the
156
+ instruction at ``at``, or the byte ``at`` when no instruction starts there, with its evidence.
157
+
158
+ ``decoded`` maps a site to ``(instruction, evidence)``.
159
+ """
160
+ end = at + decoded[at][0].size if at in decoded else at + 1
161
+ found = []
162
+ # An x86 instruction is at most 15 bytes, so only the starts just before the site can reach into it.
163
+ for site in range(max(at - 14, 0), end):
164
+ if site == at or site not in decoded or site + decoded[site][0].size <= at:
165
+ continue
166
+ ins, evidence = decoded[site]
167
+ found.append({"site": site, "address": _target_place(image, site)[2], "size": ins.size, "text": _text(ins),
168
+ "evidence": evidence, **_routine_fields(image, starts, routine_of(site))})
169
+ return found
170
+
171
+
172
+ def _row_starts(image, rows, starts, domains, seen, contested, unresolved, routine_of):
173
+ """Each row whose start lies inside an instruction the entry-path walk established, or at or inside
174
+ an instruction of an overlap the walk left unresolved, and counts of the rest.
143
175
 
144
176
  A start is checked against the walk's instructions only; bytes the walk did not decode are not
145
- decoded here, so a row start in them is counted as not read rather than placed. A start at or
146
- inside an instruction the walk decoded but rejected as contested is counted as contested.
177
+ decoded here, so a row start in them is counted as not read rather than placed. ``unresolved``
178
+ holds the instructions at the walk's overlap gaps, which it decoded on the entry path and
179
+ rejected because no boundary between them is proven. A row start at or inside one is listed with
180
+ every instruction it overlaps, since the row's own entry can be one side of the overlap. A start
181
+ at or inside an instruction the walk decoded but rejected as contested is counted as contested.
147
182
  """
148
183
  found, counts = [], {"instructionStarts": 0, "insideAnInstruction": 0, "overlappingInstructionStarts": 0,
149
- "contested": 0, "notRead": 0}
184
+ "unresolvedOverlaps": 0, "contested": 0, "notRead": 0}
185
+ # Every instruction the walk decoded, with its evidence. Only a row start at an unresolved overlap reads it.
186
+ decoded = ({at: (ins, CONTESTED_REASON) for at, ins in contested.items()}
187
+ | {at: (ins, OVERLAP_REASON) for at, ins in unresolved.items()}
188
+ | {at: (ins, "entry-path instruction") for at, ins in seen.items()}) if unresolved else {}
150
189
  for row in rows:
151
190
  offsets = _offsets(image, domains, row["space"], row["at"])
152
191
  if not offsets:
@@ -155,6 +194,25 @@ def _row_starts(image, rows, starts, domains, seen, contested, routine_of):
155
194
  if held is None:
156
195
  if any(at in seen for at in offsets):
157
196
  counts["instructionStarts"] += 1
197
+ continue
198
+ hit = next(((at, holder) for at in offsets for holder in [holding_instruction(unresolved, at)]
199
+ if at in unresolved or holder is not None), None)
200
+ if hit is not None:
201
+ at, holder = hit
202
+ counts["unresolvedOverlaps"] += 1
203
+ entry = {**_row_fields(row), "site": at}
204
+ if at in unresolved:
205
+ entry |= {"status": "start of an unresolved overlapping instruction",
206
+ "rowStartInstructionSize": unresolved[at].size, "rowStartInstructionText": _text(unresolved[at]),
207
+ **_routine_fields(image, starts, routine_of(at), "rowStart")}
208
+ else:
209
+ entry["status"] = "inside an unresolved overlapping instruction"
210
+ if holder is not None:
211
+ entry |= {"insideInstruction": holder, "insideInstructionAddress": _target_place(image, holder)[2],
212
+ "insideInstructionSize": unresolved[holder].size,
213
+ "insideInstructionText": _text(unresolved[holder]),
214
+ **_routine_fields(image, starts, routine_of(holder))}
215
+ found.append(entry | {"overlaps": _overlaps(image, starts, at, decoded, routine_of)})
158
216
  elif any(at in contested or holding_instruction(contested, at) is not None for at in offsets):
159
217
  counts["contested"] += 1
160
218
  else:
@@ -163,17 +221,14 @@ def _row_starts(image, rows, starts, domains, seen, contested, routine_of):
163
221
  at, holder = held
164
222
  overlapping = at in seen
165
223
  counts["overlappingInstructionStarts" if overlapping else "insideAnInstruction"] += 1
166
- routine = routine_of(holder)
167
224
  entry = {**_row_fields(row), "site": at,
168
225
  "status": "start of an overlapping instruction" if overlapping else "inside an instruction",
169
226
  "insideInstruction": holder, "insideInstructionAddress": _target_place(image, holder)[2],
170
227
  "insideInstructionSize": seen[holder].size, "insideInstructionText": _text(seen[holder])}
171
228
  if overlapping:
172
- entry |= {"rowStartInstructionSize": seen[at].size, "rowStartInstructionText": _text(seen[at])}
173
- if routine is not None:
174
- place = _target_place(image, routine)
175
- entry |= {"routine": routine, "routineAddress": place[2], "routineIsRow": place[:2] in starts}
176
- found.append(entry)
229
+ entry |= {"rowStartInstructionSize": seen[at].size, "rowStartInstructionText": _text(seen[at]),
230
+ **_routine_fields(image, starts, routine_of(at), "rowStart")}
231
+ found.append(entry | _routine_fields(image, starts, routine_of(holder)))
177
232
  return found, counts
178
233
 
179
234
 
@@ -211,10 +266,12 @@ def inventory_check(image, config):
211
266
  the first of an instruction the entry-path walk established names that instruction.
212
267
 
213
268
  The rows are checked against the same walk: each row whose start lies inside an instruction the
214
- walk established is listed in ``rowStarts``. ``noReturn`` declarations, in ``reach``'s shape, end
269
+ walk established, or at or inside an instruction of an overlap the walk left unresolved, is listed
270
+ in ``rowStarts``. ``noReturn`` declarations, in ``reach``'s shape, end
215
271
  the walk at a call to a declared routine and at a declared interrupt site, are checked for a
216
272
  return on the routine's own paths, and list in ``rowsPastNoReturn`` each row whose body
217
- continues past such a call or interrupt.
273
+ continues past such a call or interrupt. ``indirectCalls`` declarations, in ``reach``'s shape,
274
+ make each declared target of a reached computed call a call target, and the walk reads on in them.
218
275
  """
219
276
  from .reports import call_controls, direct_calls, entries, search_coverage
220
277
  from .reach import no_return_declarations, no_return_rows, successor_graph, fewest_calls
@@ -223,8 +280,19 @@ def inventory_check(image, config):
223
280
  rows = read_inventory(config["inventory"], image)
224
281
  limit = integer(config.get("limit", 1000), 1, 10000, "result limit")
225
282
  no_return_routines, no_return_interrupts = no_return_declarations(config.get("noReturn", []), image)
226
- declared = {"no_return_calls": frozenset(no_return_routines), "no_return_interrupts": frozenset(no_return_interrupts)}
283
+ indirect_calls = indirect_call_declarations(config.get("indirectCalls", []), image)
284
+ for at in config.get("controls", []) if isinstance(config.get("controls"), list) else []:
285
+ # call_controls refuses a control that is no integer.
286
+ if type(at) is int and at in indirect_calls:
287
+ raise ValueError(f"Positive control {at} is a declared indirect call, whose targets rest on its "
288
+ "declaration; a control must resolve from its own encoding")
289
+ declared = {"no_return_calls": frozenset(no_return_routines), "no_return_interrupts": frozenset(no_return_interrupts),
290
+ "indirect_calls": indirect_calls}
227
291
  calls = direct_calls(image, config, **declared)
292
+
293
+ def ends_branch(row):
294
+ # A declared indirect call ends its branch only when every target it may call is declared noReturn.
295
+ return call_ends(row["site"], row["target"], indirect_calls, no_return_routines)
228
296
  seen, contested = calls["seen"], calls["contested"]
229
297
 
230
298
  starts = {(row["space"], row["at"]) for row in rows}
@@ -297,31 +365,45 @@ def inventory_check(image, config):
297
365
  entry["rows"] = [_row_fields(rows[i]) for i in held]
298
366
  missing.append(entry)
299
367
 
368
+ # The instructions of the overlaps the walk left unresolved. The walk decoded each at its gap site.
369
+ overlapping = {g["site"]: image.decode(g["site"]) for g in calls["gaps"] if g.get("reason") == OVERLAP_REASON}
370
+
300
371
  # The routine the walk read an instruction in, by the route with the fewest calls, as reach names it.
372
+ # An unresolved instruction is a node that ends its route, so it gets the routine of the established
373
+ # instruction that steps into it, or its own when it is an entry, and no route passes through it.
301
374
  # The graph is built only when a row start needs it.
302
375
  routines = None
303
376
 
304
377
  def routine_of(site):
305
378
  nonlocal routines
306
379
  if routines is None:
307
- graph = successor_graph(image, seen, **declared)
308
- routines = fewest_calls(graph, [at for at in entries(image) if at in seen])[2]
380
+ graph = successor_graph(image, seen | overlapping, **declared)
381
+ graph = {at: [] if at in overlapping else successors for at, successors in graph.items()}
382
+ routines = fewest_calls(graph, [at for at in entries(image) if at in seen or at in overlapping])[2]
309
383
  return routines.get(site)
310
- row_starts, start_counts = _row_starts(image, rows, starts, domains, seen, contested, routine_of)
384
+ row_starts, start_counts = _row_starts(image, rows, starts, domains, seen, contested, overlapping, routine_of)
311
385
 
312
386
  # Each declaration with the calls it kept from their return sites, as reach reports them.
313
387
  returns, check_read, check_stopped = _no_return_check(image, no_return_routines, declared,
314
388
  config.get("instructionLimit", 10000))
315
389
  entry_calls = {}
316
390
  for row in calls["rows"]:
317
- if row["target"] in no_return_routines and row["site"] in seen:
391
+ if row["target"] in no_return_routines and row["site"] in seen and ends_branch(row):
318
392
  entry_calls.setdefault(row["target"], []).append(row["site"])
319
393
  no_return = no_return_rows(no_return_routines, no_return_interrupts, returns,
320
394
  {at: sorted(sites) for at, sites in entry_calls.items()}, seen, seen, check_read)
321
395
 
322
396
  # A row whose body holds a declared call or interrupt and the byte after it still covers what follows.
323
- ends = [(row["site"], image.decode(row["site"]).size, "call", row["target"], row["classification"])
324
- for row in calls["rows"] if row["target"] in no_return_routines]
397
+ # A declared computed call has one row for each target, and is listed once with all of them.
398
+ ends, declared_ends = [], set()
399
+ for row in calls["rows"]:
400
+ if row["target"] not in no_return_routines or not ends_branch(row) or row["site"] in declared_ends:
401
+ continue
402
+ routine = row["target"]
403
+ if row["site"] in indirect_calls:
404
+ declared_ends.add(row["site"])
405
+ routine = list(indirect_calls[row["site"]]["targets"])
406
+ ends.append((row["site"], image.decode(row["site"]).size, "call", routine, row["classification"]))
325
407
  ends += [(at, row["following"] - at, "interrupt", None,
326
408
  "entry-path instruction" if at in seen else CONTESTED_REASON if at in contested else "declared site")
327
409
  for at, row in no_return_interrupts.items()]
@@ -338,7 +420,9 @@ def inventory_check(image, config):
338
420
  continue
339
421
  entry = {**_row_fields(rows[i]), "kind": kind, "site": site, "siteAddress": here[2],
340
422
  "siteClassification": classification}
341
- if routine is not None:
423
+ if isinstance(routine, list):
424
+ entry["routines"] = routine
425
+ elif routine is not None:
342
426
  entry["routine"] = routine
343
427
  past.append(entry | {"following": site + size, "followingAddress": after[2],
344
428
  "followingRead": site + size in seen, "bytesAfter": piece[1] - after[1]})
@@ -389,6 +473,12 @@ def inventory_check(image, config):
389
473
  summary += (f", {start_counts['overlappingInstructionStarts']} of them at the start of an overlapping "
390
474
  "instruction it also established")
391
475
  summary += "."
476
+ if start_counts["unresolvedOverlaps"]:
477
+ summary += " " + _count(start_counts["unresolvedOverlaps"],
478
+ "row start lies at or inside an instruction of an overlap the walk left unresolved, "
479
+ "listed with the instructions it overlaps.",
480
+ "row starts lie at or inside an instruction of an overlap the walk left unresolved, "
481
+ "each listed with the instructions it overlaps.")
392
482
  if start_counts["notRead"]:
393
483
  summary += " " + _count(start_counts["notRead"], "row start in declared code lies", "row starts in declared code lie") \
394
484
  + " in bytes where the walk established no instruction, so its boundary is not checked."
@@ -420,10 +510,15 @@ def inventory_check(image, config):
420
510
  + "; interrupt handlers are not read")
421
511
  if no_return:
422
512
  assumptions.append("each noReturn routine and interrupt never returns, for the reason it gives")
513
+ if indirect_calls:
514
+ assumptions.append("each declared indirect call can call the targets its declaration gives, for the evidence "
515
+ "it gives, and only those when it is declared exhaustive")
516
+ indirect_rows = [declaration | {"reached": site in seen} for site, declaration in indirect_calls.items()]
423
517
  return {"inventory": {"path": config["inventory"], "rows": len(rows)},
424
518
  "targets": missing[:limit], "unresolved": unresolved[:limit],
425
519
  "rowsOutsideDeclaredCode": outside_code[:limit],
426
520
  "rowStarts": row_starts[:limit], "noReturn": no_return, "rowsPastNoReturn": past[:limit],
521
+ "indirectCalls": indirect_rows,
427
522
  "counts": {"callTargets": len(by_target), **tally, "unresolvedCalls": len(unresolved),
428
523
  "inventoryRows": len(rows), "rowsOutsideDeclaredCode": len(outside_code),
429
524
  "rowStarts": start_counts, "rowsPastNoReturn": len(past_rows),
@@ -434,15 +529,17 @@ def inventory_check(image, config):
434
529
  "summary": summary, "controls": controls,
435
530
  "searched": [r for r in image.regions if r["name"] in calls["scans"]], "coverage": coverage,
436
531
  "partialSearch": partial, "gaps": calls["gaps"],
437
- "exclusions": ["computed call targets (listed in unresolved when the walk reaches them)", "unrelocated far calls",
532
+ "exclusions": ["computed call targets no indirectCalls declaration gives (listed in unresolved when the "
533
+ "walk reaches them)", "unrelocated far calls",
438
534
  "undeclared mappings", "prefix-started raw candidates off the entry path", "jump targets"],
439
535
  "interpretation": "Each distinct resolved direct call target in the searched regions, placed in the inventory's "
440
536
  "notation and compared with its rows. A target only raw byte candidates or contested "
441
537
  "instructions call is not shown to be code. The counts are lower bounds on the targets "
442
538
  "the inventory lacks: calls the search does not resolve can add more. Row starts are "
443
- "compared only with the instructions the entry-path walk established; a start where it "
444
- "established no instruction is counted as notRead or contested and not placed, so linear decoding past data "
445
- "never reports one. A start inside an instruction can be deliberately overlapping code, "
539
+ "compared only with the instructions the entry-path walk decoded; a start at or inside an instruction "
540
+ "of an overlap the walk left unresolved is listed with every instruction it overlaps, and a "
541
+ "start where it established no instruction is counted as notRead or contested and not placed, "
542
+ "so linear decoding past data never reports one. A start inside an instruction can be deliberately overlapping code, "
446
543
  "which the row names with both instructions for a reader to judge. rowsPastNoReturn rests "
447
544
  "on the noReturn declarations: followingRead says whether the walk reached the bytes after "
448
545
  "the call by another route, only a site the walk established counts a row, and an empty "