scientific-method-engine 9.1.0__tar.gz → 10.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/PKG-INFO +9 -1
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/README.md +8 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/pyproject.toml +1 -1
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/effect_order.py +1 -1
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/image.py +55 -3
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/reports.py +5 -2
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/trace.py +72 -3
- scientific_method_engine-10.0.0/tests/test_indirect_far_transfers.py +351 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_oracle.py +19 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/.gitignore +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/LICENSE +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/__init__.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/__main__.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/cli.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/__init__.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/loops.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/machine.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/pcode.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/pe.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/relational.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/src/scientific_method_engine/x86/values.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/oracle.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_continuation_budget.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_dispatch.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_effect_order.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_entry_frame.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_interrupt_models.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_loops.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_memory_scopes.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_nested_frame_request.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_pe.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_relational_controls.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_successor_rule.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_table_continuations.py +0 -0
- {scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_x86.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: scientific-method-engine
|
|
3
|
-
Version:
|
|
3
|
+
Version: 10.0.0
|
|
4
4
|
Summary: Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code.
|
|
5
5
|
Project-URL: Source, https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine
|
|
6
6
|
Author: kibertoad
|
|
@@ -145,6 +145,14 @@ boundary and continuation limits remain explicit gaps or stops. Partial-table sp
|
|
|
145
145
|
partial evidence, never complete dispatch or native-reachability claims. See the
|
|
146
146
|
[table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).
|
|
147
147
|
|
|
148
|
+
A far call or jump through an `m16:16` pointer is followed when the path stored both words and
|
|
149
|
+
the address names declared code through one region's exact mapping, or names a source FBOV
|
|
150
|
+
trampoline whose overlay entry is declared. The event keeps the pointer read, each word's
|
|
151
|
+
producers and writers, and how the target was admitted. An unknown or partly unknown word, an
|
|
152
|
+
address outside declared code, a segment alias of resident code, an overlay's analysis segment and
|
|
153
|
+
an `m16:32` pointer stop the path with a named reason. See
|
|
154
|
+
[indirect far transfers](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#indirect-far-transfers-through-a-traced-pointer).
|
|
155
|
+
|
|
148
156
|
A call model may also sit at an `INT n` instruction in the real-mode model. The interrupt is
|
|
149
157
|
still reported as a hardware boundary with its vector, the handler is not executed, and each case
|
|
150
158
|
returns to the next instruction with SP and CS as before the interrupt. Registers, flags and memory
|
|
@@ -129,6 +129,14 @@ boundary and continuation limits remain explicit gaps or stops. Partial-table sp
|
|
|
129
129
|
partial evidence, never complete dispatch or native-reachability claims. See the
|
|
130
130
|
[table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).
|
|
131
131
|
|
|
132
|
+
A far call or jump through an `m16:16` pointer is followed when the path stored both words and
|
|
133
|
+
the address names declared code through one region's exact mapping, or names a source FBOV
|
|
134
|
+
trampoline whose overlay entry is declared. The event keeps the pointer read, each word's
|
|
135
|
+
producers and writers, and how the target was admitted. An unknown or partly unknown word, an
|
|
136
|
+
address outside declared code, a segment alias of resident code, an overlay's analysis segment and
|
|
137
|
+
an `m16:32` pointer stop the path with a named reason. See
|
|
138
|
+
[indirect far transfers](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#indirect-far-transfers-through-a-traced-pointer).
|
|
139
|
+
|
|
132
140
|
A call model may also sit at an `INT n` instruction in the real-mode model. The interrupt is
|
|
133
141
|
still reported as a hardware boundary with its vector, the handler is not executed, and each case
|
|
134
142
|
returns to the next instruction with SP and CS as before the interrupt. Registers, flags and memory
|
|
@@ -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 = "
|
|
8
|
+
version = "10.0.0"
|
|
9
9
|
description = "Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code."
|
|
10
10
|
readme = "README.md"
|
|
11
11
|
requires-python = ">=3.12"
|
|
@@ -4,7 +4,7 @@ from bisect import bisect_right
|
|
|
4
4
|
from .memory_scopes import model_scopes, without_scopes
|
|
5
5
|
|
|
6
6
|
|
|
7
|
-
KINDS = {"read", "write", "call", "call-return", "return", "branch", "compare", "flag-assumption",
|
|
7
|
+
KINDS = {"read", "write", "call", "far-jump", "call-return", "return", "branch", "compare", "flag-assumption",
|
|
8
8
|
"arithmetic", "value-transfer", "conversion", "flag-write", "flags-save", "flags-restore", "local-iret", "string-operation", "declared-jump-continuation",
|
|
9
9
|
"hardware-boundary"}
|
|
10
10
|
|
|
@@ -3,6 +3,7 @@ import re
|
|
|
3
3
|
from pathlib import Path
|
|
4
4
|
import xxhash
|
|
5
5
|
from capstone import Cs, CS_ARCH_X86, CS_MODE_16, CS_MODE_32
|
|
6
|
+
from capstone.x86 import X86_OP_MEM
|
|
6
7
|
from .pe import prepare_pe
|
|
7
8
|
import capstone
|
|
8
9
|
|
|
@@ -109,6 +110,8 @@ class Image:
|
|
|
109
110
|
self.decoder = Cs(CS_ARCH_X86, CS_MODE_32 if self.flat else CS_MODE_16)
|
|
110
111
|
self.decoder.detail = True
|
|
111
112
|
self.cache = {}
|
|
113
|
+
# overlayExports rows by trampoline site, built on the first far_pointer_target call.
|
|
114
|
+
self.trampoline_rows = None
|
|
112
115
|
self.relocations = config.get("relocations", [])
|
|
113
116
|
if not isinstance(self.relocations, list) or len(self.relocations) > 100000:
|
|
114
117
|
raise ValueError("Invalid relocation metadata")
|
|
@@ -125,10 +128,13 @@ class Image:
|
|
|
125
128
|
def region(self, site):
|
|
126
129
|
return next((r for r in self.regions if r["start"] <= site < r["end"]), None)
|
|
127
130
|
|
|
131
|
+
def mapped_region(self, segment, ip):
|
|
132
|
+
"""The region whose declared mapping covers ``segment:ip`` exactly, or None. At most one does."""
|
|
133
|
+
return next((r for r in self.regions if r["segment"] == segment and r["ip"] <= ip < r["ip"] + r["end"] - r["start"]), None)
|
|
134
|
+
|
|
128
135
|
def offset(self, segment, ip):
|
|
129
|
-
|
|
130
|
-
if
|
|
131
|
-
r = exact[0]
|
|
136
|
+
r = self.mapped_region(segment, ip)
|
|
137
|
+
if r is not None:
|
|
132
138
|
return r["start"] + ip - r["ip"]
|
|
133
139
|
if self.flat:
|
|
134
140
|
return None
|
|
@@ -157,6 +163,10 @@ class Image:
|
|
|
157
163
|
def far_target(self, site, ins):
|
|
158
164
|
if self.flat:
|
|
159
165
|
return None, {"reason": "far transfer is outside the PE32 flat model"}
|
|
166
|
+
if ins.operands and ins.operands[0].type == X86_OP_MEM:
|
|
167
|
+
# The pointer is read from memory when the instruction runs; only a traced path knows it
|
|
168
|
+
# (far_pointer_target).
|
|
169
|
+
return None, {"reason": "computed transfer remains unresolved"}
|
|
160
170
|
# ptr16:16 immediate only. Operand-size-prefixed far calls are unsupported.
|
|
161
171
|
if ins.size != 5 or self.data[site] not in (0x9a, 0xea):
|
|
162
172
|
return None, {"reason": "unsupported far transfer encoding"}
|
|
@@ -170,6 +180,48 @@ class Image:
|
|
|
170
180
|
target = integer(fixup["target"], 0, len(self.data) - 1, "canonical target")
|
|
171
181
|
return target, {"rawSegment": raw, "offset": ip, "resolvedSegment": fixup["segment"], "relocation": fixup}
|
|
172
182
|
|
|
183
|
+
def far_pointer_target(self, segment, offset):
|
|
184
|
+
"""The code a known ``segment:offset`` far pointer names, as ``(target, admission)``.
|
|
185
|
+
|
|
186
|
+
The pointer is admitted only through the exact declared mapping of one region: ``segment``
|
|
187
|
+
equals the region's segment and ``offset`` lies in its IP range. A region with a
|
|
188
|
+
``container`` is an overlay's analysis view, whose segment is not a load address, so a
|
|
189
|
+
pointer that names it is refused. So is a pointer that reaches declared resident code only
|
|
190
|
+
through another segment (a canonical alias), because the code would then run under a CS
|
|
191
|
+
and IP the region's mapping does not describe. A pointer at a source FBOV trampoline
|
|
192
|
+
(``overlayExports``) continues at that trampoline's overlay entry, as an immediate far
|
|
193
|
+
transfer through a relocated trampoline does. Returns ``(None, {"reason": ...})`` when the
|
|
194
|
+
pointer is not admitted.
|
|
195
|
+
"""
|
|
196
|
+
region = self.mapped_region(segment, offset)
|
|
197
|
+
if region is None:
|
|
198
|
+
if self.offset(segment, offset) is not None:
|
|
199
|
+
return None, {"reason": "far pointer names declared resident code only through a segment alias of its mapping"}
|
|
200
|
+
return None, {"reason": "far pointer names no declared code region"}
|
|
201
|
+
if region.get("container") is not None:
|
|
202
|
+
return None, {"reason": "far pointer names overlay code by its analysis segment, which is not a load address",
|
|
203
|
+
"region": region["name"]}
|
|
204
|
+
site = region["start"] + offset - region["ip"]
|
|
205
|
+
admission = {"rule": "exact declared region mapping", "region": region["name"], "regionSegment": region["segment"],
|
|
206
|
+
"regionIp": region["ip"], "regionStart": region["start"], "regionEvidence": region["evidence"]}
|
|
207
|
+
if self.trampoline_rows is None:
|
|
208
|
+
# Indexed once: a traced path can take many indirect far transfers, and the source FBOV
|
|
209
|
+
# tables can list thousands of trampolines.
|
|
210
|
+
self.trampoline_rows = {}
|
|
211
|
+
for row in self.config.get("overlayExports", []):
|
|
212
|
+
if isinstance(row, dict):
|
|
213
|
+
self.trampoline_rows.setdefault(row.get("trampoline"), []).append(row)
|
|
214
|
+
exports = self.trampoline_rows.get(site, [])
|
|
215
|
+
if not exports:
|
|
216
|
+
return site, admission
|
|
217
|
+
if len(exports) > 1 or type(exports[0].get("entry")) is not int:
|
|
218
|
+
return None, {**admission, "reason": "far pointer names an FBOV trampoline without one overlay entry"}
|
|
219
|
+
export = exports[0]
|
|
220
|
+
admission["trampoline"] = {k: export.get(k) for k in ("trampoline", "descriptor", "entry", "evidence")}
|
|
221
|
+
if self.region(export["entry"]) is None:
|
|
222
|
+
return None, {**admission, "reason": "the overlay entry the FBOV trampoline names lies outside declared code regions"}
|
|
223
|
+
return export["entry"], admission
|
|
224
|
+
|
|
173
225
|
def file_offset(self, va, width=1):
|
|
174
226
|
"""Only loaded raw PE bytes; zero-fill and alignment padding are not source extents."""
|
|
175
227
|
metadata = self.config.get("peMetadata")
|
|
@@ -1770,16 +1770,19 @@ def _run_report(image, config, command):
|
|
|
1770
1770
|
if command == "returns":
|
|
1771
1771
|
report = return_flows(report, config)
|
|
1772
1772
|
if command != "trace":
|
|
1773
|
-
kinds = {"arguments": ("address-formation", "read", "call", "call-return"), "effects": ("address-formation", "write", "call", "call-return", "return", "branch", "string-operation", "hardware-boundary",
|
|
1773
|
+
kinds = {"arguments": ("address-formation", "read", "call", "call-return"), "effects": ("address-formation", "write", "call", "far-jump", "call-return", "return", "branch", "string-operation", "hardware-boundary",
|
|
1774
1774
|
"flag-assumption", "flag-write", "flags-save", "flags-restore", "local-iret"),
|
|
1775
1775
|
"returns": ("return", "call-return", "compare", "branch", "write"),
|
|
1776
|
-
"guards": ("compare", "branch", "read", "write", "call", "call-return"),
|
|
1776
|
+
"guards": ("compare", "branch", "read", "write", "call", "far-jump", "call-return"),
|
|
1777
1777
|
"memory": ("read", "write", "address-formation")}[command]
|
|
1778
1778
|
for path in report["paths"]:
|
|
1779
1779
|
# Returns keep the transfers, conversions and reads that depend on a declared result.
|
|
1780
1780
|
consumed = {c["order"] for f in path.get("returnFlows", {}).get("results", ()) for c in f["consumers"]}
|
|
1781
1781
|
# Arguments keeps the writes its argument-frame slots cite as writers.
|
|
1782
1782
|
consumed |= {s["writerOrder"] for f in path.get("argumentFrames", ()) for s in f["slots"] if s["writerSite"] is not None}
|
|
1783
|
+
# A kept indirect far CALL or JMP keeps the pointer read its provenance cites.
|
|
1784
|
+
consumed |= {e["provenance"]["pointerRead"]["order"] for e in path["events"] if e["kind"] in kinds
|
|
1785
|
+
and isinstance(e.get("provenance"), dict) and "pointerRead" in e["provenance"]}
|
|
1783
1786
|
path["events"] = [e for e in path["events"] if e["kind"] in kinds or e["order"] in consumed or
|
|
1784
1787
|
(command == "effects" and e["kind"] == "read" and (e.get("nearPointerAccessCandidates") or e.get("nearPointerArgumentCandidates")))]
|
|
1785
1788
|
return report
|
|
@@ -6,7 +6,7 @@ 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,
|
|
9
|
+
from .values import const, unknown, sources, op, join
|
|
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
|
|
@@ -22,6 +22,63 @@ def call_target(image, site, ins):
|
|
|
22
22
|
return None, {"reason": "computed transfer remains unresolved"}
|
|
23
23
|
|
|
24
24
|
|
|
25
|
+
def far_pointer_word(state, read, low):
|
|
26
|
+
"""One word of the far pointer ``read`` has just fetched, as ``(row, word)``.
|
|
27
|
+
|
|
28
|
+
``row`` reports the word's value and the producers and writers of its two bytes. ``word`` is the
|
|
29
|
+
modeled value of those bytes with all their sources, including the markers of declared return
|
|
30
|
+
results that ``producers`` leaves out, or None when a byte has no modeled value.
|
|
31
|
+
"""
|
|
32
|
+
rows = read["byteProducers"][low // 8:low // 8 + 2]
|
|
33
|
+
interval = read["interval"]
|
|
34
|
+
seg, base, start = interval["segment"], interval["base"], interval["start"]
|
|
35
|
+
keys = [(seg, base, start + i if seg == ("linear",) else (start + i) % (1 << state.bits))
|
|
36
|
+
for i in (low // 8, low // 8 + 1)]
|
|
37
|
+
word = join([state.memory[key] for key in keys]) if all(key in state.memory for key in keys) else None
|
|
38
|
+
return ({"value": None if word is None else word.number,
|
|
39
|
+
"producers": sorted({p for row in rows for p in row["producers"]}), "bytes": rows}, word)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def far_pointer_transfer(state, image):
|
|
43
|
+
"""Resolve an indirect far CALL or JMP from the m16:16 pointer the trace has just read.
|
|
44
|
+
|
|
45
|
+
Called right after ``state.get`` read the operand, so the newest event is that read; any other
|
|
46
|
+
newest event is an engine error, so the provenance never cites the wrong event. Returns
|
|
47
|
+
``(target, provenance, code_segment)``. ``provenance`` keeps the read's order and address, its
|
|
48
|
+
effective segment register, and both words with the producers and writers of their bytes. The
|
|
49
|
+
target is admitted only when both words are known and ``Image.far_pointer_target`` admits the
|
|
50
|
+
address they form; otherwise ``target`` and ``code_segment`` are None and ``provenance`` names
|
|
51
|
+
the reason. ``code_segment`` is the value CS takes: the segment word with every source of its
|
|
52
|
+
bytes (declared return results included), or the overlay
|
|
53
|
+
entry region's segment when the pointer names an FBOV trampoline.
|
|
54
|
+
"""
|
|
55
|
+
read = state.events[-1]
|
|
56
|
+
if read["kind"] != "read" or read["site"] != state.at or read["width"] != 4:
|
|
57
|
+
raise RuntimeError("an indirect far transfer needs its own m16:16 read as the newest event")
|
|
58
|
+
(offset_word, _), (segment_word, segment_value) = far_pointer_word(state, read, 0), far_pointer_word(state, read, 16)
|
|
59
|
+
provenance = {"encoding": "m16:16",
|
|
60
|
+
"pointerRead": {"order": read["order"], "segment": read["segment"], "offset": read["offset"],
|
|
61
|
+
"segmentRegister": read["effectiveSegmentRegister"]},
|
|
62
|
+
"offsetWord": offset_word, "segmentWord": segment_word}
|
|
63
|
+
unknown_words = [name for name, word in (("offset", offset_word), ("segment", segment_word)) if word["value"] is None]
|
|
64
|
+
if unknown_words:
|
|
65
|
+
provenance["reason"] = "far pointer " + " and ".join(unknown_words) + (" words" if len(unknown_words) > 1 else " word") + " unknown"
|
|
66
|
+
return None, provenance, None
|
|
67
|
+
provenance["loadedAddress"] = f"{segment_word['value']:04X}:{offset_word['value']:04X}"
|
|
68
|
+
target, admission = image.far_pointer_target(segment_word["value"], offset_word["value"])
|
|
69
|
+
admission = dict(admission)
|
|
70
|
+
reason = admission.pop("reason", None)
|
|
71
|
+
provenance["admission"] = admission
|
|
72
|
+
if target is None:
|
|
73
|
+
provenance["reason"] = reason
|
|
74
|
+
return None, provenance, None
|
|
75
|
+
if "trampoline" in admission:
|
|
76
|
+
return target, provenance, const(image.region(target)["segment"], 16, state.at)
|
|
77
|
+
# CS keeps every source of the segment word's bytes, so a declared result stored there stays a
|
|
78
|
+
# result origin of CS.
|
|
79
|
+
return target, provenance, segment_value
|
|
80
|
+
|
|
81
|
+
|
|
25
82
|
OVERLAP_REASON = "overlapping entry-path instructions; boundary unresolved"
|
|
26
83
|
RETURNS = {"ret": "near return", "retf": "far return", "iret": "interrupt return", "iretd": "interrupt return"}
|
|
27
84
|
INTERRUPTS = ("int", "int1", "int3", "into")
|
|
@@ -806,9 +863,11 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
806
863
|
break
|
|
807
864
|
if m in ("call", "lcall"):
|
|
808
865
|
target, provenance = call_target(image, at, ins)
|
|
809
|
-
indirect_value = None
|
|
866
|
+
indirect_value = code_segment = None
|
|
810
867
|
if target is None and ins.operands and ins.operands[0].type in (X86_OP_REG, X86_OP_MEM):
|
|
811
868
|
indirect_value = state.get(ins, ins.operands[0], image)
|
|
869
|
+
if m == "lcall":
|
|
870
|
+
target, provenance, code_segment = far_pointer_transfer(state, image)
|
|
812
871
|
guard_checks = []
|
|
813
872
|
if indirect_value is not None:
|
|
814
873
|
for g in state.guards:
|
|
@@ -874,7 +933,8 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
874
933
|
"continuation": following, "returnIP": return_ip, "callSite": at,
|
|
875
934
|
"callerCS": state.reg("cs"), "localFlagsFrame": flags_frame})
|
|
876
935
|
if m == "lcall":
|
|
877
|
-
|
|
936
|
+
# An indirect far call loads CS from the pointer's segment word (far_pointer_transfer).
|
|
937
|
+
state.setreg("cs", const(target_region["segment"], 16, at) if code_segment is None else code_segment, at)
|
|
878
938
|
state.at = target
|
|
879
939
|
continue
|
|
880
940
|
if m in ("iret", "iretd"):
|
|
@@ -927,6 +987,15 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
927
987
|
continue
|
|
928
988
|
if m in ("jmp", "ljmp"):
|
|
929
989
|
target, provenance = call_target(image, at, ins)
|
|
990
|
+
if target is None and m == "ljmp" and ins.operands[0].type == X86_OP_MEM:
|
|
991
|
+
pointer = state.get(ins, ins.operands[0], image)
|
|
992
|
+
target, provenance, code_segment = far_pointer_transfer(state, image)
|
|
993
|
+
state.event("far-jump", target=target, provenance=provenance, indirectValue=pointer.report())
|
|
994
|
+
if target is None:
|
|
995
|
+
raise StopPath("unresolved jump: " + provenance["reason"])
|
|
996
|
+
state.setreg("cs", code_segment, at)
|
|
997
|
+
state.at = target
|
|
998
|
+
continue
|
|
930
999
|
if target is None:
|
|
931
1000
|
if continue_declared_jumps and at in image.indirect_jumps:
|
|
932
1001
|
deferred.append(deepcopy(state))
|
|
@@ -0,0 +1,351 @@
|
|
|
1
|
+
"""Indirect far CALL and JMP through a traced m16:16 pointer. Synthetic bytes only."""
|
|
2
|
+
import unittest
|
|
3
|
+
|
|
4
|
+
from test_x86 import events
|
|
5
|
+
from scientific_method_engine.x86.reports import run_report
|
|
6
|
+
from scientific_method_engine.x86.trace import walk
|
|
7
|
+
from scientific_method_engine.x86.image import Image
|
|
8
|
+
|
|
9
|
+
# The producer stores an offset and a segment at DS:0200, then calls through them.
|
|
10
|
+
STORE_OFFSET = "c7 06 00 02 30 00" # mov word [0200], 0030
|
|
11
|
+
STORE_SEGMENT = "c7 06 02 02 00 10" # mov word [0202], 1000
|
|
12
|
+
CALL = "ff 1e 00 02" # call far [0200]
|
|
13
|
+
JUMP = "ff 2e 00 02" # jmp far [0200]
|
|
14
|
+
TARGETS = 0x30
|
|
15
|
+
# 0030: mov ax, 42; retf 0034: mov ax, 7; retf 0038: mov ax, 42; ret
|
|
16
|
+
TARGET_CODE = "b8 2a 00 cb b8 07 00 cb b8 2a 00 c3"
|
|
17
|
+
FRAME = {"ds": 0x1000, "ss": 0x9000}
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def program(*parts):
|
|
21
|
+
producer = bytes.fromhex(" ".join(parts))
|
|
22
|
+
assert len(producer) <= TARGETS
|
|
23
|
+
return producer + bytes(TARGETS - len(producer)) + bytes.fromhex(TARGET_CODE), len(producer)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def regions(data, producer_end, resident=None):
|
|
27
|
+
rows = [{"name": "producer", "start": 0, "end": producer_end, "ip": 0, "segment": 0x1000, "entries": [0],
|
|
28
|
+
"evidence": "synthetic producer"},
|
|
29
|
+
{"name": "target", "start": TARGETS, "end": len(data), "ip": TARGETS, "segment": 0x1000,
|
|
30
|
+
"entries": [TARGETS], "evidence": "synthetic declared target"}]
|
|
31
|
+
if resident is not None:
|
|
32
|
+
for row in rows:
|
|
33
|
+
row["resident"] = resident
|
|
34
|
+
return rows
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def run(*parts, command="trace", resident=None, **extra):
|
|
38
|
+
data, end = program(*parts)
|
|
39
|
+
config = {"regions": regions(data, end, resident), "entry": 0, "registers": {**FRAME, **extra.pop("registers", {})},
|
|
40
|
+
"maxSteps": 32, "maxPaths": 2, "totalSteps": 64, "visitLimit": 4, **extra}
|
|
41
|
+
return run_report(data, config, command)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def site(*parts):
|
|
45
|
+
return len(bytes.fromhex(" ".join(parts)))
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def only_path(test, result):
|
|
49
|
+
test.assertEqual(len(result["paths"]), 1)
|
|
50
|
+
return result["paths"][0]
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
class FollowedPointer(unittest.TestCase):
|
|
54
|
+
def test_produced_pointer_enters_the_declared_target_and_returns(self):
|
|
55
|
+
result = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3", command="guards")
|
|
56
|
+
path = only_path(self, result)
|
|
57
|
+
self.assertTrue(path["returned"], path["stop"])
|
|
58
|
+
self.assertTrue(result["completeWithinModel"])
|
|
59
|
+
self.assertEqual(path["registers"]["ax"]["value"], 42)
|
|
60
|
+
call = events(result, "call")[0]
|
|
61
|
+
self.assertEqual(call["site"], 12)
|
|
62
|
+
self.assertEqual(call["target"], TARGETS)
|
|
63
|
+
self.assertEqual(call["returnFrameBytes"], 4)
|
|
64
|
+
self.assertEqual(call["indirectValue"]["value"], 0x10000030)
|
|
65
|
+
provenance = call["provenance"]
|
|
66
|
+
self.assertEqual(provenance["encoding"], "m16:16")
|
|
67
|
+
self.assertEqual(provenance["loadedAddress"], "1000:0030")
|
|
68
|
+
self.assertEqual((provenance["offsetWord"]["value"], provenance["offsetWord"]["producers"]), (0x30, [0]))
|
|
69
|
+
self.assertEqual((provenance["segmentWord"]["value"], provenance["segmentWord"]["producers"]), (0x1000, [6]))
|
|
70
|
+
self.assertEqual([row["writeOrder"] for row in provenance["offsetWord"]["bytes"] + provenance["segmentWord"]["bytes"]],
|
|
71
|
+
[0, 0, 1, 1])
|
|
72
|
+
self.assertEqual(provenance["pointerRead"]["segmentRegister"], "ds")
|
|
73
|
+
self.assertEqual(provenance["pointerRead"]["offset"]["value"], 0x200)
|
|
74
|
+
self.assertEqual(provenance["admission"], {"rule": "exact declared region mapping", "region": "target",
|
|
75
|
+
"regionSegment": 0x1000, "regionIp": TARGETS, "regionStart": TARGETS,
|
|
76
|
+
"regionEvidence": "synthetic declared target"})
|
|
77
|
+
self.assertNotIn("reason", provenance)
|
|
78
|
+
# The read that fetched the pointer is the event the provenance cites.
|
|
79
|
+
read = next(e for e in path["events"] if e["order"] == provenance["pointerRead"]["order"])
|
|
80
|
+
self.assertEqual((read["kind"], read["width"]), ("read", 4))
|
|
81
|
+
returned = [e for e in path["events"] if e["kind"] == "call-return"]
|
|
82
|
+
self.assertEqual([(e["callSite"], e["modeled"]) for e in returned], [(12, False)])
|
|
83
|
+
|
|
84
|
+
def test_callee_runs_under_the_segment_word_and_the_far_return_restores_cs(self):
|
|
85
|
+
result = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3")
|
|
86
|
+
path = only_path(self, result)
|
|
87
|
+
inner = next(e for e in path["events"] if e["kind"] == "return" and e["depth"] == 1)
|
|
88
|
+
self.assertEqual(inner["registers"]["cs"]["value"], 0x1000)
|
|
89
|
+
self.assertIn(6, inner["registers"]["cs"]["producers"])
|
|
90
|
+
self.assertEqual(path["registers"]["cs"]["value"], 0x1000)
|
|
91
|
+
|
|
92
|
+
def test_overwriting_the_offset_word_changes_the_target(self):
|
|
93
|
+
rewrite = "c7 06 00 02 34 00"
|
|
94
|
+
result = run(STORE_OFFSET, STORE_SEGMENT, rewrite, CALL, "c3")
|
|
95
|
+
path = only_path(self, result)
|
|
96
|
+
self.assertTrue(path["returned"], path["stop"])
|
|
97
|
+
self.assertEqual(path["registers"]["ax"]["value"], 7)
|
|
98
|
+
call = events(result, "call")[0]
|
|
99
|
+
self.assertEqual(call["target"], 0x34)
|
|
100
|
+
self.assertEqual(call["provenance"]["offsetWord"]["producers"], [12])
|
|
101
|
+
self.assertEqual(call["provenance"]["segmentWord"]["producers"], [6])
|
|
102
|
+
|
|
103
|
+
def test_overwriting_the_segment_word_with_an_undeclared_segment_stops(self):
|
|
104
|
+
rewrite = "c7 06 02 02 00 20"
|
|
105
|
+
result = run(STORE_OFFSET, STORE_SEGMENT, rewrite, CALL, "c3")
|
|
106
|
+
path = only_path(self, result)
|
|
107
|
+
self.assertFalse(path["returned"])
|
|
108
|
+
self.assertEqual(path["stop"], "unresolved call: far pointer names no declared code region")
|
|
109
|
+
call = events(result, "call")[0]
|
|
110
|
+
self.assertIsNone(call["target"])
|
|
111
|
+
self.assertEqual(call["provenance"]["loadedAddress"], "2000:0030")
|
|
112
|
+
self.assertEqual(call["provenance"]["segmentWord"]["producers"], [12])
|
|
113
|
+
self.assertFalse(result["completeWithinModel"])
|
|
114
|
+
|
|
115
|
+
def test_effective_segment_override_is_kept(self):
|
|
116
|
+
# mov word es:[0200], 0030 / mov word es:[0202], 1000 / call far es:[0200]
|
|
117
|
+
result = run("26 c7 06 00 02 30 00", "26 c7 06 02 02 00 10", "26 ff 1e 00 02", "c3", registers={"es": 0x1000, "ds": 0x5000})
|
|
118
|
+
path = only_path(self, result)
|
|
119
|
+
self.assertTrue(path["returned"], path["stop"])
|
|
120
|
+
self.assertEqual(events(result, "call")[0]["provenance"]["pointerRead"]["segmentRegister"], "es")
|
|
121
|
+
|
|
122
|
+
def test_pointer_built_from_registers_by_instructions_is_followed(self):
|
|
123
|
+
# mov ax, 0030 / mov [0200], ax / mov ax, 1000 / mov [0202], ax / call far [0200]
|
|
124
|
+
result = run("b8 30 00", "a3 00 02", "b8 00 10", "a3 02 02", CALL, "c3")
|
|
125
|
+
path = only_path(self, result)
|
|
126
|
+
self.assertTrue(path["returned"], path["stop"])
|
|
127
|
+
provenance = events(result, "call")[0]["provenance"]
|
|
128
|
+
self.assertEqual(provenance["offsetWord"]["producers"], [0, 3])
|
|
129
|
+
self.assertEqual(provenance["segmentWord"]["producers"], [6, 9])
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
class StoppedPointer(unittest.TestCase):
|
|
133
|
+
def assert_stopped(self, result, reason):
|
|
134
|
+
path = only_path(self, result)
|
|
135
|
+
self.assertFalse(path["returned"])
|
|
136
|
+
self.assertEqual(path["stop"], reason)
|
|
137
|
+
self.assertFalse(result["completeWithinModel"])
|
|
138
|
+
self.assertFalse([e for e in path["events"] if e["depth"] > 0], "the target must not be entered")
|
|
139
|
+
call = [e for e in path["events"] if e["kind"] in ("call", "far-jump")][-1]
|
|
140
|
+
self.assertIsNone(call["target"])
|
|
141
|
+
return call["provenance"]
|
|
142
|
+
|
|
143
|
+
def test_unknown_pointer_stays_stopped(self):
|
|
144
|
+
provenance = self.assert_stopped(run(CALL, "c3"), "unresolved call: far pointer offset and segment words unknown")
|
|
145
|
+
self.assertEqual({row["unwritten"]["cause"] for w in ("offsetWord", "segmentWord") for row in provenance[w]["bytes"]},
|
|
146
|
+
{"no write on this path"})
|
|
147
|
+
self.assertNotIn("loadedAddress", provenance)
|
|
148
|
+
|
|
149
|
+
def test_partly_unknown_pointer_stays_stopped(self):
|
|
150
|
+
self.assert_stopped(run(STORE_OFFSET, CALL, "c3"), "unresolved call: far pointer segment word unknown")
|
|
151
|
+
self.assert_stopped(run(STORE_SEGMENT, CALL, "c3"), "unresolved call: far pointer offset word unknown")
|
|
152
|
+
# One byte of the segment word stored: the word is still unknown.
|
|
153
|
+
self.assert_stopped(run(STORE_OFFSET, "c6 06 02 02 00", CALL, "c3"), "unresolved call: far pointer segment word unknown")
|
|
154
|
+
|
|
155
|
+
def test_alias_invalidated_pointer_stays_stopped(self):
|
|
156
|
+
# mov word es:[di], 0 with ES and DI unknown may store over the pointer.
|
|
157
|
+
provenance = self.assert_stopped(run(STORE_OFFSET, STORE_SEGMENT, "26 c7 05 00 00", CALL, "c3"),
|
|
158
|
+
"unresolved call: far pointer offset and segment words unknown")
|
|
159
|
+
causes = {row["unwritten"]["cause"] for w in ("offsetWord", "segmentWord") for row in provenance[w]["bytes"]}
|
|
160
|
+
self.assertEqual(causes, {"dropped by a possibly aliasing write"})
|
|
161
|
+
|
|
162
|
+
def test_pointer_dropped_by_a_modeled_call_stays_stopped(self):
|
|
163
|
+
# A modeled call between the stores and the transfer forgets memory.
|
|
164
|
+
parts = (STORE_OFFSET, STORE_SEGMENT, "e8 00 00", CALL, "c3")
|
|
165
|
+
model = [{"site": 12, "evidence": "synthetic modeled service", "cases": [{}]}]
|
|
166
|
+
result = run(*parts, callModels=model)
|
|
167
|
+
provenance = self.assert_stopped(result, "unresolved call: far pointer offset and segment words unknown")
|
|
168
|
+
self.assertEqual({row["unwritten"]["cause"] for row in provenance["offsetWord"]["bytes"]}, {"dropped by a modeled call"})
|
|
169
|
+
|
|
170
|
+
def test_target_outside_declared_regions_stays_stopped(self):
|
|
171
|
+
# 1000:0020 lies between the two declared regions.
|
|
172
|
+
provenance = self.assert_stopped(run("c7 06 00 02 20 00", STORE_SEGMENT, CALL, "c3"),
|
|
173
|
+
"unresolved call: far pointer names no declared code region")
|
|
174
|
+
self.assertEqual(provenance["loadedAddress"], "1000:0020")
|
|
175
|
+
|
|
176
|
+
def test_canonical_segment_alias_is_not_followed(self):
|
|
177
|
+
# 1003:0000 is linear 10030, the resident target, but not under the target region's mapping.
|
|
178
|
+
provenance = self.assert_stopped(run("c7 06 00 02 00 00", "c7 06 02 02 03 10", CALL, "c3", resident=True),
|
|
179
|
+
"unresolved call: far pointer names declared resident code only through a segment alias of its mapping")
|
|
180
|
+
self.assertEqual(provenance["loadedAddress"], "1003:0000")
|
|
181
|
+
|
|
182
|
+
def test_overlay_analysis_segment_is_not_a_load_address(self):
|
|
183
|
+
data, end = program(STORE_OFFSET, STORE_SEGMENT, CALL, "c3")
|
|
184
|
+
rows = regions(data, end, resident=True)
|
|
185
|
+
rows[1].update(resident=False, container={"view": "overlay-1", "start": TARGETS, "end": len(data)})
|
|
186
|
+
result = run_report(data, {"regions": rows, "entry": 0, "registers": FRAME}, "trace")
|
|
187
|
+
provenance = self.assert_stopped(
|
|
188
|
+
result, "unresolved call: far pointer names overlay code by its analysis segment, which is not a load address")
|
|
189
|
+
self.assertEqual(provenance["admission"], {"region": "target"})
|
|
190
|
+
|
|
191
|
+
def test_operand_size_override_stays_stopped(self):
|
|
192
|
+
# 66 FF 1E is a far call through m16:32, outside the segmented16 frame model.
|
|
193
|
+
result = run(STORE_OFFSET, STORE_SEGMENT, "66 ff 1e 00 02", "c3")
|
|
194
|
+
path = only_path(self, result)
|
|
195
|
+
self.assertEqual(path["stop"], "Operand-size control transfer override is outside the selected frame model")
|
|
196
|
+
self.assertFalse(events(result, "call"))
|
|
197
|
+
|
|
198
|
+
def test_unknown_jump_pointer_stays_stopped_with_its_event(self):
|
|
199
|
+
provenance = self.assert_stopped(run(STORE_SEGMENT, JUMP), "unresolved jump: far pointer offset word unknown")
|
|
200
|
+
self.assertEqual(provenance["segmentWord"]["value"], 0x1000)
|
|
201
|
+
|
|
202
|
+
|
|
203
|
+
class ModelsAndLimits(unittest.TestCase):
|
|
204
|
+
def test_call_model_at_the_site_keeps_precedence(self):
|
|
205
|
+
model = [{"site": 12, "evidence": "synthetic far service", "cases": [{"registers": {"ax": 5}}]}]
|
|
206
|
+
result = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3", callModels=model)
|
|
207
|
+
path = only_path(self, result)
|
|
208
|
+
self.assertTrue(path["returned"], path["stop"])
|
|
209
|
+
self.assertEqual(path["registers"]["ax"]["value"], 5)
|
|
210
|
+
self.assertEqual(path["conditionalModels"][0]["site"], 12)
|
|
211
|
+
self.assertEqual(events(result, "call")[0]["target"], TARGETS)
|
|
212
|
+
self.assertFalse([e for e in path["events"] if e["depth"] > 0])
|
|
213
|
+
|
|
214
|
+
def test_depth_limit_stops_before_the_target(self):
|
|
215
|
+
result = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3", maxDepth=1)
|
|
216
|
+
path = only_path(self, result)
|
|
217
|
+
self.assertEqual(path["stop"], "call depth limit; recursion or callee remains unresolved")
|
|
218
|
+
self.assertEqual(events(result, "call")[0]["target"], TARGETS)
|
|
219
|
+
|
|
220
|
+
def test_step_limit_inside_the_target_stays_a_stop(self):
|
|
221
|
+
result = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3", maxSteps=4)
|
|
222
|
+
path = only_path(self, result)
|
|
223
|
+
self.assertEqual(path["stop"], "step limit; loop progress unresolved")
|
|
224
|
+
self.assertEqual(path["stopSite"], TARGETS + 3)
|
|
225
|
+
|
|
226
|
+
def test_reach_control_into_the_target_holds_only_when_read(self):
|
|
227
|
+
control = [{"name": "enters", "kind": "reach", "at": {"site": TARGETS}, "expect": "always"}]
|
|
228
|
+
held = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3", relationalControls=control)
|
|
229
|
+
self.assertEqual(held["relationalControls"]["controls"][0]["verdict"], "held")
|
|
230
|
+
for limit in ({"maxDepth": 1}, {"maxSteps": 3}):
|
|
231
|
+
with self.subTest(limit=limit):
|
|
232
|
+
capped = run(STORE_OFFSET, STORE_SEGMENT, CALL, "c3", relationalControls=control, **limit)
|
|
233
|
+
self.assertEqual(capped["relationalControls"]["controls"][0]["verdict"], "undecided")
|
|
234
|
+
unknown = run(STORE_OFFSET, CALL, "c3", relationalControls=control)
|
|
235
|
+
self.assertEqual(unknown["relationalControls"]["controls"][0]["verdict"], "undecided")
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
class FarJump(unittest.TestCase):
|
|
239
|
+
def test_produced_pointer_jump_continues_at_the_target(self):
|
|
240
|
+
result = run("c7 06 00 02 38 00", STORE_SEGMENT, JUMP)
|
|
241
|
+
path = only_path(self, result)
|
|
242
|
+
self.assertTrue(path["returned"], path["stop"])
|
|
243
|
+
self.assertEqual(path["registers"]["ax"]["value"], 42)
|
|
244
|
+
jump = next(e for e in path["events"] if e["kind"] == "far-jump")
|
|
245
|
+
self.assertEqual(jump["target"], 0x38)
|
|
246
|
+
self.assertEqual(jump["provenance"]["loadedAddress"], "1000:0038")
|
|
247
|
+
self.assertEqual(jump["provenance"]["offsetWord"]["producers"], [0])
|
|
248
|
+
self.assertEqual(jump["indirectValue"]["value"], 0x10000038)
|
|
249
|
+
|
|
250
|
+
def test_far_jump_event_reaches_the_guard_and_effect_projections(self):
|
|
251
|
+
for command in ("guards", "effects"):
|
|
252
|
+
with self.subTest(command=command):
|
|
253
|
+
result = run("c7 06 00 02 38 00", STORE_SEGMENT, JUMP, command=command)
|
|
254
|
+
self.assertTrue(events(result, "far-jump"))
|
|
255
|
+
|
|
256
|
+
def test_projections_keep_the_pointer_read_a_kept_transfer_cites(self):
|
|
257
|
+
cases = (("effects", (STORE_OFFSET, STORE_SEGMENT, CALL, "c3"), "call"),
|
|
258
|
+
("effects", ("c7 06 00 02 38 00", STORE_SEGMENT, JUMP), "far-jump"),
|
|
259
|
+
("arguments", (STORE_OFFSET, STORE_SEGMENT, CALL, "c3"), "call"))
|
|
260
|
+
for command, parts, kind in cases:
|
|
261
|
+
with self.subTest(command=command, kind=kind):
|
|
262
|
+
path = only_path(self, run(*parts, command=command))
|
|
263
|
+
transfer = next(e for e in path["events"] if e["kind"] == kind)
|
|
264
|
+
order = transfer["provenance"]["pointerRead"]["order"]
|
|
265
|
+
read = [e for e in path["events"] if e["order"] == order]
|
|
266
|
+
self.assertEqual([(e["kind"], e["width"]) for e in read], [("read", 4)])
|
|
267
|
+
# Effects still leaves out reads no kept event cites.
|
|
268
|
+
path = only_path(self, run(STORE_OFFSET, STORE_SEGMENT, "a1 00 02", CALL, "c3", command="effects"))
|
|
269
|
+
self.assertEqual([e["width"] for e in path["events"] if e["kind"] == "read"], [4])
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
class ResultOrigins(unittest.TestCase):
|
|
273
|
+
# 0000: call 0011; mov [word], ax; mov word [other], const; call far [0200]; ret
|
|
274
|
+
# 0011: mov ax, 1000 or 0030; ret (declared result in AX)
|
|
275
|
+
def run_flow(self, result_word, other_word):
|
|
276
|
+
stored = {"offset": "00 02", "segment": "02 02"}
|
|
277
|
+
other = {"offset": "c7 06 00 02 30 00", "segment": "c7 06 02 02 00 10"}[other_word]
|
|
278
|
+
value = {"offset": "30 00", "segment": "00 10"}[result_word]
|
|
279
|
+
helper = site("e8 0e 00", "a3 " + stored[result_word], other, CALL, "c3")
|
|
280
|
+
self.assertEqual(helper, 0x11)
|
|
281
|
+
return run("e8 0e 00", "a3 " + stored[result_word], other, CALL, "c3", "b8 " + value, "c3", command="trace",
|
|
282
|
+
returnContracts=[{"entry": helper, "register": "ax", "evidence": "synthetic result contract"}])
|
|
283
|
+
|
|
284
|
+
def callee_cs(self, result):
|
|
285
|
+
path = only_path(self, result)
|
|
286
|
+
self.assertTrue(path["returned"], path["stop"])
|
|
287
|
+
return next(e for e in path["events"] if e["kind"] == "return" and e["depth"] == 1 and e["site"] == 0x33)["registers"]["cs"]
|
|
288
|
+
|
|
289
|
+
def test_a_declared_result_stored_as_the_segment_word_is_a_result_origin_of_cs(self):
|
|
290
|
+
cs = self.callee_cs(self.run_flow("segment", "offset"))
|
|
291
|
+
self.assertEqual(cs["value"], 0x1000)
|
|
292
|
+
self.assertTrue(cs.get("resultOrigins"))
|
|
293
|
+
|
|
294
|
+
def test_a_declared_result_stored_as_the_offset_word_is_not(self):
|
|
295
|
+
cs = self.callee_cs(self.run_flow("offset", "segment"))
|
|
296
|
+
self.assertEqual(cs["value"], 0x1000)
|
|
297
|
+
self.assertNotIn("resultOrigins", cs)
|
|
298
|
+
|
|
299
|
+
|
|
300
|
+
class Trampolines(unittest.TestCase):
|
|
301
|
+
def layout(self, entry_declared=True):
|
|
302
|
+
# Resident producer, a resident stub holding an INT 3Fh trampoline at file 0x20, and an
|
|
303
|
+
# overlay whose entry is file 0x30.
|
|
304
|
+
data, end = program("c7 06 00 02 20 00", STORE_SEGMENT, CALL, "c3")
|
|
305
|
+
data = data[:0x20] + bytes.fromhex("cd 3f 00 00") + data[0x24:]
|
|
306
|
+
rows = [{"name": "producer", "start": 0, "end": end, "ip": 0, "segment": 0x1000, "resident": True,
|
|
307
|
+
"entries": [0], "evidence": "synthetic producer"},
|
|
308
|
+
{"name": "stub", "start": 0x20, "end": 0x24, "ip": 0x20, "segment": 0x1000, "resident": True,
|
|
309
|
+
"entries": [0x20], "evidence": "synthetic trampoline stub"}]
|
|
310
|
+
if entry_declared:
|
|
311
|
+
rows.append({"name": "overlay", "start": TARGETS, "end": len(data), "ip": 0, "segment": 0x4000,
|
|
312
|
+
"resident": False, "container": {"view": "overlay-1", "start": TARGETS, "end": len(data)},
|
|
313
|
+
"entries": [TARGETS], "evidence": "synthetic overlay analysis view"})
|
|
314
|
+
exports = [{"descriptor": 1, "trampoline": 0x20, "entry": TARGETS, "codeRange": {"start": TARGETS, "end": len(data)},
|
|
315
|
+
"evidence": "synthetic FBOV descriptor/trampoline"}]
|
|
316
|
+
return run_report(data, {"regions": rows, "entry": 0, "registers": FRAME, "overlayExports": exports}, "trace")
|
|
317
|
+
|
|
318
|
+
def test_pointer_at_a_trampoline_continues_at_its_overlay_entry(self):
|
|
319
|
+
result = self.layout()
|
|
320
|
+
path = only_path(self, result)
|
|
321
|
+
self.assertTrue(path["returned"], path["stop"])
|
|
322
|
+
self.assertEqual(path["registers"]["ax"]["value"], 42)
|
|
323
|
+
call = events(result, "call")[0]
|
|
324
|
+
self.assertEqual(call["target"], TARGETS)
|
|
325
|
+
admission = call["provenance"]["admission"]
|
|
326
|
+
self.assertEqual(admission["region"], "stub")
|
|
327
|
+
self.assertEqual(admission["trampoline"], {"trampoline": 0x20, "descriptor": 1, "entry": TARGETS,
|
|
328
|
+
"evidence": "synthetic FBOV descriptor/trampoline"})
|
|
329
|
+
inner = next(e for e in path["events"] if e["kind"] == "return" and e["depth"] == 1)
|
|
330
|
+
self.assertEqual(inner["registers"]["cs"]["value"], 0x4000)
|
|
331
|
+
|
|
332
|
+
def test_trampoline_entry_outside_declared_regions_stays_stopped(self):
|
|
333
|
+
result = self.layout(entry_declared=False)
|
|
334
|
+
path = only_path(self, result)
|
|
335
|
+
self.assertEqual(path["stop"], "unresolved call: the overlay entry the FBOV trampoline names lies outside declared code regions")
|
|
336
|
+
self.assertEqual(events(result, "call")[0]["provenance"]["admission"]["trampoline"]["entry"], TARGETS)
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
class StaticWalk(unittest.TestCase):
|
|
340
|
+
def test_walk_names_an_indirect_far_transfer_as_computed(self):
|
|
341
|
+
for transfer in (CALL, JUMP):
|
|
342
|
+
with self.subTest(transfer=transfer):
|
|
343
|
+
data, end = program(transfer, "c3")
|
|
344
|
+
image = Image(data, {"regions": regions(data, end)})
|
|
345
|
+
_, gaps, edges, _, _ = walk(image, [0])
|
|
346
|
+
self.assertIn({"site": 0, "reason": "computed transfer remains unresolved"}, gaps)
|
|
347
|
+
self.assertIsNone(edges[0]["target"])
|
|
348
|
+
|
|
349
|
+
|
|
350
|
+
if __name__ == "__main__":
|
|
351
|
+
unittest.main()
|
|
@@ -39,6 +39,25 @@ class AddressForms(unittest.TestCase):
|
|
|
39
39
|
check(self, "bb4000 c7073412 c747027856 c41f bb4000 c537 c3", registers=DATA, resolved=("bx", "es", "si", "ds"))
|
|
40
40
|
|
|
41
41
|
|
|
42
|
+
class FarTransfers(unittest.TestCase):
|
|
43
|
+
"""Indirect far CALL and JMP through an m16:16 pointer the routine stores first (code at 1000:0000)."""
|
|
44
|
+
CODE = {"ds": 0x1000}
|
|
45
|
+
|
|
46
|
+
def test_call_far_through_memory(self):
|
|
47
|
+
# The pointer names 1000:0018 (AX=7) and not 1000:0014 (AX=42); the caller adds one after the far return.
|
|
48
|
+
result = check(self, "c7060002 1800 c7060202 0010 ff1e0002 050100 c3 b82a00cb b80700cb",
|
|
49
|
+
registers=self.CODE, resolved=("ax", "sp"))
|
|
50
|
+
self.assertEqual(result["paths"][0]["registers"]["ax"]["value"], 8)
|
|
51
|
+
|
|
52
|
+
def test_call_far_through_a_based_operand_with_a_segment_override(self):
|
|
53
|
+
check(self, "bb0002 26c7071300 26c747020010 26ff1f 40 c3 b82a00cb",
|
|
54
|
+
registers={"es": 0x1000, "ds": 0x3000}, resolved=("ax", "sp"))
|
|
55
|
+
|
|
56
|
+
def test_jmp_far_through_memory(self):
|
|
57
|
+
result = check(self, "c7060002 1000 c7060202 0010 ff2e0002 b82a00c3", registers=self.CODE, resolved=("ax",))
|
|
58
|
+
self.assertEqual(result["paths"][0]["registers"]["ax"]["value"], 42)
|
|
59
|
+
|
|
60
|
+
|
|
42
61
|
class Stack(unittest.TestCase):
|
|
43
62
|
def test_push_pop_and_leave(self):
|
|
44
63
|
check(self, "b81100 50 6a22 5b 59 55 89e5 6a33 c9 c3", resolved=("bx", "cx", "sp"))
|
|
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-9.1.0 → scientific_method_engine-10.0.0}/tests/test_continuation_budget.py
RENAMED
|
File without changes
|
|
File without changes
|
{scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_effect_order.py
RENAMED
|
File without changes
|
{scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_entry_frame.py
RENAMED
|
File without changes
|
{scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_interrupt_models.py
RENAMED
|
File without changes
|
|
File without changes
|
{scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_memory_scopes.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
{scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_relational_controls.py
RENAMED
|
File without changes
|
{scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_successor_rule.py
RENAMED
|
File without changes
|
{scientific_method_engine-9.1.0 → scientific_method_engine-10.0.0}/tests/test_table_continuations.py
RENAMED
|
File without changes
|
|
File without changes
|