scientific-method-engine 7.4.0__tar.gz → 8.1.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-7.4.0 → scientific_method_engine-8.1.0}/PKG-INFO +9 -1
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/README.md +8 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/pyproject.toml +1 -1
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/cli.py +2 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/argument_frames.py +51 -13
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/machine.py +4 -1
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/memory_scopes.py +18 -1
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/relational.py +4 -4
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/trace.py +91 -29
- scientific_method_engine-8.1.0/tests/test_interrupt_models.py +219 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_relational_controls.py +67 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_x86.py +112 -13
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/.gitignore +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/LICENSE +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/__init__.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/__main__.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/image.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/loops.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/pcode.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/reports.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/src/scientific_method_engine/x86/values.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/oracle.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_continuation_budget.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_dispatch.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_effect_order.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_entry_frame.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_loops.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_memory_scopes.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_nested_frame_request.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_oracle.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_pe.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.0}/tests/test_successor_rule.py +0 -0
- {scientific_method_engine-7.4.0 → scientific_method_engine-8.1.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:
|
|
3
|
+
Version: 8.1.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 call model may also sit at an `INT n` instruction in the real-mode model. The interrupt is
|
|
149
|
+
still reported as a hardware boundary with its vector, the handler is not executed, and each case
|
|
150
|
+
returns to the next instruction with SP and CS as before the interrupt. Registers, flags and memory
|
|
151
|
+
the model does not preserve or set are unknown. `leavesFlags: true` describes a service that returns
|
|
152
|
+
with a far return and leaves the interrupt's FLAGS word on the stack. Without a model, and at INT1,
|
|
153
|
+
INT3 (in either encoding), INTO or any PE32 interrupt, the path stops at the interrupt as before. See
|
|
154
|
+
[ADR 0017](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/decisions/0017-call-models-at-interrupt-sites.md).
|
|
155
|
+
|
|
148
156
|
A call model may declare `preservesMemory`: up to 32 scopes (4,096 bytes in total), each naming a
|
|
149
157
|
segment register, an address-width base register, an optional displacement, a byte count and the
|
|
150
158
|
evidence for assuming the service leaves those bytes alone. Scopes resolve against the pre-call
|
|
@@ -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 call model may also sit at an `INT n` instruction in the real-mode model. The interrupt is
|
|
133
|
+
still reported as a hardware boundary with its vector, the handler is not executed, and each case
|
|
134
|
+
returns to the next instruction with SP and CS as before the interrupt. Registers, flags and memory
|
|
135
|
+
the model does not preserve or set are unknown. `leavesFlags: true` describes a service that returns
|
|
136
|
+
with a far return and leaves the interrupt's FLAGS word on the stack. Without a model, and at INT1,
|
|
137
|
+
INT3 (in either encoding), INTO or any PE32 interrupt, the path stops at the interrupt as before. See
|
|
138
|
+
[ADR 0017](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/decisions/0017-call-models-at-interrupt-sites.md).
|
|
139
|
+
|
|
132
140
|
A call model may declare `preservesMemory`: up to 32 scopes (4,096 bytes in total), each naming a
|
|
133
141
|
segment register, an address-width base register, an optional displacement, a byte count and the
|
|
134
142
|
evidence for assuming the service leaves those bytes alone. Scopes resolve against the pre-call
|
|
@@ -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 = "8.1.0"
|
|
9
9
|
description = "Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code."
|
|
10
10
|
readme = "README.md"
|
|
11
11
|
requires-python = ">=3.12"
|
|
@@ -27,6 +27,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
|
|
|
27
27
|
"Declared table continuations are separate conditional paths that spend continuationBudget\n"
|
|
28
28
|
"(paths, totalSteps, maxSteps, visitLimit, stringIterations); ordinary computed transfers remain stopped.\n"
|
|
29
29
|
"Port accesses and interrupts are hardware-boundary events; portInputs supplies port reads as assumptions.\n"
|
|
30
|
+
"A callModels entry at an INT n site (real mode) returns past the interrupt under its cases (leavesFlags: true\n"
|
|
31
|
+
"keeps the interrupt's FLAGS word on the stack); other interrupts stop.\n"
|
|
30
32
|
"callModels[].preservesMemory keeps explicit, bounded pre-call byte scopes across a modeled call; other memory stays unknown.\n"
|
|
31
33
|
"A scope needs a concrete segment; its base may be symbolic, such as BP in an entryFrame query.\n"
|
|
32
34
|
"Each traced path's loops record lists restart edges and what changed between iterations (loopIterationLimit).\n"
|
|
@@ -7,6 +7,8 @@ amount never join or split slots. Whatever a read did not settle on the path sta
|
|
|
7
7
|
"""
|
|
8
8
|
from capstone.x86 import X86_OP_IMM, X86_OP_REG
|
|
9
9
|
|
|
10
|
+
from .machine import NO_WRITE
|
|
11
|
+
|
|
10
12
|
# The argument bytes one frame maps; a wider frame is mapped up to here and stays open.
|
|
11
13
|
WINDOW_BYTES = 256
|
|
12
14
|
|
|
@@ -131,12 +133,27 @@ def _frame(image, events, index):
|
|
|
131
133
|
# A read byte with no known caller writer, one the callee stored to first, or one whose producers
|
|
132
134
|
# lack the slot's writer saw something other than the caller's bytes. The store check catches an
|
|
133
135
|
# overwrite derived from the argument itself, which keeps the writer among its producers.
|
|
134
|
-
stale
|
|
135
|
-
|
|
136
|
+
stale, unknown = [], []
|
|
137
|
+
for i, at in enumerate(span):
|
|
138
|
+
slot = by_byte[at]
|
|
139
|
+
if first_store.get(at, read["order"]) < read["order"]:
|
|
140
|
+
stale.append(i)
|
|
141
|
+
elif slot["writerSite"] is None:
|
|
142
|
+
stale.append(i)
|
|
143
|
+
# Nothing on the path wrote a byte with no write, so the caller did not. A byte a modeled
|
|
144
|
+
# call invalidated or another address may have stored could still hold the caller's value.
|
|
145
|
+
if slot["reason"] != NO_WRITE:
|
|
146
|
+
unknown.append(i)
|
|
147
|
+
elif slot["writerSite"] not in read["byteProducers"][i]["producers"]:
|
|
148
|
+
# No callee store through the frame's segment and base explains the missing writer: a callee
|
|
149
|
+
# write through another address or a modeled call in the callee may or may not have replaced it.
|
|
150
|
+
stale.append(i)
|
|
151
|
+
unknown.append(i)
|
|
136
152
|
partial = [s["offset"] for s in covered if s["offset"] < offset or s["offset"] + s["width"] > offset + read["argument"]["width"]]
|
|
137
153
|
groupings.append({"readSite": read["site"], "readOrder": read["order"], "offset": offset, "width": read["argument"]["width"],
|
|
138
154
|
"grouping": read["argument"]["grouping"], "slotOffsets": [s["offset"] for s in covered],
|
|
139
|
-
"partialSlots": partial, "bytesNotFromSlotWriter": stale
|
|
155
|
+
"partialSlots": partial, "bytesNotFromSlotWriter": stale,
|
|
156
|
+
"bytesOfUnknownOrigin": unknown})
|
|
140
157
|
if stale:
|
|
141
158
|
open_reasons.append(f"bytes {stale} of the read at {read['site']} do not come from the slot's writer")
|
|
142
159
|
if partial:
|
|
@@ -182,12 +199,17 @@ def argument_frames(report, image):
|
|
|
182
199
|
|
|
183
200
|
A path gets one map per traced call, from caller-written slots to callee reads. A site's
|
|
184
201
|
groupings agree only when every path that traced a call there settled on the same read widths
|
|
185
|
-
and groupings. Separately, a site's widths are consistent when its paths read at
|
|
186
|
-
the caller wrote and no two reads with a different offset, width or grouping
|
|
187
|
-
byte from the caller; a path that skipped a read leaves the site consistent
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
202
|
+
and groupings. Separately, a site's widths are consistent (``True``) when its paths read at
|
|
203
|
+
least one byte the caller wrote and no two reads with a different offset, width or grouping
|
|
204
|
+
both saw one shared byte from the caller; a path that skipped a read leaves the site consistent
|
|
205
|
+
but not agreed. Bytes the callee stored itself and bytes no write on the path stored are not
|
|
206
|
+
the caller's and do not decide consistency. A byte of unknown origin (invalidated by a modeled
|
|
207
|
+
call, possibly stored through another address, or missing the slot writer among its producers
|
|
208
|
+
without a callee store) may be the caller's, and so may a read byte past the mapped window: a
|
|
209
|
+
pair of reads that would conflict on such a byte is listed in ``undecidedWidths`` and leaves the
|
|
210
|
+
site's ``widthsConsistent`` ``None`` unless another pair conflicts on the caller's bytes. A site
|
|
211
|
+
with no such pair whose reads saw no byte the caller wrote is ``None`` when some read saw a byte
|
|
212
|
+
of unknown origin and ``False`` otherwise. The report must come from
|
|
191
213
|
``trace`` with ``argument_window=WINDOW_BYTES``: each traced call's slots come from its
|
|
192
214
|
``argumentSlots`` record, which this removes from every path, declared continuations included.
|
|
193
215
|
"""
|
|
@@ -207,7 +229,7 @@ def argument_frames(report, image):
|
|
|
207
229
|
widths = sorted({tuple(sorted({(g["offset"], g["width"], g["grouping"]) for g in f["groupings"]})) for _, f in rows})
|
|
208
230
|
# Each read's paths, split by whether every byte it saw came from the caller's slot writer, and the
|
|
209
231
|
# frame bytes it saw from the slot writer on any path.
|
|
210
|
-
read_on, from_caller, not_from_caller, caller_bytes = {}, {}, {}, {}
|
|
232
|
+
read_on, from_caller, not_from_caller, caller_bytes, unknown_bytes = {}, {}, {}, {}, {}
|
|
211
233
|
for i, f in rows:
|
|
212
234
|
for g in f["groupings"]:
|
|
213
235
|
key = (g["offset"], g["width"], g["grouping"])
|
|
@@ -215,14 +237,29 @@ def argument_frames(report, image):
|
|
|
215
237
|
(not_from_caller if g["bytesNotFromSlotWriter"] else from_caller).setdefault(key, set()).add(i)
|
|
216
238
|
mapped = range(min(g["width"], f["mappedBytes"] - g["offset"]))
|
|
217
239
|
caller_bytes.setdefault(key, set()).update(g["offset"] + at for at in mapped if at not in g["bytesNotFromSlotWriter"])
|
|
240
|
+
# A read byte past the window was never mapped, so it may be the caller's too.
|
|
241
|
+
unmapped = range(max(0, f["mappedBytes"] - g["offset"]), g["width"])
|
|
242
|
+
unknown_bytes.setdefault(key, set()).update(g["offset"] + at for at in [*g["bytesOfUnknownOrigin"], *unmapped])
|
|
218
243
|
reads = sorted(read_on)
|
|
219
244
|
# Distinct reads that share a byte conflict: different intervals, or one interval grouped two ways.
|
|
220
245
|
pairs = [(a, b) for n, a in enumerate(reads) for b in reads[n + 1:] if _overlap(a, b)]
|
|
221
246
|
conflicting = [[{"offset": o, "width": w, "grouping": k} for o, w, k in pair] for pair in pairs]
|
|
222
|
-
# Only the caller's bytes decide consistency: a pair
|
|
247
|
+
# Only the caller's bytes decide consistency: a pair conflicts when both reads saw one shared byte from
|
|
223
248
|
# the slot writer. A callee reusing its argument slot as a local neither breaks nor supplies the
|
|
224
|
-
# width the caller's argument is read at, but a read past the caller's bytes still reads them.
|
|
249
|
+
# width the caller's argument is read at, but a read past the caller's bytes still reads them. A pair
|
|
250
|
+
# that would conflict if bytes of unknown origin were the caller's is undecided.
|
|
225
251
|
caller_conflict = any(caller_bytes[a] & caller_bytes[b] for a, b in pairs)
|
|
252
|
+
undecided = [(a, b) for a, b in pairs if not caller_bytes[a] & caller_bytes[b]
|
|
253
|
+
and (caller_bytes[a] | unknown_bytes[a]) & (caller_bytes[b] | unknown_bytes[b])]
|
|
254
|
+
if caller_conflict:
|
|
255
|
+
consistent = False
|
|
256
|
+
elif undecided:
|
|
257
|
+
consistent = None
|
|
258
|
+
elif any(caller_bytes.values()):
|
|
259
|
+
consistent = True
|
|
260
|
+
else:
|
|
261
|
+
# No read saw a byte from the slot writers; one of unknown origin leaves open whether any read did.
|
|
262
|
+
consistent = None if any(unknown_bytes.values()) else False
|
|
226
263
|
report["argumentFrameSites"].append({
|
|
227
264
|
"callSite": site, "paths": sorted({i for i, _ in rows}), "frames": len(rows),
|
|
228
265
|
"unsettledPaths": sorted({i for i, f in rows if not f["settledOnThisPath"]}),
|
|
@@ -231,7 +268,8 @@ def argument_frames(report, image):
|
|
|
231
268
|
"fromCallerOnPaths": sorted(from_caller.get((o, w, k), ())),
|
|
232
269
|
"notFromCallerOnPaths": sorted(not_from_caller.get((o, w, k), ()))} for o, w, k in reads],
|
|
233
270
|
"conflictingWidths": conflicting,
|
|
234
|
-
"
|
|
271
|
+
"undecidedWidths": [[{"offset": o, "width": w, "grouping": k} for o, w, k in pair] for pair in undecided],
|
|
272
|
+
"widthsConsistent": consistent,
|
|
235
273
|
"agreed": len(widths) == 1 and all(f["settledOnThisPath"] for _, f in rows),
|
|
236
274
|
"interpretation": "read widths per traced path; paths that never reached this call are not represented"})
|
|
237
275
|
return report
|
|
@@ -25,6 +25,9 @@ FLAT_PORT_REASON = "port access in the flat model depends on I/O privilege, whic
|
|
|
25
25
|
# The write-log key that marks a point where the model forgot all memory.
|
|
26
26
|
MEMORY_CLEARED = ("memory-cleared",)
|
|
27
27
|
|
|
28
|
+
# The ``unwritten`` cause of a byte that no write on the path stored.
|
|
29
|
+
NO_WRITE = "no write on this path"
|
|
30
|
+
|
|
28
31
|
|
|
29
32
|
class WriteLog:
|
|
30
33
|
"""Append-only list of (key, previous value) pairs, one per register or memory byte a write changes.
|
|
@@ -299,7 +302,7 @@ class State:
|
|
|
299
302
|
return dict(lost)
|
|
300
303
|
if self.memory_cleared is not None:
|
|
301
304
|
return {"cause": "dropped by a modeled call", "order": self.memory_cleared}
|
|
302
|
-
return {"cause":
|
|
305
|
+
return {"cause": NO_WRITE, "order": None}
|
|
303
306
|
|
|
304
307
|
def byte_writer(self, index, key):
|
|
305
308
|
"""The byteProducers row of one accessed byte: its producers and the write that stored it."""
|
|
@@ -56,7 +56,7 @@ def validate_scopes(model, bits, flat):
|
|
|
56
56
|
ranges.append((displacement, displacement + size))
|
|
57
57
|
|
|
58
58
|
|
|
59
|
-
def capture_scopes(state, model):
|
|
59
|
+
def capture_scopes(state, model, frame_bytes=0):
|
|
60
60
|
"""Resolve each scope against the pre-call state and snapshot its bytes.
|
|
61
61
|
|
|
62
62
|
Returns ``(values, unread, descriptions)``: the cached bytes, the unknown term names of bytes
|
|
@@ -68,8 +68,23 @@ def capture_scopes(state, model):
|
|
|
68
68
|
share a linear byte (segment aliases included). A symbolic base may address any byte of its
|
|
69
69
|
segment, so it may alias every scope whose segment range overlaps that segment. An uncached
|
|
70
70
|
byte stays uncached after the call.
|
|
71
|
+
|
|
72
|
+
``frame_bytes`` is the size of the return frame the processor writes below SS:SP when the modeled
|
|
73
|
+
instruction runs: the return address of a call, or FLAGS, CS and IP of an interrupt. Those bytes
|
|
74
|
+
no longer hold their pre-call values, so a scope that shares a byte with that frame on the same
|
|
75
|
+
segment and base raises ``StopPath``. A scope that only may alias the frame stays the query's
|
|
76
|
+
hypothesis.
|
|
71
77
|
"""
|
|
72
78
|
values, unread, descriptions, resolved = {}, {}, [], []
|
|
79
|
+
frame = None
|
|
80
|
+
if frame_bytes:
|
|
81
|
+
try:
|
|
82
|
+
frame_seg, frame_base, _, frame_keys = state.keys(
|
|
83
|
+
state.segment("ss"), op("sub", state.reg(state.sp), const(frame_bytes, state.bits)), frame_bytes)
|
|
84
|
+
frame = ((frame_seg, frame_base), set(frame_keys))
|
|
85
|
+
except StopPath:
|
|
86
|
+
# A frame that wraps past offset zero of the stack segment is not checked.
|
|
87
|
+
frame = None
|
|
73
88
|
for scope in model.get("preservesMemory", []):
|
|
74
89
|
segment, base = state.segment(scope["segment"]), state.reg(scope["base"])
|
|
75
90
|
if segment.number is None:
|
|
@@ -91,6 +106,8 @@ def capture_scopes(state, model):
|
|
|
91
106
|
shared = domains_may_overlap(prior_domain, domain)
|
|
92
107
|
if shared:
|
|
93
108
|
raise StopPath("preservesMemory intervals overlap or alias")
|
|
109
|
+
if frame is not None and frame[0] == (seg, group_base) and not frame[1].isdisjoint(keys):
|
|
110
|
+
raise StopPath("preservesMemory scope covers the return frame the processor writes below SP")
|
|
94
111
|
resolved.append(((seg, group_base), set(keys), domain))
|
|
95
112
|
linear = seg == ("linear",)
|
|
96
113
|
cached = 0
|
|
@@ -6,7 +6,7 @@ whose paths were not all read (a stop, a limit, a dropped path) is undecided, ne
|
|
|
6
6
|
"""
|
|
7
7
|
from bisect import bisect_right
|
|
8
8
|
from .image import integer
|
|
9
|
-
from .machine import ALIASES, State
|
|
9
|
+
from .machine import ALIASES, NO_WRITE, State
|
|
10
10
|
|
|
11
11
|
KINDS = ("reach", "order", "lastWriter", "containment", "relation", "origin")
|
|
12
12
|
OPERATORS = ("eq", "ne", "lt", "le", "gt", "ge")
|
|
@@ -333,7 +333,7 @@ class _Path:
|
|
|
333
333
|
# Orders of modeled call returns, ascending.
|
|
334
334
|
self.modeled = []
|
|
335
335
|
# Unknown memory term name -> the first order of a read that showed its bytes had no
|
|
336
|
-
# modeled value for a reason other than
|
|
336
|
+
# modeled value for a reason other than NO_WRITE.
|
|
337
337
|
self.first_drop = {}
|
|
338
338
|
# For each event, the most recent branch earlier in the same frame (same entry and depth,
|
|
339
339
|
# completed callee frames skipped), or None.
|
|
@@ -343,7 +343,7 @@ class _Path:
|
|
|
343
343
|
self.by_site.setdefault((e["site"], e["kind"]), []).append(e["order"])
|
|
344
344
|
if e["kind"] == "call-return" and e.get("modeled"):
|
|
345
345
|
self.modeled.append(e["order"])
|
|
346
|
-
if e["kind"] == "read" and any((r.get("unwritten") or {}).get("cause",
|
|
346
|
+
if e["kind"] == "read" and any((r.get("unwritten") or {}).get("cause", NO_WRITE) != NO_WRITE
|
|
347
347
|
for r in e.get("byteProducers", ())):
|
|
348
348
|
for n in _leaves(e["value"]["expression"], set()):
|
|
349
349
|
if n.startswith("memory:"):
|
|
@@ -525,7 +525,7 @@ def _occurrence(control, path, anchor, image):
|
|
|
525
525
|
"writer": {"site": writer["site"], "order": writer["order"], "entry": writer["entry"], "depth": writer["depth"]}})
|
|
526
526
|
else:
|
|
527
527
|
unwritten = row.get("unwritten") or {"cause": "unknown", "order": None}
|
|
528
|
-
verdict = (("held" if ENTRY_STATE in allowed else "violated") if unwritten["cause"] ==
|
|
528
|
+
verdict = (("held" if ENTRY_STATE in allowed else "violated") if unwritten["cause"] == NO_WRITE
|
|
529
529
|
else "undecided")
|
|
530
530
|
rows.append({"index": row["index"], "verdict": verdict, "writer": None, "unwritten": unwritten})
|
|
531
531
|
verdicts.append(verdict)
|
|
@@ -10,6 +10,7 @@ from .values import const, unknown, sources, op, Value
|
|
|
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
|
+
from .pcode_backend import interrupt_vector
|
|
13
14
|
|
|
14
15
|
def call_target(image, site, ins):
|
|
15
16
|
if ins.mnemonic in ("lcall", "ljmp"):
|
|
@@ -27,6 +28,19 @@ PORTS = ("in", "out", "insb", "insw", "insd", "outsb", "outsw", "outsd")
|
|
|
27
28
|
PORT_INPUTS = ("in", "insb", "insw", "insd")
|
|
28
29
|
|
|
29
30
|
|
|
31
|
+
def modeled_interrupt(image, ins, site):
|
|
32
|
+
"""The vector of the ``INT n`` at ``site`` that a call model there describes, or None.
|
|
33
|
+
|
|
34
|
+
Only an ``INT n`` in the real-mode model takes a model. INT1, INT3 (also when encoded as
|
|
35
|
+
``INT 1`` or ``INT 3``), INTO and every interrupt in the PE32 flat model keep stopping the path,
|
|
36
|
+
with or without a model at their site (ADR 0017). The vector can be 0, so test it against None.
|
|
37
|
+
"""
|
|
38
|
+
if ins is None or ins.mnemonic != "int" or image.flat:
|
|
39
|
+
return None
|
|
40
|
+
vector, _ = interrupt_vector(image.flat, ins, site)
|
|
41
|
+
return None if vector in (1, 3) else vector
|
|
42
|
+
|
|
43
|
+
|
|
30
44
|
def base_mnemonic(ins):
|
|
31
45
|
# Capstone names REP/REPNE/BND prefixes in the mnemonic ("repz ret", "rep insb", "bnd jmp").
|
|
32
46
|
return ins.mnemonic.split()[-1]
|
|
@@ -453,6 +467,11 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
453
467
|
raise ValueError("A model requires 1..16 return cases")
|
|
454
468
|
if "returnBytes" in model and (type(model["returnBytes"]) is not int or model["returnBytes"] not in (2, 4)):
|
|
455
469
|
raise ValueError("Modeled returnBytes must be 2 or 4")
|
|
470
|
+
if "returnBytes" in model and modeled_interrupt(image, image.decode(model["site"]), model["site"]) is not None:
|
|
471
|
+
raise ValueError("An interrupt model takes no returnBytes: the interrupt returns past its own FLAGS, CS and IP")
|
|
472
|
+
if "leavesFlags" in model and (model["leavesFlags"] is not True
|
|
473
|
+
or modeled_interrupt(image, image.decode(model["site"]), model["site"]) is None):
|
|
474
|
+
raise ValueError("leavesFlags must be true and needs an INT n site in the real-mode model")
|
|
456
475
|
if any(r not in REGISTERS for r in model.get("preserves", [])):
|
|
457
476
|
raise ValueError("Model preserves must name full registers")
|
|
458
477
|
validate_scopes(model, image.bits, image.flat)
|
|
@@ -460,6 +479,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
460
479
|
for r, n in case.get("registers", {}).items():
|
|
461
480
|
if r not in ALIASES or type(n) is not int or not 0 <= n < 1 << ALIASES[r][2]:
|
|
462
481
|
raise ValueError("Invalid model register")
|
|
482
|
+
model_at = {model["site"]: model for model in models}
|
|
463
483
|
explicit_continuation_budget = validate_continuation_budget(config)
|
|
464
484
|
observed_frame = entry_frame(image, config, entry) if arrive is None else None
|
|
465
485
|
root = State(entry, image, config)
|
|
@@ -515,6 +535,52 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
515
535
|
gap["callStack"] = open_calls(s)
|
|
516
536
|
global_gaps.append(gap)
|
|
517
537
|
|
|
538
|
+
def capture_model_scopes(s, model, frame_bytes):
|
|
539
|
+
# Scopes resolve against the state before the modeled instruction runs. frame_bytes is the
|
|
540
|
+
# return frame the processor writes below SP, which no scope may claim to preserve.
|
|
541
|
+
values, unread, scopes = capture_scopes(s, model, frame_bytes)
|
|
542
|
+
return values, unread, scopes, scope_history(s, values, unread)
|
|
543
|
+
|
|
544
|
+
def model_returns(s, model, captured, following, assumption, limit_reason, target, **marks):
|
|
545
|
+
# One child per case, each a conditional return under the query's model. ``marks`` extend
|
|
546
|
+
# the conditionalModels entry and the modeled call-return event (an interrupt's vector).
|
|
547
|
+
nonlocal created
|
|
548
|
+
at = s.at
|
|
549
|
+
kept_values, kept_unread, preserved_scopes, kept_history = captured
|
|
550
|
+
for case in model["cases"]:
|
|
551
|
+
if created >= max_paths:
|
|
552
|
+
path_limit(at, s, limit_reason)
|
|
553
|
+
break
|
|
554
|
+
child = deepcopy(s)
|
|
555
|
+
created += 1
|
|
556
|
+
for r in REGISTERS:
|
|
557
|
+
if r not in model.get("preserves", []) and r not in ("esp", "cs"):
|
|
558
|
+
child.setreg(r, unknown(f"modeled-call:{at}:{r}", ALIASES[r][2]), at)
|
|
559
|
+
child.clear_memory()
|
|
560
|
+
retain_scopes(child, kept_values, kept_unread, kept_history)
|
|
561
|
+
if model.get("leavesFlags"):
|
|
562
|
+
# The handler returned with a far return over the interrupt's FLAGS word, which stays on
|
|
563
|
+
# the stack. Its word is the pre-interrupt FLAGS snapshot, so a later POPF restores them.
|
|
564
|
+
child.save_flags(16)
|
|
565
|
+
child.forget_flags()
|
|
566
|
+
child.direction_flag = unknown(f"modeled-call:{at}:DF:{child.flag_serial}", 1, at)
|
|
567
|
+
child.interrupt_flag = unknown(f"modeled-call:{at}:IF:{child.flag_serial}", 1, at)
|
|
568
|
+
for r, n in case.get("registers", {}).items():
|
|
569
|
+
child.setreg(r, const(n, ALIASES[r][2], at), at)
|
|
570
|
+
child.conditional.append({"site": at, "evidence": model["evidence"], **marks,
|
|
571
|
+
"assumption": assumption + "; memory effects unresolved"
|
|
572
|
+
+ (" outside explicit scopes" if preserved_scopes else ""),
|
|
573
|
+
"preservedMemoryScopes": preserved_scopes})
|
|
574
|
+
# The scopes are reported once, on the path's conditionalModels entry; the event cites its index.
|
|
575
|
+
child.event("call-return", callSite=at, callerEntry=s.frames[-1]["entry"],
|
|
576
|
+
# A modeled call's result contracts are its target's; an interrupt's target is None,
|
|
577
|
+
# which no contract names.
|
|
578
|
+
resultContracts=result_contracts(child, contracts, target),
|
|
579
|
+
registers=snapshot(child), modeled=True, **marks,
|
|
580
|
+
unknownMemoryEffects=True, conditionalModel=len(child.conditional) - 1)
|
|
581
|
+
child.at = following
|
|
582
|
+
pending.append(child)
|
|
583
|
+
|
|
518
584
|
def finish(s, reason=None, returned=False):
|
|
519
585
|
if continuing and reason and reason.startswith(STRING_BUDGET_STOP):
|
|
520
586
|
# machine.py names no budget; a continuation's string iterations come from continuationBudget.
|
|
@@ -712,6 +778,27 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
712
778
|
string_step(state, ins, count)
|
|
713
779
|
state.at = following
|
|
714
780
|
continue
|
|
781
|
+
interrupt_model = model_at.get(at) if m == "int" else None
|
|
782
|
+
vector = modeled_interrupt(image, ins, at) if interrupt_model else None
|
|
783
|
+
if vector is not None:
|
|
784
|
+
# The handler is not executed. The boundary event is kept, and each case returns to the
|
|
785
|
+
# next instruction under the query's model, with CS as before the interrupt and SP as before it or,
|
|
786
|
+
# under leavesFlags, one FLAGS word below (ADR 0017).
|
|
787
|
+
# Scopes resolve first, so a path that stops on them reports the boundary unmodeled.
|
|
788
|
+
try:
|
|
789
|
+
captured = capture_model_scopes(state, interrupt_model, 6)
|
|
790
|
+
except StopPath:
|
|
791
|
+
state.event("hardware-boundary", boundary="interrupt", mnemonic=m, vector=vector,
|
|
792
|
+
interpretation="the interrupt handler and its effects are not modeled")
|
|
793
|
+
raise
|
|
794
|
+
state.event("hardware-boundary", boundary="interrupt", mnemonic=m, vector=vector, modeled=True,
|
|
795
|
+
interpretation="the interrupt handler is not executed; a callModels case supplies its return")
|
|
796
|
+
model_returns(state, interrupt_model, captured, following,
|
|
797
|
+
"interrupt returns to the next instruction with its FLAGS word left on the stack and CS unchanged"
|
|
798
|
+
if interrupt_model.get("leavesFlags") else
|
|
799
|
+
"interrupt returns to the next instruction with balanced stack and CS unchanged",
|
|
800
|
+
"path limit at modeled interrupt", None, boundary="interrupt", vector=vector)
|
|
801
|
+
break
|
|
715
802
|
if m in ("call", "lcall"):
|
|
716
803
|
target, provenance = call_target(image, at, ins)
|
|
717
804
|
indirect_value = None
|
|
@@ -730,7 +817,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
730
817
|
push_cs = (not image.flat and m == "call" and previous is not None and previous.mnemonic == "push"
|
|
731
818
|
and previous.size + state.path[-2] == at and previous.operands[0].type == X86_OP_REG
|
|
732
819
|
and previous.reg_name(previous.operands[0].reg) == "cs" and previous.operands[0].size == 2)
|
|
733
|
-
model =
|
|
820
|
+
model = model_at.get(at)
|
|
734
821
|
if model:
|
|
735
822
|
return_bytes = model.get("returnBytes", 4 if m == "lcall" else image.bits // 8)
|
|
736
823
|
# The encoding before the call decides validity; a path that reaches the call
|
|
@@ -745,38 +832,13 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
|
|
|
745
832
|
raise StopPath("push-CS/near-call model requires an explicit four-byte return contract")
|
|
746
833
|
# Scopes resolve against the pre-call state: before the modeled frame consumes an
|
|
747
834
|
# already-pushed CS word and before a case replaces registers.
|
|
748
|
-
|
|
749
|
-
kept_history = scope_history(state, kept_values, kept_unread)
|
|
835
|
+
captured = capture_model_scopes(state, model, 4 if m == "lcall" else image.bits // 8)
|
|
750
836
|
if push_cs:
|
|
751
837
|
actual_cs = state.pop(2)
|
|
752
838
|
if actual_cs.term != state.reg("cs").term:
|
|
753
839
|
raise StopPath("modeled far return segment changed")
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
path_limit(at, state, "path limit at modeled call")
|
|
757
|
-
break
|
|
758
|
-
child = deepcopy(state)
|
|
759
|
-
created += 1
|
|
760
|
-
for r in REGISTERS:
|
|
761
|
-
if r not in model.get("preserves", []) and r not in ("esp", "cs"):
|
|
762
|
-
child.setreg(r, unknown(f"modeled-call:{at}:{r}", ALIASES[r][2]), at)
|
|
763
|
-
child.clear_memory()
|
|
764
|
-
retain_scopes(child, kept_values, kept_unread, kept_history)
|
|
765
|
-
child.forget_flags()
|
|
766
|
-
child.direction_flag = unknown(f"modeled-call:{at}:DF:{child.flag_serial}", 1, at)
|
|
767
|
-
child.interrupt_flag = unknown(f"modeled-call:{at}:IF:{child.flag_serial}", 1, at)
|
|
768
|
-
for r, n in case.get("registers", {}).items():
|
|
769
|
-
child.setreg(r, const(n, ALIASES[r][2], at), at)
|
|
770
|
-
child.conditional.append({"site": at, "evidence": model["evidence"],
|
|
771
|
-
"assumption": "call returns with balanced stack; memory effects unresolved"
|
|
772
|
-
+ (" outside explicit scopes" if preserved_scopes else ""),
|
|
773
|
-
"preservedMemoryScopes": preserved_scopes})
|
|
774
|
-
# The scopes are reported once, on the path's conditionalModels entry; the event cites its index.
|
|
775
|
-
child.event("call-return", callSite=at, callerEntry=state.frames[-1]["entry"],
|
|
776
|
-
resultContracts=result_contracts(child, contracts, target), registers=snapshot(child), modeled=True,
|
|
777
|
-
unknownMemoryEffects=True, conditionalModel=len(child.conditional) - 1)
|
|
778
|
-
child.at = following
|
|
779
|
-
pending.append(child)
|
|
840
|
+
model_returns(state, model, captured, following, "call returns with balanced stack",
|
|
841
|
+
"path limit at modeled call", target)
|
|
780
842
|
break
|
|
781
843
|
if target is None:
|
|
782
844
|
raise StopPath("unresolved call: " + provenance.get("reason", "outside mapped code"))
|