scientific-method-engine 18.3.0__tar.gz → 18.4.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.
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/PKG-INFO +1 -1
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/pyproject.toml +1 -1
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/cli.py +3 -0
- scientific_method_engine-18.4.0/src/scientific_method_engine/x86/dispatch.py +168 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/inventory.py +36 -7
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/reach.py +60 -27
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/reports.py +21 -4
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/trace.py +26 -6
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_inventory_check.py +43 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_reach.py +174 -0
- scientific_method_engine-18.3.0/src/scientific_method_engine/x86/dispatch.py +0 -51
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/.gitignore +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/LICENSE +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/README.md +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/__init__.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/__main__.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportRangeBoundaries.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/ghidra/scientificmethod/Xxh3.java +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/__init__.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/image.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/loops.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/machine.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/pcode.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/pe.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/relational.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/src/scientific_method_engine/x86/values.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/oracle.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_config_encoding.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_continuation_budget.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_dispatch.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_effect_order.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_enter_frames.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_entry_frame.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_indirect_far_transfers.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_interrupt_models.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_join_terms.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_loops.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_memory_scopes.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_nested_frame_request.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_oracle.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_pe.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_relational_controls.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_return_checks.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_successor_rule.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_table_continuations.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_term_limit.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_upstream_gaps.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.0}/tests/test_volatile_memory.py +0 -0
- {scientific_method_engine-18.3.0 → scientific_method_engine-18.4.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
|
+
Version: 18.4.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.
|
|
8
|
+
version = "18.4.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"
|
|
@@ -38,6 +40,7 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
|
|
|
38
40
|
"noReturn takes reach's declarations: the walk stops at a call to a declared routine and at a declared\n"
|
|
39
41
|
"interrupt, a declared routine with a return on its own read paths is reported contradicted, and\n"
|
|
40
42
|
"rowsPastNoReturn lists each row whose body continues past such a call or interrupt.\n"
|
|
43
|
+
"indirectCalls takes reach's declarations: each declared target of a reached computed call is a call target.\n"
|
|
41
44
|
"uses matches accesses whose footprint intersects query offset..offset+width; its rawCandidates give each unreached\n"
|
|
42
45
|
"operand's encoded displacement, width, access, segment register and intersection, and never count as uses.\n"
|
|
43
46
|
"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
|
|
@@ -4,6 +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, 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
|
|
@@ -214,7 +215,8 @@ def inventory_check(image, config):
|
|
|
214
215
|
walk established is listed in ``rowStarts``. ``noReturn`` declarations, in ``reach``'s shape, end
|
|
215
216
|
the walk at a call to a declared routine and at a declared interrupt site, are checked for a
|
|
216
217
|
return on the routine's own paths, and list in ``rowsPastNoReturn`` each row whose body
|
|
217
|
-
continues past such a call or interrupt.
|
|
218
|
+
continues past such a call or interrupt. ``indirectCalls`` declarations, in ``reach``'s shape,
|
|
219
|
+
make each declared target of a reached computed call a call target, and the walk reads on in them.
|
|
218
220
|
"""
|
|
219
221
|
from .reports import call_controls, direct_calls, entries, search_coverage
|
|
220
222
|
from .reach import no_return_declarations, no_return_rows, successor_graph, fewest_calls
|
|
@@ -223,8 +225,19 @@ def inventory_check(image, config):
|
|
|
223
225
|
rows = read_inventory(config["inventory"], image)
|
|
224
226
|
limit = integer(config.get("limit", 1000), 1, 10000, "result limit")
|
|
225
227
|
no_return_routines, no_return_interrupts = no_return_declarations(config.get("noReturn", []), image)
|
|
226
|
-
|
|
228
|
+
indirect_calls = indirect_call_declarations(config.get("indirectCalls", []), image)
|
|
229
|
+
for at in config.get("controls", []) if isinstance(config.get("controls"), list) else []:
|
|
230
|
+
# call_controls refuses a control that is no integer.
|
|
231
|
+
if type(at) is int and at in indirect_calls:
|
|
232
|
+
raise ValueError(f"Positive control {at} is a declared indirect call, whose targets rest on its "
|
|
233
|
+
"declaration; a control must resolve from its own encoding")
|
|
234
|
+
declared = {"no_return_calls": frozenset(no_return_routines), "no_return_interrupts": frozenset(no_return_interrupts),
|
|
235
|
+
"indirect_calls": indirect_calls}
|
|
227
236
|
calls = direct_calls(image, config, **declared)
|
|
237
|
+
|
|
238
|
+
def ends_branch(row):
|
|
239
|
+
# A declared indirect call ends its branch only when every target it may call is declared noReturn.
|
|
240
|
+
return call_ends(row["site"], row["target"], indirect_calls, no_return_routines)
|
|
228
241
|
seen, contested = calls["seen"], calls["contested"]
|
|
229
242
|
|
|
230
243
|
starts = {(row["space"], row["at"]) for row in rows}
|
|
@@ -314,14 +327,22 @@ def inventory_check(image, config):
|
|
|
314
327
|
config.get("instructionLimit", 10000))
|
|
315
328
|
entry_calls = {}
|
|
316
329
|
for row in calls["rows"]:
|
|
317
|
-
if row["target"] in no_return_routines and row["site"] in seen:
|
|
330
|
+
if row["target"] in no_return_routines and row["site"] in seen and ends_branch(row):
|
|
318
331
|
entry_calls.setdefault(row["target"], []).append(row["site"])
|
|
319
332
|
no_return = no_return_rows(no_return_routines, no_return_interrupts, returns,
|
|
320
333
|
{at: sorted(sites) for at, sites in entry_calls.items()}, seen, seen, check_read)
|
|
321
334
|
|
|
322
335
|
# A row whose body holds a declared call or interrupt and the byte after it still covers what follows.
|
|
323
|
-
|
|
324
|
-
|
|
336
|
+
# A declared computed call has one row for each target, and is listed once with all of them.
|
|
337
|
+
ends, declared_ends = [], set()
|
|
338
|
+
for row in calls["rows"]:
|
|
339
|
+
if row["target"] not in no_return_routines or not ends_branch(row) or row["site"] in declared_ends:
|
|
340
|
+
continue
|
|
341
|
+
routine = row["target"]
|
|
342
|
+
if row["site"] in indirect_calls:
|
|
343
|
+
declared_ends.add(row["site"])
|
|
344
|
+
routine = list(indirect_calls[row["site"]]["targets"])
|
|
345
|
+
ends.append((row["site"], image.decode(row["site"]).size, "call", routine, row["classification"]))
|
|
325
346
|
ends += [(at, row["following"] - at, "interrupt", None,
|
|
326
347
|
"entry-path instruction" if at in seen else CONTESTED_REASON if at in contested else "declared site")
|
|
327
348
|
for at, row in no_return_interrupts.items()]
|
|
@@ -338,7 +359,9 @@ def inventory_check(image, config):
|
|
|
338
359
|
continue
|
|
339
360
|
entry = {**_row_fields(rows[i]), "kind": kind, "site": site, "siteAddress": here[2],
|
|
340
361
|
"siteClassification": classification}
|
|
341
|
-
if routine
|
|
362
|
+
if isinstance(routine, list):
|
|
363
|
+
entry["routines"] = routine
|
|
364
|
+
elif routine is not None:
|
|
342
365
|
entry["routine"] = routine
|
|
343
366
|
past.append(entry | {"following": site + size, "followingAddress": after[2],
|
|
344
367
|
"followingRead": site + size in seen, "bytesAfter": piece[1] - after[1]})
|
|
@@ -420,10 +443,15 @@ def inventory_check(image, config):
|
|
|
420
443
|
+ "; interrupt handlers are not read")
|
|
421
444
|
if no_return:
|
|
422
445
|
assumptions.append("each noReturn routine and interrupt never returns, for the reason it gives")
|
|
446
|
+
if indirect_calls:
|
|
447
|
+
assumptions.append("each declared indirect call can call the targets its declaration gives, for the evidence "
|
|
448
|
+
"it gives, and only those when it is declared exhaustive")
|
|
449
|
+
indirect_rows = [declaration | {"reached": site in seen} for site, declaration in indirect_calls.items()]
|
|
423
450
|
return {"inventory": {"path": config["inventory"], "rows": len(rows)},
|
|
424
451
|
"targets": missing[:limit], "unresolved": unresolved[:limit],
|
|
425
452
|
"rowsOutsideDeclaredCode": outside_code[:limit],
|
|
426
453
|
"rowStarts": row_starts[:limit], "noReturn": no_return, "rowsPastNoReturn": past[:limit],
|
|
454
|
+
"indirectCalls": indirect_rows,
|
|
427
455
|
"counts": {"callTargets": len(by_target), **tally, "unresolvedCalls": len(unresolved),
|
|
428
456
|
"inventoryRows": len(rows), "rowsOutsideDeclaredCode": len(outside_code),
|
|
429
457
|
"rowStarts": start_counts, "rowsPastNoReturn": len(past_rows),
|
|
@@ -434,7 +462,8 @@ def inventory_check(image, config):
|
|
|
434
462
|
"summary": summary, "controls": controls,
|
|
435
463
|
"searched": [r for r in image.regions if r["name"] in calls["scans"]], "coverage": coverage,
|
|
436
464
|
"partialSearch": partial, "gaps": calls["gaps"],
|
|
437
|
-
"exclusions": ["computed call targets (listed in unresolved when the
|
|
465
|
+
"exclusions": ["computed call targets no indirectCalls declaration gives (listed in unresolved when the "
|
|
466
|
+
"walk reaches them)", "unrelocated far calls",
|
|
438
467
|
"undeclared mappings", "prefix-started raw candidates off the entry path", "jump targets"],
|
|
439
468
|
"interpretation": "Each distinct resolved direct call target in the searched regions, placed in the inventory's "
|
|
440
469
|
"notation and compared with its rows. A target only raw byte candidates or contested "
|
|
@@ -4,6 +4,7 @@ from .image import integer
|
|
|
4
4
|
from .trace import (walk, cfg_step, base_mnemonic, unsupported_transfer, holding_instruction, INTERRUPTS, RETURNS,
|
|
5
5
|
LIMIT_REASON, OVERLAP_REASON, UNDECODED_REASON)
|
|
6
6
|
from .pcode_backend import interrupt_vector
|
|
7
|
+
from .dispatch import indirect_call_declarations, call_ends
|
|
7
8
|
|
|
8
9
|
# The virtual root of the dominator computation; no file offset is negative.
|
|
9
10
|
ROOT = -1
|
|
@@ -102,15 +103,16 @@ def returns_from(graph, seen, returning_leaves, routine):
|
|
|
102
103
|
def successor_kinds(at, ins, step):
|
|
103
104
|
"""Each successor of ``step`` with how the CFG reaches it: call, return, table, interrupt, jump or fall."""
|
|
104
105
|
m, following = base_mnemonic(ins), at + ins.size
|
|
106
|
+
# A call lists its resolved or declared targets first, then its return site; a call to the next
|
|
107
|
+
# instruction lists that site twice.
|
|
105
108
|
targets = {e["target"] for e in step.edges if e["target"] is not None}
|
|
106
|
-
|
|
109
|
+
calls = sum(e["target"] is not None for e in step.edges) if m in CALLS else 0
|
|
110
|
+
rows = []
|
|
107
111
|
for successor in step.successors:
|
|
108
|
-
if
|
|
112
|
+
if m in CALLS:
|
|
113
|
+
kind = "call" if len(rows) < calls else "return"
|
|
114
|
+
elif step.supplied:
|
|
109
115
|
kind = "table"
|
|
110
|
-
elif m in CALLS:
|
|
111
|
-
# A call names its target first; a call to the next instruction lists that site twice.
|
|
112
|
-
kind = "call" if successor in targets and not called else "return"
|
|
113
|
-
called = called or kind == "call"
|
|
114
116
|
elif m in INTERRUPTS:
|
|
115
117
|
kind = "interrupt"
|
|
116
118
|
elif successor == following and m not in ("jmp", "ljmp") and (successor not in targets or len(rows) > 0):
|
|
@@ -202,11 +204,12 @@ def reach(image, config):
|
|
|
202
204
|
|
|
203
205
|
The walk decodes from ``starts`` (established region entries) and follows every resolved call
|
|
204
206
|
into its callee and on at its return site, every resolved jump and branch, the rows of a
|
|
205
|
-
declared indirect jump table,
|
|
206
|
-
is reached but never decoded. A call to a
|
|
207
|
-
do not continue at the next instruction
|
|
208
|
-
|
|
209
|
-
|
|
207
|
+
declared indirect jump table, the declared targets of an ``indirectCalls`` site, and every
|
|
208
|
+
interrupt to the next instruction. A ``leaves`` routine is reached but never decoded. A call to a
|
|
209
|
+
``noReturn`` routine and a ``noReturn`` interrupt site do not continue at the next instruction,
|
|
210
|
+
nor does a declared indirect call that is exhaustive and whose targets are all ``noReturn``.
|
|
211
|
+
Each reached target gets one chain with the fewest calls, the assumptions its route rests on,
|
|
212
|
+
and the routines on every route to it within the read graph.
|
|
210
213
|
"""
|
|
211
214
|
from .reports import entries
|
|
212
215
|
starts = _sites(config.get("starts"), "starts", image)
|
|
@@ -218,6 +221,12 @@ def reach(image, config):
|
|
|
218
221
|
leaves = _leaves(config.get("leaves", []), image, set(starts))
|
|
219
222
|
controls = _sites(config.get("controls", []), "controls", image, least=0)
|
|
220
223
|
instruction_controls = _sites(config.get("instructionControls", []), "instructionControls", image, least=0)
|
|
224
|
+
indirect_calls = indirect_call_declarations(config.get("indirectCalls", []), image)
|
|
225
|
+
# A control shows that the walk resolved a call from its own encoding, which a declaration does not.
|
|
226
|
+
for at in controls:
|
|
227
|
+
if at in indirect_calls:
|
|
228
|
+
raise ValueError(f"control {at} is a declared indirect call, whose targets rest on its declaration; give "
|
|
229
|
+
"the site as an instructionControls entry, or a call inside a declared target as a control")
|
|
221
230
|
# The walk decodes a site as image.decode does, so a control whose bytes are no call can never pass.
|
|
222
231
|
for at in controls:
|
|
223
232
|
ins = image.decode(at)
|
|
@@ -233,11 +242,13 @@ def reach(image, config):
|
|
|
233
242
|
limit = integer(config.get("limit", 1000), 1, 10000, "result limit")
|
|
234
243
|
instruction_limit = config.get("instructionLimit", 10000)
|
|
235
244
|
no_return_routines, no_return_interrupts = no_return_declarations(config.get("noReturn", []), image)
|
|
236
|
-
declared = {"no_return_calls": frozenset(no_return_routines), "no_return_interrupts": frozenset(no_return_interrupts)
|
|
245
|
+
declared = {"no_return_calls": frozenset(no_return_routines), "no_return_interrupts": frozenset(no_return_interrupts),
|
|
246
|
+
"indirect_calls": indirect_calls}
|
|
237
247
|
seen, walk_gaps, _, _, contested = walk(image, starts, instruction_limit, follow_interrupts=True,
|
|
238
248
|
stops=frozenset(leaves), **declared)
|
|
239
249
|
|
|
240
|
-
|
|
250
|
+
# Each reached call site with its resolved or declared targets.
|
|
251
|
+
graph, unresolved, interrupts, call_targets = {}, [], [], {}
|
|
241
252
|
for at, ins in sorted(seen.items()):
|
|
242
253
|
step = cfg_step(image, at, ins, follow_interrupts=True, **declared)
|
|
243
254
|
graph[at] = [(s, kind) for s, kind in successor_kinds(at, ins, step) if s in seen or s in leaves]
|
|
@@ -251,7 +262,7 @@ def reach(image, config):
|
|
|
251
262
|
unresolved.append({"site": at, "instruction": text, "kind": kind,
|
|
252
263
|
"reason": edge["provenance"].get("reason", "target outside declared regions")})
|
|
253
264
|
elif m in CALLS:
|
|
254
|
-
|
|
265
|
+
call_targets.setdefault(at, []).append(edge["target"])
|
|
255
266
|
if m in INTERRUPTS and at not in no_return_interrupts:
|
|
256
267
|
vector, conditional = interrupt_vector(image.flat, ins, at)
|
|
257
268
|
interrupts.append({"site": at, "instruction": text, "vector": vector, "conditional": conditional})
|
|
@@ -278,15 +289,17 @@ def reach(image, config):
|
|
|
278
289
|
for child in successors[node]:
|
|
279
290
|
predecessors[child].append(node)
|
|
280
291
|
idom = _dominators(order, predecessors)
|
|
281
|
-
routine_starts = set(starts) | {target for
|
|
292
|
+
routine_starts = set(starts) | {target for found in call_targets.values() for target in found if target in distance}
|
|
282
293
|
|
|
283
294
|
def chain(target):
|
|
284
|
-
hops, assumed_returns, tables, continued = [], [], [], []
|
|
295
|
+
hops, assumed_returns, tables, declared_calls, continued = [], [], [], [], []
|
|
285
296
|
at = target
|
|
286
297
|
while parent[at] is not None:
|
|
287
298
|
previous, kind = parent[at]
|
|
288
299
|
if kind == "call":
|
|
289
300
|
hops.append({"callSite": previous, "routine": at})
|
|
301
|
+
if previous in indirect_calls:
|
|
302
|
+
declared_calls.append({"site": previous, "target": at})
|
|
290
303
|
elif kind == "return":
|
|
291
304
|
assumed_returns.append(previous)
|
|
292
305
|
elif kind == "table":
|
|
@@ -297,7 +310,7 @@ def reach(image, config):
|
|
|
297
310
|
hops.append({"routine": at})
|
|
298
311
|
return {"chain": hops[::-1], "calls": distance[target],
|
|
299
312
|
"route": {"assumedReturns": assumed_returns[::-1], "declaredTableJumps": tables[::-1],
|
|
300
|
-
"interruptsContinued": continued[::-1]}}
|
|
313
|
+
"declaredCalls": declared_calls[::-1], "interruptsContinued": continued[::-1]}}
|
|
301
314
|
|
|
302
315
|
# The walk decodes both instructions of an unresolved overlap and keeps neither, so their starts are not in seen.
|
|
303
316
|
overlapping = {g["site"] for g in walk_gaps if g["reason"] == OVERLAP_REASON}
|
|
@@ -337,13 +350,16 @@ def reach(image, config):
|
|
|
337
350
|
# Kept apart from the gap rows, which the result limit can cut.
|
|
338
351
|
stopped = any(g["reason"] == LIMIT_REASON for g in walk_gaps)
|
|
339
352
|
# A control at a site a noReturn declaration kept the walk from names that declaration, which may be the cause.
|
|
340
|
-
|
|
341
|
-
|
|
353
|
+
def ends(at, found):
|
|
354
|
+
return call_ends(at, found[0], indirect_calls, no_return_routines)
|
|
355
|
+
cut_by = {at + seen[at].size: f"the call at {at} to noReturn routine{'s' if len(found) > 1 else ''} "
|
|
356
|
+
+ ", ".join(map(str, found))
|
|
357
|
+
for at, found in sorted(call_targets.items()) if ends(at, found)}
|
|
342
358
|
cut_by |= {row["following"]: f"the noReturn interrupt at {at}"
|
|
343
359
|
for at, row in no_return_interrupts.items() if at in seen}
|
|
344
360
|
# Not reached and reached-but-unresolved need different fixes, so each failure says which it is.
|
|
345
361
|
failures = []
|
|
346
|
-
for label, sites, passed in (("control", controls,
|
|
362
|
+
for label, sites, passed in (("control", controls, call_targets), ("instruction control", instruction_controls, seen)):
|
|
347
363
|
for at in sites:
|
|
348
364
|
if at in passed:
|
|
349
365
|
continue
|
|
@@ -363,16 +379,27 @@ def reach(image, config):
|
|
|
363
379
|
+ (" (the walk stopped at its instruction limit)" if stopped else ""))
|
|
364
380
|
if failures:
|
|
365
381
|
raise ValueError("Positive controls failed: " + "; ".join(failures))
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
382
|
+
# Every call to each routine, and the calls to a noReturn routine that the declaration ended.
|
|
383
|
+
call_sites, ended_sites = {}, {}
|
|
384
|
+
for site, found in sorted(call_targets.items()):
|
|
385
|
+
ended = ends(site, found)
|
|
386
|
+
for target in found:
|
|
387
|
+
call_sites.setdefault(target, []).append(site)
|
|
388
|
+
if ended:
|
|
389
|
+
ended_sites.setdefault(target, []).append(site)
|
|
369
390
|
leaf_rows = [{"routine": at, "reason": reason, "reached": at in distance, "callSites": call_sites.get(at, [])}
|
|
370
391
|
for at, reason in leaves.items()]
|
|
371
392
|
# Each call the declaration kept from its return site, so a reviewer can check what follows it.
|
|
372
393
|
returning_leaves = set(leaves) - set(no_return_routines)
|
|
373
394
|
returns = {at: returns_from(graph, seen, returning_leaves, at) for at in no_return_routines}
|
|
374
|
-
no_return = no_return_rows(no_return_routines, no_return_interrupts, returns,
|
|
395
|
+
no_return = no_return_rows(no_return_routines, no_return_interrupts, returns, ended_sites, seen, distance, seen)
|
|
375
396
|
contradicted = any(row.get("contradicted") for row in no_return)
|
|
397
|
+
# A declared target the walk entered but established no instruction at shows in gaps or contested too,
|
|
398
|
+
# unless the walk stopped at its instruction limit before reading it.
|
|
399
|
+
indirect_rows = [declaration | {"reached": site in seen, "routine": routine.get(site),
|
|
400
|
+
"unreadTargets": [t for t in declaration["targets"]
|
|
401
|
+
if site in seen and t not in seen and t not in leaves]}
|
|
402
|
+
for site, declaration in indirect_calls.items()]
|
|
376
403
|
counts = {"routines": len(routine_starts), "instructions": len(seen), "unresolved": len(unresolved),
|
|
377
404
|
"interrupts": len(interrupts), "gaps": len(gaps), "contested": len(contested)}
|
|
378
405
|
assumptions = ["each reached call returns to its next instruction"
|
|
@@ -382,21 +409,24 @@ def reach(image, config):
|
|
|
382
409
|
+ "; interrupt handlers are not read",
|
|
383
410
|
"each leaf calls nothing, for the reason it gives",
|
|
384
411
|
"each declared indirect jump table holds the routes its declaration gives"]
|
|
412
|
+
if indirect_calls:
|
|
413
|
+
assumptions.append("each declared indirect call can call the targets its declaration gives, for the evidence "
|
|
414
|
+
"it gives, and only those when it is declared exhaustive")
|
|
385
415
|
if no_return:
|
|
386
416
|
assumptions.append("each noReturn routine and interrupt never returns, for the reason it gives")
|
|
387
|
-
return {"starts": starts, "targets": rows, "leaves": leaf_rows, "noReturn": no_return,
|
|
417
|
+
return {"starts": starts, "targets": rows, "leaves": leaf_rows, "noReturn": no_return, "indirectCalls": indirect_rows,
|
|
388
418
|
"reachedRoutines": sorted(routine_starts), "counts": counts,
|
|
389
419
|
"unresolved": unresolved[:limit], "interrupts": interrupts[:limit], "gaps": gaps[:limit],
|
|
390
420
|
"contested": sorted(contested)[:limit],
|
|
391
421
|
"truncated": any(len(x) > limit for x in (unresolved, interrupts, gaps, contested)),
|
|
392
422
|
"instructionLimitReached": stopped,
|
|
393
|
-
"controls": [{"site": at, "target":
|
|
423
|
+
"controls": [{"site": at, "target": call_targets[at][0]} for at in controls],
|
|
394
424
|
"instructionControls": [{"site": at, "instruction": _text(seen[at]), "routine": routine.get(at)}
|
|
395
425
|
for at in instruction_controls],
|
|
396
426
|
"negativeUsable": bool(controls or instruction_controls)
|
|
397
427
|
and not (stopped or unresolved or gaps or contested or contradicted),
|
|
398
428
|
"assumptions": assumptions,
|
|
399
|
-
"exclusions": ["computed call and jump targets (listed in unresolved)", "unrelocated far calls",
|
|
429
|
+
"exclusions": ["computed call and jump targets no declaration gives (listed in unresolved)", "unrelocated far calls",
|
|
400
430
|
"code reached only from outside the starts", "runtime reachability"],
|
|
401
431
|
"interpretation": "Routes over the decoded entry-path CFG from the starts. A chain has the fewest calls; "
|
|
402
432
|
"throughEveryRoute lists the routine starts every read route to the target passes, "
|
|
@@ -404,6 +434,9 @@ def reach(image, config):
|
|
|
404
434
|
"negativeUsable needs a control of either kind, a walk that did not stop at its instruction limit, "
|
|
405
435
|
"and no unresolved transfer, gap, contested instruction or contradicted noReturn "
|
|
406
436
|
"routine, and still rests on the listed assumptions, leaves and noReturn declarations. "
|
|
437
|
+
"A declared indirect call counts as resolved when it is declared exhaustive: its table "
|
|
438
|
+
"rows are read from the build's bytes and its targets list rests on its evidence alone, "
|
|
439
|
+
"and neither proves an instruction boundary or that the call runs. "
|
|
407
440
|
"A noReturn routine is contradicted when a return instruction, or a leaf entered "
|
|
408
441
|
"other than by a call, lies on its own read paths; an empty returnSites means only "
|
|
409
442
|
"that the walk read none. "
|
|
@@ -15,6 +15,7 @@ from .image import Image, instruction_limit, integer, scan_limit
|
|
|
15
15
|
from .trace import (trace, walk, cfg_step, call_target, unsupported_transfer, uncovered, holding_instruction, base_mnemonic, OVERLAP_REASON, CONTESTED_REASON, LIMIT_REASON,
|
|
16
16
|
RETURNS, INTERRUPTS, PORTS, PORT_INPUTS, port_width, budget_input, modeled_interrupt_sites)
|
|
17
17
|
from .pcode_backend import interrupt_vector
|
|
18
|
+
from .dispatch import CALL_NOT_EXHAUSTIVE
|
|
18
19
|
|
|
19
20
|
|
|
20
21
|
def entries(image):
|
|
@@ -85,13 +86,16 @@ def search_coverage(image, spans):
|
|
|
85
86
|
return rows
|
|
86
87
|
|
|
87
88
|
|
|
88
|
-
def direct_calls(image, config, no_return_calls=frozenset(), no_return_interrupts=frozenset()):
|
|
89
|
+
def direct_calls(image, config, no_return_calls=frozenset(), no_return_interrupts=frozenset(), indirect_calls=None):
|
|
89
90
|
"""Every direct call site in the searched regions, as ``incoming`` and ``inventory-check`` read them.
|
|
90
91
|
|
|
91
92
|
Walks the entry-path CFG from every established entry, ending a branch at a call to a routine in
|
|
92
|
-
``no_return_calls`` and at an interrupt site in ``no_return_interrupts``
|
|
93
|
+
``no_return_calls`` and at an interrupt site in ``no_return_interrupts`` and following the declared
|
|
94
|
+
targets of each ``indirect_calls`` site as ``walk`` does, then
|
|
93
95
|
scans every byte of the regions ``searchRegions`` names (all regions by default) for E8 and 9A
|
|
94
|
-
call starts, and adds each reached call the scan cannot see (one that starts with a prefix).
|
|
96
|
+
call starts, and adds each reached call the scan cannot see (one that starts with a prefix). A
|
|
97
|
+
reached declared indirect call gives one row for each declared target, and one unresolved row more
|
|
98
|
+
when it is not declared exhaustive; those rows are not in ``scanned``. Returns a dict with the walk's
|
|
95
99
|
``seen``, ``gaps`` (with a ``raw scan limit`` gap where ``scanLimit`` stopped a region),
|
|
96
100
|
``edges``, ``undecoded`` and ``contested``; ``rows``, every call row in the order it was read,
|
|
97
101
|
each with its ``target`` (None when unresolved); ``scanned``, those rows by site, leaving out
|
|
@@ -99,7 +103,8 @@ def direct_calls(image, config, no_return_calls=frozenset(), no_return_interrupt
|
|
|
99
103
|
searched; and ``read``, the byte span the scan read in each.
|
|
100
104
|
"""
|
|
101
105
|
seen, gaps, edges, undecoded, contested = walk(image, entries(image), config.get("instructionLimit", 10000),
|
|
102
|
-
no_return_calls=no_return_calls, no_return_interrupts=no_return_interrupts
|
|
106
|
+
no_return_calls=no_return_calls, no_return_interrupts=no_return_interrupts,
|
|
107
|
+
indirect_calls=indirect_calls)
|
|
103
108
|
rows, scanned = [], {}
|
|
104
109
|
|
|
105
110
|
def classify(at):
|
|
@@ -144,6 +149,15 @@ def direct_calls(image, config, no_return_calls=frozenset(), no_return_interrupt
|
|
|
144
149
|
rows.append({"site": at, "target": None, "encoding": ins.mnemonic, "region": region["name"],
|
|
145
150
|
"classification": "unsupported control-transfer frame encoding"})
|
|
146
151
|
continue
|
|
152
|
+
declaration = (indirect_calls or {}).get(at)
|
|
153
|
+
if declaration is not None:
|
|
154
|
+
provenance = {"encoding": "declared indirect call", "evidence": declaration["evidence"]}
|
|
155
|
+
rows.extend({"site": at, "target": target, "encoding": ins.mnemonic, "classification": classify(at),
|
|
156
|
+
"provenance": provenance, "region": region["name"]} for target in declaration["targets"])
|
|
157
|
+
if not declaration["exhaustive"]:
|
|
158
|
+
rows.append({"site": at, "target": None, "encoding": ins.mnemonic, "classification": classify(at),
|
|
159
|
+
"provenance": {"reason": CALL_NOT_EXHAUSTIVE}, "region": region["name"]})
|
|
160
|
+
continue
|
|
147
161
|
resolved, provenance = call_target(image, at, ins)
|
|
148
162
|
row = {"site": at, "target": resolved, "encoding": ins.mnemonic,
|
|
149
163
|
"classification": classify(at), "provenance": provenance, "region": region["name"]}
|
|
@@ -1854,6 +1868,9 @@ def _run_report(image, config, command):
|
|
|
1854
1868
|
raise ValueError("entryFrame applies only to " + ", ".join(TRACE_COMMANDS))
|
|
1855
1869
|
if "inventory" in config and command != "inventory-check":
|
|
1856
1870
|
raise ValueError("inventory applies only to inventory-check")
|
|
1871
|
+
# Other commands do not read the declarations, so a config that carries them is refused rather than ignored.
|
|
1872
|
+
if "indirectCalls" in config and command not in ("reach", "inventory-check"):
|
|
1873
|
+
raise ValueError("indirectCalls applies only to reach and inventory-check")
|
|
1857
1874
|
if command == "operand":
|
|
1858
1875
|
return operand_provenance(image, config)
|
|
1859
1876
|
if command == "target":
|