scientific-method-engine 13.0.0__tar.gz → 13.2.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-13.0.0 → scientific_method_engine-13.2.0}/PKG-INFO +1 -1
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/pyproject.toml +1 -1
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/cli.py +4 -1
- scientific_method_engine-13.2.0/src/scientific_method_engine/x86/reach.py +246 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/relational.py +9 -6
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/reports.py +5 -3
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/trace.py +27 -14
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/values.py +20 -2
- scientific_method_engine-13.2.0/tests/test_reach.py +173 -0
- scientific_method_engine-13.2.0/tests/test_term_limit.py +120 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_x86.py +4 -2
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/.gitignore +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/LICENSE +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/README.md +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/__init__.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/__main__.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/__init__.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/image.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/loops.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/machine.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/pcode.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/pe.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/oracle.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_continuation_budget.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_dispatch.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_effect_order.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_enter_frames.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_entry_frame.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_indirect_far_transfers.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_interrupt_models.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_loops.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_memory_scopes.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_nested_frame_request.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_oracle.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_pe.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_relational_controls.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_return_checks.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_successor_rule.py +0 -0
- {scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_table_continuations.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: scientific-method-engine
|
|
3
|
-
Version: 13.
|
|
3
|
+
Version: 13.2.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 = "13.
|
|
8
|
+
version = "13.2.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"
|
|
@@ -13,7 +13,7 @@ PREPARED_CONFIG_LIMIT = 16 * 1024 * 1024
|
|
|
13
13
|
# The header names the decoder and instruction semantics that actually ran, not the pins in pyproject.toml.
|
|
14
14
|
DECODER = "capstone " + capstone.__version__
|
|
15
15
|
INSTRUCTION_SEMANTICS = f"pypcode {pypcode.__version__} (Ghidra SLEIGH x86)"
|
|
16
|
-
USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bounds|owner|callees|trace|uses|arguments|"
|
|
16
|
+
USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bounds|owner|callees|reach|trace|uses|arguments|"
|
|
17
17
|
"effects|returns|memory|incoming|call-order|guards|allocation|dispatch> <config.json|->\n"
|
|
18
18
|
"effects includes ordered path writes/calls and local restoration witnesses; transactionality remains unestablished.\n"
|
|
19
19
|
"callees compares its edges with an ExportCallEdges.java export given as ghidraCallEdges;\n"
|
|
@@ -21,6 +21,9 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
|
|
|
21
21
|
"agreed is false where Ghidra ends the function at an instruction the engine reads past (ghidraEndsFunction),\n"
|
|
22
22
|
"continues past one the engine stops at (ghidraContinues),\n"
|
|
23
23
|
"or continues at another address than the next instruction (ghidraFallsThroughElsewhere).\n"
|
|
24
|
+
"reach lists the target sites the starts reach over resolved calls and jumps, with the fewest-call chain\n"
|
|
25
|
+
"and the routines every read route passes, and lists every reached transfer it could not resolve;\n"
|
|
26
|
+
"a leaves routine is reached but not read, and its reason is repeated in the report.\n"
|
|
24
27
|
"trace, arguments, effects, returns, guards, memory and allocation check relationalControls:\n"
|
|
25
28
|
"a violated control fails the report; an undecided one is reported and never counts as held.\n"
|
|
26
29
|
"A lastWriter control with an address inspects that memory at its checkpoint anchors without a read.\n"
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
"""Transitive reachability from established starts to target sites over the entry-path CFG."""
|
|
2
|
+
from collections import deque
|
|
3
|
+
from .image import integer
|
|
4
|
+
from .trace import walk, cfg_step, base_mnemonic, unsupported_transfer, holding_instruction, INTERRUPTS, RETURNS
|
|
5
|
+
from .pcode_backend import interrupt_vector
|
|
6
|
+
|
|
7
|
+
# The virtual root of the dominator computation; no file offset is negative.
|
|
8
|
+
ROOT = -1
|
|
9
|
+
CALLS = ("call", "lcall")
|
|
10
|
+
UNSUPPORTED = "unsupported control-transfer frame encoding"
|
|
11
|
+
LEAF_OVERLAP = "leaf start inside a reached instruction; the leaf is not decoded, so its boundary is unchecked"
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def _sites(value, label, image, limit=256):
|
|
15
|
+
if not isinstance(value, list) or not 1 <= len(value) <= limit or len(set(map(repr, value))) != len(value):
|
|
16
|
+
raise ValueError(f"{label} must be a list of 1..{limit} distinct file offsets")
|
|
17
|
+
for at in value:
|
|
18
|
+
integer(at, 0, len(image.data) - 1, label)
|
|
19
|
+
if image.region(at) is None:
|
|
20
|
+
raise ValueError(f"{label} {at} is outside declared code")
|
|
21
|
+
return list(value)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _leaves(value, image, starts):
|
|
25
|
+
if not isinstance(value, list) or len(value) > 256:
|
|
26
|
+
raise ValueError("leaves must be a list of at most 256 objects")
|
|
27
|
+
leaves = {}
|
|
28
|
+
for leaf in value:
|
|
29
|
+
if not isinstance(leaf, dict) or set(leaf) != {"routine", "reason"}:
|
|
30
|
+
raise ValueError("Each leaf needs exactly routine and reason")
|
|
31
|
+
at = integer(leaf["routine"], 0, len(image.data) - 1, "leaf routine")
|
|
32
|
+
if image.region(at) is None:
|
|
33
|
+
raise ValueError(f"leaf routine {at} is outside declared code")
|
|
34
|
+
if not isinstance(leaf["reason"], str) or not leaf["reason"].strip():
|
|
35
|
+
raise ValueError("A leaf needs a nonempty reason")
|
|
36
|
+
if at in leaves:
|
|
37
|
+
raise ValueError("Duplicate leaf routine")
|
|
38
|
+
if at in starts:
|
|
39
|
+
raise ValueError("A start cannot be a leaf")
|
|
40
|
+
leaves[at] = leaf["reason"]
|
|
41
|
+
return leaves
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def _kinds(at, ins, step):
|
|
45
|
+
"""Each successor of ``step`` with how the CFG reaches it: call, return, table, interrupt, jump or fall."""
|
|
46
|
+
m, following = base_mnemonic(ins), at + ins.size
|
|
47
|
+
targets = {e["target"] for e in step.edges if e["target"] is not None}
|
|
48
|
+
rows, called = [], False
|
|
49
|
+
for successor in step.successors:
|
|
50
|
+
if step.supplied:
|
|
51
|
+
kind = "table"
|
|
52
|
+
elif m in CALLS:
|
|
53
|
+
# A call names its target first; a call to the next instruction lists that site twice.
|
|
54
|
+
kind = "call" if successor in targets and not called else "return"
|
|
55
|
+
called = called or kind == "call"
|
|
56
|
+
elif m in INTERRUPTS:
|
|
57
|
+
kind = "interrupt"
|
|
58
|
+
elif successor == following and m not in ("jmp", "ljmp") and (successor not in targets or len(rows) > 0):
|
|
59
|
+
kind = "fall"
|
|
60
|
+
else:
|
|
61
|
+
kind = "jump"
|
|
62
|
+
rows.append((successor, kind))
|
|
63
|
+
return rows
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _dominators(order, predecessors):
|
|
67
|
+
"""Immediate dominators (Cooper, Harvey and Kennedy) of every node in ``order``, a reverse postorder from ROOT."""
|
|
68
|
+
index = {node: i for i, node in enumerate(order)}
|
|
69
|
+
idom = {ROOT: ROOT}
|
|
70
|
+
|
|
71
|
+
def intersect(a, b):
|
|
72
|
+
while a != b:
|
|
73
|
+
while index[a] > index[b]:
|
|
74
|
+
a = idom[a]
|
|
75
|
+
while index[b] > index[a]:
|
|
76
|
+
b = idom[b]
|
|
77
|
+
return a
|
|
78
|
+
changed = True
|
|
79
|
+
while changed:
|
|
80
|
+
changed = False
|
|
81
|
+
for node in order[1:]:
|
|
82
|
+
done = [p for p in predecessors[node] if p in idom]
|
|
83
|
+
new = done[0]
|
|
84
|
+
for p in done[1:]:
|
|
85
|
+
new = intersect(p, new)
|
|
86
|
+
if idom.get(node) != new:
|
|
87
|
+
idom[node] = new
|
|
88
|
+
changed = True
|
|
89
|
+
return idom
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def reach(image, config):
|
|
93
|
+
"""Which target sites the starts reach over resolved calls and jumps, by which chain, and what the walk could not read.
|
|
94
|
+
|
|
95
|
+
The walk decodes from ``starts`` (established region entries) and follows every resolved call
|
|
96
|
+
into its callee and on at its return site, every resolved jump and branch, the rows of a
|
|
97
|
+
declared indirect jump table, and every interrupt to the next instruction. A ``leaves`` routine
|
|
98
|
+
is reached but never decoded. Each reached target gets one chain with the fewest calls, the
|
|
99
|
+
assumptions its route rests on, and the routines on every route to it within the read graph.
|
|
100
|
+
"""
|
|
101
|
+
from .reports import entries
|
|
102
|
+
starts = _sites(config.get("starts"), "starts", image)
|
|
103
|
+
established = set(entries(image))
|
|
104
|
+
for at in starts:
|
|
105
|
+
if at not in established:
|
|
106
|
+
raise ValueError(f"Reach start {at} must be an established region entry")
|
|
107
|
+
targets = _sites(config.get("targets"), "targets", image)
|
|
108
|
+
leaves = _leaves(config.get("leaves", []), image, set(starts))
|
|
109
|
+
controls = config.get("controls", [])
|
|
110
|
+
if (not isinstance(controls, list) or len(controls) > 256 or any(type(at) is not int for at in controls)
|
|
111
|
+
or len(set(controls)) != len(controls)):
|
|
112
|
+
raise ValueError("Positive controls must be at most 256 distinct file offsets")
|
|
113
|
+
limit = integer(config.get("limit", 1000), 1, 10000, "result limit")
|
|
114
|
+
instruction_limit = config.get("instructionLimit", 10000)
|
|
115
|
+
seen, walk_gaps, _, _, contested = walk(image, starts, instruction_limit, follow_interrupts=True, stops=frozenset(leaves))
|
|
116
|
+
|
|
117
|
+
graph, unresolved, interrupts, resolved_calls = {}, [], [], {}
|
|
118
|
+
for at, ins in sorted(seen.items()):
|
|
119
|
+
step = cfg_step(image, at, ins, follow_interrupts=True)
|
|
120
|
+
graph[at] = [(s, kind) for s, kind in _kinds(at, ins, step) if s in seen or s in leaves]
|
|
121
|
+
m = base_mnemonic(ins)
|
|
122
|
+
text = (ins.mnemonic + " " + ins.op_str).strip()
|
|
123
|
+
kind = "call" if m in CALLS else "return" if m in RETURNS else "jump"
|
|
124
|
+
if unsupported_transfer(image, ins):
|
|
125
|
+
unresolved.append({"site": at, "instruction": text, "kind": kind, "reason": UNSUPPORTED})
|
|
126
|
+
for edge in step.edges:
|
|
127
|
+
if edge["target"] is None:
|
|
128
|
+
unresolved.append({"site": at, "instruction": text, "kind": kind,
|
|
129
|
+
"reason": edge["provenance"].get("reason", "target outside declared regions")})
|
|
130
|
+
elif m in CALLS:
|
|
131
|
+
resolved_calls[at] = edge["target"]
|
|
132
|
+
if m in INTERRUPTS:
|
|
133
|
+
vector, conditional = interrupt_vector(image.flat, ins, at)
|
|
134
|
+
interrupts.append({"site": at, "instruction": text, "vector": vector, "conditional": conditional})
|
|
135
|
+
for at in leaves:
|
|
136
|
+
graph.setdefault(at, [])
|
|
137
|
+
|
|
138
|
+
# Fewest calls first: entering a callee costs one, every other edge nothing (0-1 breadth-first search).
|
|
139
|
+
distance, parent, routine = {}, {}, {}
|
|
140
|
+
queue = deque()
|
|
141
|
+
for at in starts:
|
|
142
|
+
distance[at], parent[at], routine[at] = 0, None, at
|
|
143
|
+
queue.append((0, at))
|
|
144
|
+
while queue:
|
|
145
|
+
cost, at = queue.popleft()
|
|
146
|
+
if cost > distance[at]:
|
|
147
|
+
continue
|
|
148
|
+
for successor, kind in graph.get(at, []):
|
|
149
|
+
step_cost = cost + (kind == "call")
|
|
150
|
+
if successor not in distance or step_cost < distance[successor]:
|
|
151
|
+
distance[successor], parent[successor] = step_cost, (at, kind)
|
|
152
|
+
routine[successor] = successor if kind == "call" else routine[at]
|
|
153
|
+
(queue.append if kind == "call" else queue.appendleft)((step_cost, successor))
|
|
154
|
+
|
|
155
|
+
# Dominators over everything reached, from a virtual root that leads to every start.
|
|
156
|
+
successors = {ROOT: list(starts)} | {at: [s for s, _ in graph.get(at, [])] for at in distance}
|
|
157
|
+
order, visited, stack = [], {ROOT}, [(ROOT, iter(successors[ROOT]))]
|
|
158
|
+
while stack:
|
|
159
|
+
node, children = stack[-1]
|
|
160
|
+
child = next(children, None)
|
|
161
|
+
if child is None:
|
|
162
|
+
order.append(node)
|
|
163
|
+
stack.pop()
|
|
164
|
+
elif child not in visited:
|
|
165
|
+
visited.add(child)
|
|
166
|
+
stack.append((child, iter(successors[child])))
|
|
167
|
+
order.reverse()
|
|
168
|
+
predecessors = {node: [] for node in order}
|
|
169
|
+
for node in order:
|
|
170
|
+
for child in successors[node]:
|
|
171
|
+
predecessors[child].append(node)
|
|
172
|
+
idom = _dominators(order, predecessors)
|
|
173
|
+
routine_starts = set(starts) | {target for at, target in resolved_calls.items() if target in distance}
|
|
174
|
+
|
|
175
|
+
def chain(target):
|
|
176
|
+
hops, assumed_returns, tables, continued = [], [], [], []
|
|
177
|
+
at = target
|
|
178
|
+
while parent[at] is not None:
|
|
179
|
+
previous, kind = parent[at]
|
|
180
|
+
if kind == "call":
|
|
181
|
+
hops.append({"callSite": previous, "routine": at})
|
|
182
|
+
elif kind == "return":
|
|
183
|
+
assumed_returns.append(previous)
|
|
184
|
+
elif kind == "table":
|
|
185
|
+
tables.append({"site": previous, "target": at})
|
|
186
|
+
elif kind == "interrupt":
|
|
187
|
+
continued.append(previous)
|
|
188
|
+
at = previous
|
|
189
|
+
hops.append({"routine": at})
|
|
190
|
+
return {"chain": hops[::-1], "calls": distance[target],
|
|
191
|
+
"route": {"assumedReturns": assumed_returns[::-1], "declaredTableJumps": tables[::-1],
|
|
192
|
+
"interruptsContinued": continued[::-1]}}
|
|
193
|
+
|
|
194
|
+
rows = []
|
|
195
|
+
for target in targets:
|
|
196
|
+
row = {"target": target}
|
|
197
|
+
if target in distance:
|
|
198
|
+
cut, at = [], idom[target]
|
|
199
|
+
while at != ROOT:
|
|
200
|
+
if at in routine_starts:
|
|
201
|
+
cut.append(at)
|
|
202
|
+
at = idom[at]
|
|
203
|
+
row |= {"reached": True, "routine": routine[target], "leaf": target in leaves, **chain(target),
|
|
204
|
+
"throughEveryRoute": cut[::-1]}
|
|
205
|
+
else:
|
|
206
|
+
holder = holding_instruction(seen, target)
|
|
207
|
+
row |= {"reached": False, "status": "inside a reached instruction" if holder is not None
|
|
208
|
+
else "start of a contested instruction" if target in contested else "not reached",
|
|
209
|
+
**({"insideInstruction": holder} if holder is not None else {})}
|
|
210
|
+
rows.append(row)
|
|
211
|
+
|
|
212
|
+
for row in unresolved + interrupts:
|
|
213
|
+
row["routine"] = routine.get(row["site"])
|
|
214
|
+
unresolved_sites = {row["site"] for row in unresolved}
|
|
215
|
+
gaps = [g for g in walk_gaps if g["site"] not in unresolved_sites and g["site"] not in contested]
|
|
216
|
+
# The walk never decodes a leaf, so its overlap check cannot see a leaf start inside a decoded instruction.
|
|
217
|
+
gaps += [{"site": at, "reason": LEAF_OVERLAP, "insideInstruction": holding_instruction(seen, at)}
|
|
218
|
+
for at in sorted(leaves) if at in distance and holding_instruction(seen, at) is not None]
|
|
219
|
+
for at in controls:
|
|
220
|
+
if at not in resolved_calls:
|
|
221
|
+
raise ValueError(f"Positive control {at} missed or not resolved")
|
|
222
|
+
call_sites = {}
|
|
223
|
+
for site, target in sorted(resolved_calls.items()):
|
|
224
|
+
call_sites.setdefault(target, []).append(site)
|
|
225
|
+
leaf_rows = [{"routine": at, "reason": reason, "reached": at in distance, "callSites": call_sites.get(at, [])}
|
|
226
|
+
for at, reason in leaves.items()]
|
|
227
|
+
counts = {"routines": len(routine_starts), "instructions": len(seen), "unresolved": len(unresolved),
|
|
228
|
+
"interrupts": len(interrupts), "gaps": len(gaps), "contested": len(contested)}
|
|
229
|
+
return {"starts": starts, "targets": rows, "leaves": leaf_rows,
|
|
230
|
+
"reachedRoutines": sorted(routine_starts), "counts": counts,
|
|
231
|
+
"unresolved": unresolved[:limit], "interrupts": interrupts[:limit], "gaps": gaps[:limit],
|
|
232
|
+
"contested": sorted(contested)[:limit],
|
|
233
|
+
"truncated": any(len(x) > limit for x in (unresolved, interrupts, gaps, contested)),
|
|
234
|
+
"controls": [{"site": at, "target": resolved_calls[at]} for at in controls],
|
|
235
|
+
"negativeUsable": bool(controls) and not (unresolved or gaps or contested),
|
|
236
|
+
"assumptions": ["each reached call returns to its next instruction",
|
|
237
|
+
"each reached interrupt returns to its next instruction; interrupt handlers are not read",
|
|
238
|
+
"each leaf calls nothing, for the reason it gives",
|
|
239
|
+
"each declared indirect jump table holds the routes its declaration gives"],
|
|
240
|
+
"exclusions": ["computed call and jump targets (listed in unresolved)", "unrelocated far calls",
|
|
241
|
+
"code reached only from outside the starts", "runtime reachability"],
|
|
242
|
+
"interpretation": "Routes over the decoded entry-path CFG from the starts. A chain has the fewest calls; "
|
|
243
|
+
"throughEveryRoute lists the routine starts every read route to the target passes, "
|
|
244
|
+
"and an unresolved transfer may add a route that passes none of them. "
|
|
245
|
+
"negativeUsable needs controls and no unresolved transfer, gap or contested instruction, "
|
|
246
|
+
"and still rests on the listed assumptions and leaves."}
|
|
@@ -9,7 +9,7 @@ from math import inf
|
|
|
9
9
|
from .image import integer
|
|
10
10
|
from .machine import ALIASES, NO_WRITE, State, StopPath
|
|
11
11
|
from .memory_scopes import SEGMENTS
|
|
12
|
-
from .values import const, op
|
|
12
|
+
from .values import const, op, TermLimit
|
|
13
13
|
|
|
14
14
|
KINDS = ("reach", "order", "lastWriter", "containment", "relation", "origin")
|
|
15
15
|
OPERATORS = ("eq", "ne", "lt", "le", "gt", "ge")
|
|
@@ -144,14 +144,17 @@ def probe_memory(state, name, address):
|
|
|
144
144
|
The row carries ``byteProducers`` as a read of those bytes would report them, or ``unresolved``
|
|
145
145
|
when the address cannot be inspected.
|
|
146
146
|
"""
|
|
147
|
-
offset = const(address.get("displacement", 0), state.bits)
|
|
148
|
-
if "base" in address:
|
|
149
|
-
offset = op("add", state.reg(address["base"]), offset)
|
|
150
147
|
segment = state.segment(address["segment"])
|
|
151
|
-
row = {"control": name, "segment": segment.report(), "offset":
|
|
148
|
+
row = {"control": name, "segment": segment.report(), "offset": None, "width": address["width"]}
|
|
149
|
+
# A probe only observes the path, so an address it cannot form (``offset`` stays None) or
|
|
150
|
+
# inspect leaves the row unresolved and the path running.
|
|
152
151
|
try:
|
|
152
|
+
offset = const(address.get("displacement", 0), state.bits)
|
|
153
|
+
if "base" in address:
|
|
154
|
+
offset = op("add", state.reg(address["base"]), offset)
|
|
155
|
+
row["offset"] = offset.report()
|
|
153
156
|
keys = state.keys(segment, offset, address["width"])[3]
|
|
154
|
-
except StopPath as error:
|
|
157
|
+
except (StopPath, TermLimit) as error:
|
|
155
158
|
return {**row, "unresolved": str(error)}
|
|
156
159
|
return {**row, "byteProducers": [state.byte_writer(i, key) for i, key in enumerate(keys)]}
|
|
157
160
|
|
|
@@ -12,7 +12,7 @@ from .argument_frames import WINDOW_BYTES, argument_frames, stack_cleanup
|
|
|
12
12
|
from .memory_scopes import model_scopes
|
|
13
13
|
from .result_flow import return_flows
|
|
14
14
|
from .image import Image, integer
|
|
15
|
-
from .trace import (trace, walk, cfg_step, call_target, unsupported_transfer, uncovered, base_mnemonic, OVERLAP_REASON, CONTESTED_REASON,
|
|
15
|
+
from .trace import (trace, walk, cfg_step, call_target, unsupported_transfer, uncovered, holding_instruction, base_mnemonic, OVERLAP_REASON, CONTESTED_REASON,
|
|
16
16
|
RETURNS, INTERRUPTS, PORTS, PORT_INPUTS, port_width, budget_input)
|
|
17
17
|
from .pcode_backend import interrupt_vector
|
|
18
18
|
|
|
@@ -176,8 +176,7 @@ def incoming(image, config):
|
|
|
176
176
|
if site in contested:
|
|
177
177
|
row["position"] = {"meaning": "start of a contested instruction"}
|
|
178
178
|
continue
|
|
179
|
-
|
|
180
|
-
inside = next((at for at in range(max(site - 14, 0), site) if at in seen and site < at + seen[at].size), None)
|
|
179
|
+
inside = holding_instruction(seen, site)
|
|
181
180
|
if inside is not None:
|
|
182
181
|
row["position"] = {"insideInstruction": inside, "meaning": "bytes of a reached instruction; a call here needs an overlapping start"}
|
|
183
182
|
continue
|
|
@@ -1729,6 +1728,9 @@ def _run_report(image, config, command):
|
|
|
1729
1728
|
return owner(image, config)
|
|
1730
1729
|
if command == "callees":
|
|
1731
1730
|
return callees(image, config)
|
|
1731
|
+
if command == "reach":
|
|
1732
|
+
from .reach import reach
|
|
1733
|
+
return reach(image, config)
|
|
1732
1734
|
if command == "call-order":
|
|
1733
1735
|
return call_order(image, config)
|
|
1734
1736
|
if command == "incoming":
|
|
@@ -6,13 +6,17 @@ from .image import integer
|
|
|
6
6
|
from .machine import (State, StopPath, REGISTERS, ALIASES, BRANCH_CONDITIONS, string_instruction,
|
|
7
7
|
string_count, string_effect, check_string_form, compare_string, repeated, string_width,
|
|
8
8
|
FLAT_PORT_REASON)
|
|
9
|
-
from .values import const, unknown, sources, op, join
|
|
9
|
+
from .values import const, unknown, sources, op, join, TermLimit
|
|
10
10
|
from .result_flow import validate_contracts, result_contracts
|
|
11
11
|
from .loops import LoopTracker
|
|
12
12
|
from .memory_scopes import validate_scopes, capture_scopes, retain_scopes, scope_history
|
|
13
13
|
from .pcode_backend import interrupt_vector
|
|
14
14
|
from .relational import checkpoint_anchors, memory_probes, probe_memory
|
|
15
15
|
|
|
16
|
+
# What stops one path and leaves the others: the model cannot follow it, or a value it built
|
|
17
|
+
# would pass the term limit. Errors in the query still fail the run.
|
|
18
|
+
PATH_STOPS = (StopPath, TermLimit)
|
|
19
|
+
|
|
16
20
|
def call_target(image, site, ins):
|
|
17
21
|
if ins.mnemonic in ("lcall", "ljmp"):
|
|
18
22
|
return image.far_target(site, ins)
|
|
@@ -156,11 +160,12 @@ class Step(NamedTuple):
|
|
|
156
160
|
supplied: bool = False
|
|
157
161
|
|
|
158
162
|
|
|
159
|
-
def cfg_step(image, at, ins, follow_flat_ports=False, step_over_calls=False):
|
|
163
|
+
def cfg_step(image, at, ins, follow_flat_ports=False, step_over_calls=False, follow_interrupts=False):
|
|
160
164
|
"""The successors of ``ins`` decoded at ``at``, under the rule ``walk`` and the ``uses`` caller continuation share.
|
|
161
165
|
|
|
162
|
-
An unsupported transfer encoding, a return, an unconditional jump without a resolved target,
|
|
163
|
-
|
|
166
|
+
An unsupported transfer encoding, a return, an unconditional jump without a resolved target,
|
|
167
|
+
``hlt``, an interrupt unless ``follow_interrupts`` (which continues at the next instruction, as
|
|
168
|
+
``body()`` does) and, unless ``follow_flat_ports``, a PE32 port access end the branch. A
|
|
164
169
|
conditional jump or loop continues at its resolved target and at the next instruction. A declared
|
|
165
170
|
indirect jump continues at its table rows only. A call continues at its resolved target and at
|
|
166
171
|
its return site; with ``step_over_calls`` it continues at its return site only and its target
|
|
@@ -193,7 +198,7 @@ def cfg_step(image, at, ins, follow_flat_ports=False, step_over_calls=False):
|
|
|
193
198
|
successors.append(target)
|
|
194
199
|
if m in ("jmp", "ljmp"):
|
|
195
200
|
return Step(successors, False, None, gaps, edges)
|
|
196
|
-
if m
|
|
201
|
+
if m == "hlt" or (m in INTERRUPTS and not follow_interrupts):
|
|
197
202
|
gaps.append({"site": at, "reason": "hardware or interrupt boundary"})
|
|
198
203
|
return Step(successors, False, None, gaps, edges)
|
|
199
204
|
# In the flat model I/O privilege decides whether a port access faults, so the walk claims nothing after it.
|
|
@@ -206,12 +211,14 @@ def cfg_step(image, at, ins, follow_flat_ports=False, step_over_calls=False):
|
|
|
206
211
|
return Step(successors, False, return_site, gaps, edges)
|
|
207
212
|
|
|
208
213
|
|
|
209
|
-
def walk(image, entries, limit=10000, follow_flat_ports=False):
|
|
214
|
+
def walk(image, entries, limit=10000, follow_flat_ports=False, follow_interrupts=False, stops=frozenset()):
|
|
210
215
|
"""Decode the CFG reached from ``entries`` and check its instruction boundaries.
|
|
211
216
|
|
|
212
217
|
A port access in the flat model records a gap and ends that branch, as ``trace`` stops there.
|
|
213
218
|
``follow_flat_ports`` continues past it instead, for callers that name each port access their
|
|
214
|
-
results depend on.
|
|
219
|
+
results depend on. ``follow_interrupts`` continues past an interrupt at the next instruction,
|
|
220
|
+
for callers that list each interrupt as an assumption. A site in ``stops`` is never decoded:
|
|
221
|
+
the walk reaches it and goes no further, so it is in no returned set.
|
|
215
222
|
"""
|
|
216
223
|
integer(limit, 1, 100000, "instruction limit")
|
|
217
224
|
pending, seen, gaps, edges = list(entries), {}, [], []
|
|
@@ -220,7 +227,7 @@ def walk(image, entries, limit=10000, follow_flat_ports=False):
|
|
|
220
227
|
successors, returns, supplied_edges = {}, set(), set()
|
|
221
228
|
while pending:
|
|
222
229
|
at = pending.pop()
|
|
223
|
-
if at in seen:
|
|
230
|
+
if at in seen or at in stops:
|
|
224
231
|
continue
|
|
225
232
|
if len(seen) >= limit:
|
|
226
233
|
gaps.append({"site": at, "reason": "instruction limit"})
|
|
@@ -230,7 +237,7 @@ def walk(image, entries, limit=10000, follow_flat_ports=False):
|
|
|
230
237
|
gaps.append({"site": at, "reason": "undecoded or unmapped edge"})
|
|
231
238
|
continue
|
|
232
239
|
seen[at] = ins
|
|
233
|
-
step = cfg_step(image, at, ins, follow_flat_ports)
|
|
240
|
+
step = cfg_step(image, at, ins, follow_flat_ports, follow_interrupts=follow_interrupts)
|
|
234
241
|
successors[at] = step.successors
|
|
235
242
|
gaps.extend(step.gaps)
|
|
236
243
|
edges.extend(step.edges)
|
|
@@ -318,6 +325,12 @@ def walk(image, entries, limit=10000, follow_flat_ports=False):
|
|
|
318
325
|
return seen, gaps, edges, undecoded, contested
|
|
319
326
|
|
|
320
327
|
|
|
328
|
+
def holding_instruction(seen, site):
|
|
329
|
+
"""The start of the instruction in ``seen`` whose bytes cover ``site`` past its first byte, or None."""
|
|
330
|
+
# An x86 instruction is at most 15 bytes, so only the starts just before the site can hold it.
|
|
331
|
+
return next((at for at in range(max(site - 14, 0), site) if at in seen and site < at + seen[at].size), None)
|
|
332
|
+
|
|
333
|
+
|
|
321
334
|
def uncovered(start, end, spans):
|
|
322
335
|
"""The ranges of start..end that no span covers; spans are clipped to the bounds."""
|
|
323
336
|
missing, cursor = [], start
|
|
@@ -740,7 +753,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
740
753
|
try:
|
|
741
754
|
value = s.get(ins, ins.operands[0], image)
|
|
742
755
|
address = s.address(ins, ins.operands[0]) if ins.operands[0].type == X86_OP_MEM else None
|
|
743
|
-
except
|
|
756
|
+
except PATH_STOPS as error:
|
|
744
757
|
global_gaps.append({"site": s.at, "reason": "conditional table operand unresolved: " + str(error)})
|
|
745
758
|
return
|
|
746
759
|
groups = {}
|
|
@@ -902,7 +915,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
902
915
|
string_step(child, ins, count)
|
|
903
916
|
child.at = following
|
|
904
917
|
pending.append(child)
|
|
905
|
-
except
|
|
918
|
+
except PATH_STOPS as error:
|
|
906
919
|
finish(child, str(error))
|
|
907
920
|
string_step(state, ins, count)
|
|
908
921
|
state.at = following
|
|
@@ -916,7 +929,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
916
929
|
# Scopes resolve first, so a path that stops on them reports the boundary unmodeled.
|
|
917
930
|
try:
|
|
918
931
|
captured = capture_model_scopes(state, interrupt_model, 6)
|
|
919
|
-
except
|
|
932
|
+
except PATH_STOPS:
|
|
920
933
|
state.event("hardware-boundary", boundary="interrupt", mnemonic=m, vector=vector,
|
|
921
934
|
interpretation="the interrupt handler and its effects are not modeled")
|
|
922
935
|
raise
|
|
@@ -989,7 +1002,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
989
1002
|
try:
|
|
990
1003
|
flags_word = state.peek(state.segment("ss"), op("add", state.reg(state.sp), const(4, 16), at), 2)
|
|
991
1004
|
flags_frame = (16, flags_word.term) in state.saved_flags
|
|
992
|
-
except
|
|
1005
|
+
except PATH_STOPS:
|
|
993
1006
|
flags_frame = False
|
|
994
1007
|
# A traced call records its return-frame width; argumentFrames maps the slots above it.
|
|
995
1008
|
call_event["returnFrameBytes"] = 4 if m == "lcall" or push_cs else image.bits // 8
|
|
@@ -1125,7 +1138,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
1125
1138
|
continue
|
|
1126
1139
|
state.semantics.ordinary(state, ins, image)
|
|
1127
1140
|
state.at = following
|
|
1128
|
-
except
|
|
1141
|
+
except PATH_STOPS as error:
|
|
1129
1142
|
finish(state, str(error))
|
|
1130
1143
|
if continuing:
|
|
1131
1144
|
# Only continuation states are traced after the switch: deferred states are popped only when
|
|
@@ -1,6 +1,24 @@
|
|
|
1
1
|
"""Small bit-vector expressions; unknown values retain their producers."""
|
|
2
2
|
from dataclasses import dataclass
|
|
3
3
|
|
|
4
|
+
# The most terms one value's expression may hold, counting every tuple node at any depth.
|
|
5
|
+
TERM_LIMIT = 1024
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class TermLimit(ValueError):
|
|
9
|
+
"""A value's expression would hold more than ``TERM_LIMIT`` terms.
|
|
10
|
+
|
|
11
|
+
A trace stops the path whose instruction built the value, with this message as the stop
|
|
12
|
+
reason. Raised anywhere else, it fails the run like any other ``ValueError``.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
MESSAGE = f"expression term limit: a value's expression would hold more than {TERM_LIMIT} terms; narrow the query"
|
|
16
|
+
|
|
17
|
+
def __init__(self, message=MESSAGE):
|
|
18
|
+
# The message is an argument so that copying or pickling the error can rebuild it.
|
|
19
|
+
super().__init__(message)
|
|
20
|
+
|
|
21
|
+
|
|
4
22
|
@dataclass(frozen=True)
|
|
5
23
|
class Value:
|
|
6
24
|
bits: int
|
|
@@ -12,8 +30,8 @@ class Value:
|
|
|
12
30
|
while pending:
|
|
13
31
|
term = pending.pop()
|
|
14
32
|
count += 1
|
|
15
|
-
if count >
|
|
16
|
-
raise
|
|
33
|
+
if count > TERM_LIMIT:
|
|
34
|
+
raise TermLimit()
|
|
17
35
|
if isinstance(term, tuple):
|
|
18
36
|
pending.extend(item for item in term if isinstance(item, tuple))
|
|
19
37
|
|
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
"""Synthetic machine code only. No original binaries or analysis artifacts."""
|
|
2
|
+
from pathlib import Path
|
|
3
|
+
import sys
|
|
4
|
+
import unittest
|
|
5
|
+
|
|
6
|
+
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
|
|
7
|
+
from scientific_method_engine.x86.reports import run_report
|
|
8
|
+
|
|
9
|
+
# One resident segment. 0000 calls 000B, then 0018, then a far pointer in memory. 000B dispatches
|
|
10
|
+
# through a two-word table at 0030 (rows 0024 and 0020) under `cmp bx, 1; ja`. 0018 and 0020 both
|
|
11
|
+
# call 0028, which stores a word. The word at 0034 follows the table and is no row of it.
|
|
12
|
+
DISPATCH = bytes.fromhex(
|
|
13
|
+
"e80800" # 0000 call 000B
|
|
14
|
+
"e81200" # 0003 call 0018
|
|
15
|
+
"ff1e0002" # 0006 call far [0200]
|
|
16
|
+
"c3" # 000A ret
|
|
17
|
+
"83fb01" # 000B cmp bx, 1
|
|
18
|
+
"7707" # 000E ja 0017
|
|
19
|
+
"d1e3" # 0010 shl bx, 1
|
|
20
|
+
"2effa73000" # 0012 jmp cs:[bx+0030]
|
|
21
|
+
"c3" # 0017 ret
|
|
22
|
+
"e80d00" # 0018 call 0028
|
|
23
|
+
"c3" # 001B ret
|
|
24
|
+
"90909090" # 001C padding
|
|
25
|
+
"e80500" # 0020 call 0028
|
|
26
|
+
"c3" # 0023 ret
|
|
27
|
+
"c3" # 0024 ret
|
|
28
|
+
"909090" # 0025 padding
|
|
29
|
+
"c70600010100" # 0028 mov word [0100], 1
|
|
30
|
+
"c3" # 002E ret
|
|
31
|
+
"90" # 002F padding
|
|
32
|
+
"24002000" # 0030 table rows 0024, 0020
|
|
33
|
+
"2800" # 0034 a word after the table
|
|
34
|
+
)
|
|
35
|
+
TABLE = {"site": 0x12, "exhaustive": True, "evidence": "synthetic: bx is gated to 0..1 before the jump",
|
|
36
|
+
"table": {"start": 0x30, "count": 2, "stride": 2, "evidence": "synthetic: two rows under cmp bx, 1"}}
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def config(data=DISPATCH, entries=(0,), **extra):
|
|
40
|
+
return {"regions": [{"name": "synthetic", "start": 0, "end": len(data), "ip": 0, "segment": 0x1000, "resident": True,
|
|
41
|
+
"entries": list(entries), "evidence": "synthetic declared code extent"}],
|
|
42
|
+
"starts": [0], "targets": [0x28], **extra}
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def reach(data=DISPATCH, entries=(0,), **extra):
|
|
46
|
+
return run_report(data, config(data, entries, **extra), "reach")
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class ReachTests(unittest.TestCase):
|
|
50
|
+
def test_declared_table_and_direct_calls_both_reach_the_target(self):
|
|
51
|
+
r = reach(indirectJumps=[TABLE], controls=[0x3, 0x20])
|
|
52
|
+
target = r["targets"][0]
|
|
53
|
+
self.assertTrue(target["reached"])
|
|
54
|
+
self.assertEqual(target["calls"], 2)
|
|
55
|
+
self.assertEqual(target["routine"], 0x28)
|
|
56
|
+
# Both chains have two calls; the report gives one and every route passes only the start and 0028.
|
|
57
|
+
self.assertEqual(target["throughEveryRoute"], [0x0])
|
|
58
|
+
self.assertEqual(r["reachedRoutines"], [0x0, 0x0B, 0x18, 0x28])
|
|
59
|
+
self.assertEqual(r["counts"]["routines"], 4)
|
|
60
|
+
# The far call through memory is listed with its operand, never followed.
|
|
61
|
+
self.assertEqual([(u["site"], u["kind"], u["routine"]) for u in r["unresolved"]], [(0x6, "call", 0x0)])
|
|
62
|
+
self.assertIn("[0x200]", r["unresolved"][0]["instruction"])
|
|
63
|
+
self.assertFalse(r["negativeUsable"])
|
|
64
|
+
self.assertEqual(r["controls"], [{"site": 0x3, "target": 0x18}, {"site": 0x20, "target": 0x28}])
|
|
65
|
+
|
|
66
|
+
def test_a_leaf_is_reached_unread_and_its_reason_is_repeated(self):
|
|
67
|
+
reason = "synthetic: returns before any call while its flag holds its start value"
|
|
68
|
+
r = reach(indirectJumps=[TABLE], leaves=[{"routine": 0x18, "reason": reason}])
|
|
69
|
+
target = r["targets"][0]
|
|
70
|
+
self.assertEqual([h.get("callSite") for h in target["chain"]], [None, 0x0, 0x20])
|
|
71
|
+
self.assertEqual([h["routine"] for h in target["chain"]], [0x0, 0x0B, 0x28])
|
|
72
|
+
self.assertEqual(target["route"]["declaredTableJumps"], [{"site": 0x12, "target": 0x20}])
|
|
73
|
+
# Only the table route is left, so 000B is on every route; 0018 is reached but its call is not read.
|
|
74
|
+
self.assertEqual(target["throughEveryRoute"], [0x0, 0x0B])
|
|
75
|
+
self.assertEqual(r["leaves"], [{"routine": 0x18, "reason": reason, "reached": True, "callSites": [0x3]}])
|
|
76
|
+
self.assertNotIn(0x18, [u["site"] for u in r["unresolved"]])
|
|
77
|
+
|
|
78
|
+
def test_an_undeclared_table_jump_is_unresolved_and_no_table_word_is_read(self):
|
|
79
|
+
r = reach(leaves=[{"routine": 0x18, "reason": "synthetic leaf"}])
|
|
80
|
+
target = r["targets"][0]
|
|
81
|
+
self.assertFalse(target["reached"])
|
|
82
|
+
self.assertEqual(target["status"], "not reached")
|
|
83
|
+
self.assertEqual([u["site"] for u in r["unresolved"]], [0x6, 0x12])
|
|
84
|
+
self.assertEqual(r["unresolved"][1]["routine"], 0x0B)
|
|
85
|
+
self.assertNotIn(0x20, r["reachedRoutines"])
|
|
86
|
+
self.assertFalse(r["negativeUsable"])
|
|
87
|
+
|
|
88
|
+
def test_a_leaf_start_inside_a_reached_instruction_is_a_gap(self):
|
|
89
|
+
# 0000 calls 0007, which jumps through a one-row table to 0005, inside the mov at 0003 (the return site).
|
|
90
|
+
data = bytes.fromhex("e80400" "b890c3" "c3" "2effa71000" "90909090" "0500")
|
|
91
|
+
table = {"site": 7, "exhaustive": True, "evidence": "synthetic: one row",
|
|
92
|
+
"table": {"start": 0x10, "count": 1, "stride": 2, "evidence": "synthetic: one row"}}
|
|
93
|
+
r = run_report(data, config(data, targets=[5], controls=[0], indirectJumps=[table],
|
|
94
|
+
leaves=[{"routine": 5, "reason": "synthetic leaf"}]), "reach")
|
|
95
|
+
self.assertIn({"site": 5, "reason": "leaf start inside a reached instruction; the leaf is not decoded, so its "
|
|
96
|
+
"boundary is unchecked", "insideInstruction": 3}, r["gaps"])
|
|
97
|
+
self.assertFalse(r["negativeUsable"])
|
|
98
|
+
|
|
99
|
+
def test_a_negative_is_usable_only_with_controls_and_nothing_unresolved(self):
|
|
100
|
+
# 0000 calls 0004, which returns; nothing reaches 0005.
|
|
101
|
+
data = bytes.fromhex("e80100c3c3c3")
|
|
102
|
+
r = run_report(data, config(data, starts=[0], targets=[5], controls=[0]), "reach")
|
|
103
|
+
self.assertFalse(r["targets"][0]["reached"])
|
|
104
|
+
self.assertTrue(r["negativeUsable"])
|
|
105
|
+
r = run_report(data, config(data, starts=[0], targets=[5]), "reach")
|
|
106
|
+
self.assertFalse(r["negativeUsable"])
|
|
107
|
+
|
|
108
|
+
def test_a_target_inside_a_reached_instruction_is_not_reached(self):
|
|
109
|
+
r = reach(indirectJumps=[TABLE], targets=[0x29])
|
|
110
|
+
self.assertEqual(r["targets"][0]["status"], "inside a reached instruction")
|
|
111
|
+
self.assertEqual(r["targets"][0]["insideInstruction"], 0x28)
|
|
112
|
+
|
|
113
|
+
def test_an_interrupt_is_continued_and_listed_and_the_route_names_it(self):
|
|
114
|
+
# 0000 int 21h; call 0006; ret. 0006 is the target.
|
|
115
|
+
data = bytes.fromhex("cd21e80100c3c3")
|
|
116
|
+
r = run_report(data, config(data, targets=[6]), "reach")
|
|
117
|
+
target = r["targets"][0]
|
|
118
|
+
self.assertTrue(target["reached"])
|
|
119
|
+
self.assertEqual(target["route"]["interruptsContinued"], [0])
|
|
120
|
+
self.assertEqual([(i["site"], i["vector"]) for i in r["interrupts"]], [(0, 0x21)])
|
|
121
|
+
|
|
122
|
+
def test_a_route_past_a_returning_call_names_the_assumed_return(self):
|
|
123
|
+
r = reach(indirectJumps=[TABLE], targets=[0x18])
|
|
124
|
+
self.assertEqual(r["targets"][0]["route"]["assumedReturns"], [0x0])
|
|
125
|
+
self.assertEqual(r["targets"][0]["chain"], [{"routine": 0x0}, {"callSite": 0x3, "routine": 0x18}])
|
|
126
|
+
|
|
127
|
+
def test_an_unrelocated_far_call_is_unresolved(self):
|
|
128
|
+
data = bytes.fromhex("9a00000010c3")
|
|
129
|
+
r = run_report(data, config(data, targets=[5]), "reach")
|
|
130
|
+
self.assertEqual(r["unresolved"][0]["reason"], "no declared relocation/fixup")
|
|
131
|
+
|
|
132
|
+
def test_an_unsupported_return_is_unresolved_as_a_return(self):
|
|
133
|
+
# 0000 calls 0004, an o32 ret: an operand-size override the frame model does not cover.
|
|
134
|
+
data = bytes.fromhex("e80100c366c3")
|
|
135
|
+
r = run_report(data, config(data, targets=[3], controls=[0]), "reach")
|
|
136
|
+
self.assertEqual([(u["site"], u["kind"], u["routine"]) for u in r["unresolved"]], [(4, "return", 4)])
|
|
137
|
+
self.assertEqual(r["gaps"], [])
|
|
138
|
+
self.assertFalse(r["negativeUsable"])
|
|
139
|
+
|
|
140
|
+
def test_an_undecodable_edge_is_a_gap(self):
|
|
141
|
+
data = bytes.fromhex("e80100c30f")
|
|
142
|
+
r = run_report(data, config(data, targets=[3]), "reach")
|
|
143
|
+
self.assertEqual(r["gaps"], [{"site": 4, "reason": "undecoded or unmapped edge"}])
|
|
144
|
+
self.assertFalse(r["negativeUsable"])
|
|
145
|
+
|
|
146
|
+
def test_the_instruction_limit_is_a_gap(self):
|
|
147
|
+
r = reach(indirectJumps=[TABLE], instructionLimit=3)
|
|
148
|
+
self.assertIn("instruction limit", [g["reason"] for g in r["gaps"]])
|
|
149
|
+
self.assertFalse(r["negativeUsable"])
|
|
150
|
+
|
|
151
|
+
def test_the_result_limit_truncates_lists_and_keeps_counts(self):
|
|
152
|
+
data = bytes.fromhex("ffd0ffd3c3") # call ax; call bx; ret
|
|
153
|
+
r = run_report(data, config(data, targets=[4], limit=1), "reach")
|
|
154
|
+
self.assertEqual(len(r["unresolved"]), 1)
|
|
155
|
+
self.assertEqual(r["counts"]["unresolved"], 2)
|
|
156
|
+
self.assertTrue(r["truncated"])
|
|
157
|
+
|
|
158
|
+
def test_rejected_inputs(self):
|
|
159
|
+
for extra, message in [({"starts": [0x18]}, "established region entry"),
|
|
160
|
+
({"starts": []}, "starts must be"),
|
|
161
|
+
({"targets": [0x1000]}, "targets"),
|
|
162
|
+
({"leaves": [{"routine": 0x18}]}, "routine and reason"),
|
|
163
|
+
({"leaves": [{"routine": 0x18, "reason": " "}]}, "nonempty reason"),
|
|
164
|
+
({"leaves": [{"routine": 0, "reason": "x"}]}, "start cannot be a leaf"),
|
|
165
|
+
({"controls": [0x3, 0x3]}, "distinct file offsets"),
|
|
166
|
+
({"controls": [0x6]}, "Positive control 6 missed"),
|
|
167
|
+
({"controls": [0x10]}, "Positive control 16 missed")]:
|
|
168
|
+
with self.subTest(extra=extra), self.assertRaisesRegex(ValueError, message):
|
|
169
|
+
reach(**extra)
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
if __name__ == "__main__":
|
|
173
|
+
unittest.main()
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
"""A value past the term limit stops its own path; the other paths and their controls stay."""
|
|
2
|
+
import copy
|
|
3
|
+
import pickle
|
|
4
|
+
import unittest
|
|
5
|
+
from test_x86 import Code, report
|
|
6
|
+
from scientific_method_engine.x86.relational import probe_memory
|
|
7
|
+
from scientific_method_engine.x86.values import TERM_LIMIT, TermLimit, Value, const, op
|
|
8
|
+
|
|
9
|
+
FRAME = {"ds": 0x3000, "ss": 0x9000, "sp": 0xE000}
|
|
10
|
+
STOP = f"expression term limit: a value's expression would hold more than {TERM_LIMIT} terms; narrow the query"
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def additions(count):
|
|
14
|
+
"""AX and BX load unknown words; a zero AX skips ``count`` additions of BX into AX."""
|
|
15
|
+
c = Code().emit("a1 00 01 8b 1e 02 01").label("test").emit("85 c0 0f 84")
|
|
16
|
+
c.fixups.append((len(c.data), 2, "done"))
|
|
17
|
+
c.data.extend(bytes(2))
|
|
18
|
+
c.label("adds")
|
|
19
|
+
for _ in range(count):
|
|
20
|
+
c.emit("01 d8")
|
|
21
|
+
return c.label("done").emit("cb")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def run(count, **extra):
|
|
25
|
+
return report(additions(count), "trace", **{"returnBytes": 4, "registers": FRAME, "maxPaths": 2, "maxSteps": count + 16, **extra})
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class TermLimitTests(unittest.TestCase):
|
|
29
|
+
def test_a_short_sum_returns_on_both_paths(self):
|
|
30
|
+
r = run(8)
|
|
31
|
+
self.assertEqual([p["returned"] for p in r["paths"]], [True, True])
|
|
32
|
+
self.assertTrue(r["completeWithinModel"])
|
|
33
|
+
|
|
34
|
+
def test_a_value_past_the_limit_stops_its_path_and_keeps_the_other(self):
|
|
35
|
+
c = additions(600)
|
|
36
|
+
r = run(600)
|
|
37
|
+
returned, stopped = r["paths"]
|
|
38
|
+
self.assertTrue(returned["returned"])
|
|
39
|
+
self.assertIsNone(returned["stop"])
|
|
40
|
+
self.assertEqual(returned["events"][-1]["kind"], "return")
|
|
41
|
+
self.assertFalse(stopped["returned"])
|
|
42
|
+
self.assertEqual(stopped["stop"], STOP)
|
|
43
|
+
# The stop names the addition that would have built the value, and every earlier addition keeps its event.
|
|
44
|
+
site = stopped["stopSite"]
|
|
45
|
+
self.assertGreater(site, c.labels["adds"])
|
|
46
|
+
self.assertEqual((site - c.labels["adds"]) % 2, 0)
|
|
47
|
+
sums = [e for e in stopped["events"] if e["kind"] == "arithmetic"]
|
|
48
|
+
self.assertEqual(len(sums), (site - c.labels["adds"]) // 2)
|
|
49
|
+
self.assertEqual(sums[-1]["site"], site - 2)
|
|
50
|
+
self.assertNotIn(site, [e["site"] for e in stopped["events"]])
|
|
51
|
+
# The steps were not spent, so the stop is not a step limit, and no path limit is recorded.
|
|
52
|
+
self.assertLess(stopped["steps"], 600 + 16)
|
|
53
|
+
self.assertEqual(r["gaps"], [])
|
|
54
|
+
self.assertFalse(r["completeWithinModel"])
|
|
55
|
+
|
|
56
|
+
def test_controls_reached_before_the_stop_are_kept(self):
|
|
57
|
+
c = additions(600)
|
|
58
|
+
tested = {"name": "tested", "kind": "reach", "at": {"site": c.labels["test"]}, "expect": "always"}
|
|
59
|
+
result = run(600, relationalControls=[tested])["relationalControls"]["controls"][0]
|
|
60
|
+
self.assertEqual(result["verdict"], "held")
|
|
61
|
+
self.assertEqual(result["occurrences"], 2)
|
|
62
|
+
self.assertEqual([p["stop"] for p in result["paths"]], [None, STOP])
|
|
63
|
+
|
|
64
|
+
def test_a_control_past_the_stop_stays_undecided(self):
|
|
65
|
+
c = additions(600)
|
|
66
|
+
done = {"name": "done", "kind": "reach", "at": {"site": c.labels["done"]}, "expect": "always"}
|
|
67
|
+
result = run(600, relationalControls=[done])["relationalControls"]["controls"][0]
|
|
68
|
+
self.assertEqual(result["verdict"], "undecided")
|
|
69
|
+
self.assertEqual(sorted(p["verdict"] for p in result["paths"]), ["held", "undecided"])
|
|
70
|
+
|
|
71
|
+
def test_a_query_error_inside_a_path_still_fails_the_run(self):
|
|
72
|
+
# A four-byte model on a near call without an encoded PUSH CS is an error in the query.
|
|
73
|
+
c = Code().branch("e8", "next").label("next").emit("cb")
|
|
74
|
+
model = [{"site": 0, "evidence": "synthetic model", "returnBytes": 4, "cases": [{}]}]
|
|
75
|
+
with self.assertRaisesRegex(ValueError, "Modeled return width differs"):
|
|
76
|
+
report(c, "trace", returnBytes=4, registers=FRAME, callModels=model)
|
|
77
|
+
|
|
78
|
+
def test_a_memory_probe_past_the_limit_is_unresolved(self):
|
|
79
|
+
# A probe observes the path, so a base too large to offset leaves its row unresolved.
|
|
80
|
+
# Two terms, then two per addition: a base of TERM_LIMIT terms, which the displacement's
|
|
81
|
+
# offset term takes past the limit.
|
|
82
|
+
term = ("neg", ("unknown", "x"))
|
|
83
|
+
for _ in range((TERM_LIMIT - 2) // 2):
|
|
84
|
+
term = ("add", term, ("unknown", "y"))
|
|
85
|
+
Value(16, term)
|
|
86
|
+
|
|
87
|
+
class Probed:
|
|
88
|
+
bits = 16
|
|
89
|
+
|
|
90
|
+
def segment(self, name):
|
|
91
|
+
return const(0x3000, 16)
|
|
92
|
+
|
|
93
|
+
def reg(self, name):
|
|
94
|
+
return Value(16, term)
|
|
95
|
+
|
|
96
|
+
def keys(self, segment, offset, width):
|
|
97
|
+
raise AssertionError("the offset cannot be formed")
|
|
98
|
+
|
|
99
|
+
address = {"segment": "ds", "base": "bx", "displacement": 2, "width": 2}
|
|
100
|
+
row = probe_memory(Probed(), "probe", address)
|
|
101
|
+
self.assertEqual(row["unresolved"], STOP)
|
|
102
|
+
self.assertIsNone(row["offset"])
|
|
103
|
+
self.assertNotIn("byteProducers", row)
|
|
104
|
+
|
|
105
|
+
def test_the_error_survives_copy_and_pickle(self):
|
|
106
|
+
for rebuilt in (copy.copy(TermLimit()), pickle.loads(pickle.dumps(TermLimit()))):
|
|
107
|
+
self.assertIsInstance(rebuilt, TermLimit)
|
|
108
|
+
self.assertEqual(str(rebuilt), STOP)
|
|
109
|
+
|
|
110
|
+
def test_the_limit_outside_a_path_raises(self):
|
|
111
|
+
# Outside a traced path nothing can stop, so the limit fails the run as a ValueError.
|
|
112
|
+
value = const(1, 16)
|
|
113
|
+
with self.assertRaisesRegex(TermLimit, "term limit"):
|
|
114
|
+
for _ in range(TERM_LIMIT):
|
|
115
|
+
value = op("add", value, Value(16, ("unknown", "x")))
|
|
116
|
+
self.assertTrue(issubclass(TermLimit, ValueError))
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
if __name__ == "__main__":
|
|
120
|
+
unittest.main()
|
|
@@ -2523,8 +2523,10 @@ class ReporterTests(unittest.TestCase):
|
|
|
2523
2523
|
self.assertEqual(b["paths"][0]["registers"]["eax"]["value"], 0xffff8080)
|
|
2524
2524
|
|
|
2525
2525
|
def test_symbolic_growth_is_bounded(self):
|
|
2526
|
-
|
|
2527
|
-
|
|
2526
|
+
# test_term_limit.py covers the stop beside other paths.
|
|
2527
|
+
path = report("01 d8 " * 200 + "c3")["paths"][0]
|
|
2528
|
+
self.assertFalse(path["returned"])
|
|
2529
|
+
self.assertTrue(path["stop"].startswith("expression term limit"))
|
|
2528
2530
|
|
|
2529
2531
|
|
|
2530
2532
|
def test_dispatch_rejects_wrong_layout_and_reports_index_overrun(self):
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_effect_order.py
RENAMED
|
File without changes
|
{scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_enter_frames.py
RENAMED
|
File without changes
|
{scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_entry_frame.py
RENAMED
|
File without changes
|
|
File without changes
|
{scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_interrupt_models.py
RENAMED
|
File without changes
|
|
File without changes
|
{scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_memory_scopes.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_return_checks.py
RENAMED
|
File without changes
|
{scientific_method_engine-13.0.0 → scientific_method_engine-13.2.0}/tests/test_successor_rule.py
RENAMED
|
File without changes
|
|
File without changes
|