scientific-method-engine 19.4.0__tar.gz → 19.6.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-19.4.0 → scientific_method_engine-19.6.0}/PKG-INFO +1 -1
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/pyproject.toml +1 -1
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/cli.py +8 -3
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/dispatch.py +100 -11
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/inventory.py +11 -6
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/pcode_backend.py +5 -1
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/reach.py +213 -42
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/trace.py +4 -4
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_inventory_check.py +28 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_reach.py +232 -6
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/.gitignore +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/LICENSE +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/README.md +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/__init__.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/__main__.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportRangeBoundaries.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/ghidra/scientificmethod/Xxh3.java +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/__init__.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/derived_counts.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/image.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/loops.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/machine.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/pcode.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/pe.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/ranges.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/relational.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/reports.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/table_bounds.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/src/scientific_method_engine/x86/values.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/oracle.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_config_encoding.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_continuation_budget.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_derived_counts.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_dispatch.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_effect_order.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_enter_frames.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_entry_frame.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_indirect_far_transfers.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_interrupt_models.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_join_terms.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_loops.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_memory_scopes.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_nested_frame_request.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_oracle.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_pe.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_ranges.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_relational_controls.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_return_checks.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_successor_rule.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_table_bounds.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_table_continuations.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_term_limit.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_upstream_gaps.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.0}/tests/test_volatile_memory.py +0 -0
- {scientific_method_engine-19.4.0 → scientific_method_engine-19.6.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: 19.
|
|
3
|
+
Version: 19.6.0
|
|
4
4
|
Summary: Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code.
|
|
5
5
|
Project-URL: Source, https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine
|
|
6
6
|
Author: kibertoad
|
|
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "scientific-method-engine"
|
|
7
7
|
# The release workflow writes the published version from the package's release tag.
|
|
8
|
-
version = "19.
|
|
8
|
+
version = "19.6.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"
|
|
@@ -22,7 +22,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
|
|
|
22
22
|
"continues past one the engine stops at (ghidraContinues),\n"
|
|
23
23
|
"or continues at another address than the next instruction (ghidraFallsThroughElsewhere).\n"
|
|
24
24
|
"reach lists the target sites the starts reach over resolved calls and jumps, with the fewest-call chain\n"
|
|
25
|
-
"and the routines every read route passes, and
|
|
25
|
+
"and the routines every read route passes, and the starts each target is reached from (reachedFrom),\n"
|
|
26
|
+
"and lists every reached transfer it could not resolve;\n"
|
|
26
27
|
"a leaves routine is reached but not read, and its reason is repeated in the report;\n"
|
|
27
28
|
"a call to a noReturn routine, a noReturn call and a noReturn interrupt do not continue at the next\n"
|
|
28
29
|
"instruction, a noReturn routine with a return, or a jump into a returning leaf, on its own read paths\n"
|
|
@@ -32,14 +33,18 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
|
|
|
32
33
|
"is followed, and each is repeated with its reason and where it cut the walk, not checked or assumed;\n"
|
|
33
34
|
"the noReturn check reads past the stops, and returnCheckGaps lists what it could not read there;\n"
|
|
34
35
|
"indirectCalls declares the targets of a computed call as a table read from the build or a list,\n"
|
|
35
|
-
"and the walk calls each of them; one not declared exhaustive stays unresolved
|
|
36
|
+
"and the walk calls each of them; one not declared exhaustive stays unresolved; outside names where the\n"
|
|
37
|
+
"call leaves the image (a saved vector, an interrupt's returned pointer or a description), which is not\n"
|
|
38
|
+
"read and is grouped in outsideTransfers, and an exhaustive empty targets list says the call never runs;\n"
|
|
36
39
|
"an exhaustive indirectJumps or indirectCalls table can leave out count and give bound {routine}:\n"
|
|
37
40
|
"the engine derives its rows from a value-range analysis of that routine and lists the derivation,\n"
|
|
38
41
|
"a count it cannot prove leaves the site unresolved with its reasons, a declared count larger than\n"
|
|
39
42
|
"the proven one is refused, and a walk edge that enters the routine other than at its start is a gap;\n"
|
|
40
43
|
"controls are call sites the walk must reach and resolve, instructionControls sites it must decode,\n"
|
|
41
44
|
"and a failed control fails the report saying whether it was reached;\n"
|
|
42
|
-
"decodedRanges true lists every instruction the walk decoded as half-open ranges with their routine
|
|
45
|
+
"decodedRanges true lists every instruction the walk decoded as half-open ranges with their routine;\n"
|
|
46
|
+
"startRoutes true gives each reached target, for each start it is reached from, the fewest calls and the\n"
|
|
47
|
+
"routines every read route from that start passes.\n"
|
|
43
48
|
"inventory-check places every resolved direct call target in the notation of the function inventory TSV\n"
|
|
44
49
|
"that inventory names and lists each target no row starts at: inside another row's body or outside every row,\n"
|
|
45
50
|
"with one calling site, near or far, and whether an entry-path call, a contested one or only raw bytes call it;\n"
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
"""Explicit, source-derived indirect jump tables and call targets for CFG discovery, and explicitly conditional path continuations."""
|
|
2
2
|
from capstone.x86 import X86_OP_IMM, X86_OP_MEM
|
|
3
3
|
from .image import integer
|
|
4
|
+
from .pcode_backend import interrupt_vector, INTERRUPTS
|
|
4
5
|
|
|
5
6
|
CALL_NOT_EXHAUSTIVE = "indirect call targets are not declared exhaustive"
|
|
6
7
|
JUMP_NOT_EXHAUSTIVE = "indirect jump table is not declared exhaustive"
|
|
@@ -214,7 +215,12 @@ def indirect_call_declarations(value, image):
|
|
|
214
215
|
|
|
215
216
|
Each declaration names a ``site`` that decodes as an unprefixed segmented16 computed call (a near
|
|
216
217
|
call through a word register or memory operand, or a far call through memory), its ``evidence``,
|
|
217
|
-
an explicit boolean ``exhaustive``,
|
|
218
|
+
an explicit boolean ``exhaustive``, at most one of ``table`` and ``targets``, and ``outside`` when
|
|
219
|
+
it has neither (ADR 0042). ``outside`` states that the call can leave the declared code, for one
|
|
220
|
+
stated destination: a saved interrupt ``vector``, the far pointer an ``interrupt`` site returned,
|
|
221
|
+
or a ``description`` of other code outside the image; it is returned normalized by
|
|
222
|
+
``outside_destination``. An exhaustive declaration may give an empty ``targets`` list, which states
|
|
223
|
+
that the call never runs. A table's rows are
|
|
218
224
|
read from the source bytes as ``indirectJumps`` reads them: words placed through the call site's
|
|
219
225
|
region mapping for a near call, and for a far call ``offset, segment`` word pairs whose segment
|
|
220
226
|
word has a declared relocation, admitted as ``Image.far_pointer_target`` admits the pointer a
|
|
@@ -235,9 +241,11 @@ def indirect_call_declarations(value, image):
|
|
|
235
241
|
result = {}
|
|
236
242
|
image.derived_call_reads = {}
|
|
237
243
|
for claim in value:
|
|
238
|
-
keys = set(claim) if isinstance(claim, dict) else None
|
|
239
|
-
|
|
240
|
-
|
|
244
|
+
keys = set(claim) - {"outside"} if isinstance(claim, dict) else None
|
|
245
|
+
base = {"site", "evidence", "exhaustive"}
|
|
246
|
+
if keys not in (base | {"table"}, base | {"targets"}) and not (keys == base and "outside" in claim):
|
|
247
|
+
raise ValueError("Each indirect call needs site, evidence, exhaustive, at most one of table and targets, "
|
|
248
|
+
"and outside when it has neither")
|
|
241
249
|
site = integer(claim["site"], 0, len(image.data) - 1, "indirect call site")
|
|
242
250
|
if site in result:
|
|
243
251
|
raise ValueError("Duplicate indirect call site")
|
|
@@ -254,7 +262,12 @@ def indirect_call_declarations(value, image):
|
|
|
254
262
|
"or a far call through memory")
|
|
255
263
|
declaration = {"site": site, "instruction": (ins.mnemonic + " " + ins.op_str).strip(),
|
|
256
264
|
"evidence": claim["evidence"], "exhaustive": claim["exhaustive"]}
|
|
257
|
-
if "
|
|
265
|
+
if "outside" in claim:
|
|
266
|
+
declaration["outside"] = outside_destination(claim["outside"], image, site, far)
|
|
267
|
+
if "table" not in claim and "targets" not in claim:
|
|
268
|
+
# An outside destination alone: the call names no target in declared code.
|
|
269
|
+
targets = []
|
|
270
|
+
elif "table" in claim:
|
|
258
271
|
table, width = claim["table"], 4 if far else 2
|
|
259
272
|
if not isinstance(table, dict) or not isinstance(table.get("evidence"), str) or not table["evidence"].strip():
|
|
260
273
|
raise ValueError("An indirect call table needs layout/count evidence")
|
|
@@ -279,9 +292,15 @@ def indirect_call_declarations(value, image):
|
|
|
279
292
|
targets = [row["target"] for row in rows]
|
|
280
293
|
else:
|
|
281
294
|
targets = claim["targets"]
|
|
282
|
-
if (not isinstance(targets, list) or
|
|
295
|
+
if (not isinstance(targets, list) or len(targets) > 256
|
|
283
296
|
or len(set(map(repr, targets))) != len(targets)):
|
|
284
|
-
raise ValueError("indirect call targets must be a list of
|
|
297
|
+
raise ValueError("indirect call targets must be a list of 0..256 distinct file offsets")
|
|
298
|
+
# No targets says the call never runs, which only an exhaustive declaration without an outside
|
|
299
|
+
# destination can state; anything else would be an undeclared call with extra words.
|
|
300
|
+
if not targets and (not claim["exhaustive"] or "outside" in claim):
|
|
301
|
+
raise ValueError(f"indirect call {site} declares no targets, which states that the call never runs; "
|
|
302
|
+
"that needs exhaustive true and no outside (give outside alone for a call that "
|
|
303
|
+
"leaves the declared code)")
|
|
285
304
|
for at in targets:
|
|
286
305
|
integer(at, 0, len(image.data) - 1, "indirect call target")
|
|
287
306
|
region = image.region(at)
|
|
@@ -298,6 +317,50 @@ def indirect_call_declarations(value, image):
|
|
|
298
317
|
return result
|
|
299
318
|
|
|
300
319
|
|
|
320
|
+
def declared_interrupt(image, at, label, conditional_reason):
|
|
321
|
+
"""``(ins, vector)`` for the unconditional interrupt instruction at ``at``, which a declaration names as ``label``.
|
|
322
|
+
|
|
323
|
+
``at`` must lie in declared code and decode as an interrupt, whatever prefix capstone names in the
|
|
324
|
+
mnemonic; a conditional interrupt (INTO) is refused with ``conditional_reason``.
|
|
325
|
+
"""
|
|
326
|
+
if image.region(at) is None:
|
|
327
|
+
raise ValueError(f"{label} {at} is outside declared code")
|
|
328
|
+
ins = image.decode(at)
|
|
329
|
+
if ins is None or ins.mnemonic.split()[-1] not in INTERRUPTS:
|
|
330
|
+
raise ValueError(f"{label} {at} is not an interrupt instruction")
|
|
331
|
+
vector, conditional = interrupt_vector(image.flat, ins, at)
|
|
332
|
+
if conditional:
|
|
333
|
+
raise ValueError(f"{label} {at} is conditional {conditional_reason}")
|
|
334
|
+
return ins, vector
|
|
335
|
+
|
|
336
|
+
|
|
337
|
+
def outside_destination(value, image, site, far):
|
|
338
|
+
"""The normalized ``outside`` destination of the declared indirect call at ``site``.
|
|
339
|
+
|
|
340
|
+
``value`` names exactly one of ``vector`` (0..255: the call enters the handler that held that
|
|
341
|
+
interrupt vector before the program replaced it), ``interrupt`` (a file offset in declared code
|
|
342
|
+
that decodes as an unconditional interrupt instruction: the call goes through the far pointer
|
|
343
|
+
that interrupt returned, and the result adds the interrupt's ``vector`` and ``instruction``) or
|
|
344
|
+
``description`` (nonempty free text naming other code outside the image, such as code built on
|
|
345
|
+
the stack or a table a loaded driver fills). A saved vector and an interrupt's returned pointer
|
|
346
|
+
are far pointers, so those two need a far call.
|
|
347
|
+
"""
|
|
348
|
+
if not isinstance(value, dict) or len(value) != 1 or set(value) - {"vector", "interrupt", "description"}:
|
|
349
|
+
raise ValueError(f"indirect call {site} outside needs exactly one of vector, interrupt and description")
|
|
350
|
+
kind, given = next(iter(value.items()))
|
|
351
|
+
if kind != "description" and not far:
|
|
352
|
+
raise ValueError(f"indirect call {site} outside {kind} names a far pointer, which a near call cannot use")
|
|
353
|
+
if kind == "vector":
|
|
354
|
+
return {"vector": integer(given, 0, 255, "outside vector")}
|
|
355
|
+
if kind == "description":
|
|
356
|
+
if not isinstance(given, str) or not given.strip():
|
|
357
|
+
raise ValueError(f"indirect call {site} outside description must be nonempty text")
|
|
358
|
+
return {"description": given}
|
|
359
|
+
at = integer(given, 0, len(image.data) - 1, "outside interrupt")
|
|
360
|
+
ins, vector = declared_interrupt(image, at, f"indirect call {site} outside interrupt", "and may return nothing")
|
|
361
|
+
return {"interrupt": at, "vector": vector, "instruction": (ins.mnemonic + " " + ins.op_str).strip()}
|
|
362
|
+
|
|
363
|
+
|
|
301
364
|
def open_reason(declaration, call):
|
|
302
365
|
"""Why a declared table or call leaves its site unresolved, or None.
|
|
303
366
|
|
|
@@ -321,11 +384,37 @@ def derived_assumptions(image, indirect_calls):
|
|
|
321
384
|
return []
|
|
322
385
|
|
|
323
386
|
|
|
387
|
+
def never_runs(declaration):
|
|
388
|
+
"""Whether a declared indirect call states that it never runs: exhaustive, with an empty ``targets`` list
|
|
389
|
+
and no outside. A table whose count was not proven also has no targets, but it is unresolved, not empty."""
|
|
390
|
+
return (declaration["exhaustive"] and "table" not in declaration and not declaration["targets"]
|
|
391
|
+
and "outside" not in declaration)
|
|
392
|
+
|
|
393
|
+
|
|
324
394
|
def declared_call_ends(declaration, no_return_calls):
|
|
325
|
-
"""Whether a declared indirect call ends its branch: nothing leaves it unresolved (``open_reason``)
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
395
|
+
"""Whether a declared indirect call ends its branch: nothing leaves it unresolved (``open_reason``), it
|
|
396
|
+
has no ``outside`` destination (which the walk does not read, so it is assumed to return), and every
|
|
397
|
+
target is in ``no_return_calls``.
|
|
398
|
+
|
|
399
|
+
A declaration that ``never_runs`` ends its branch, since the next instruction is reached through the
|
|
400
|
+
call only once it has run.
|
|
401
|
+
"""
|
|
402
|
+
return (open_reason(declaration, True) is None and "outside" not in declaration
|
|
403
|
+
and all(target in no_return_calls for target in declaration["targets"]))
|
|
404
|
+
|
|
405
|
+
|
|
406
|
+
def indirect_call_assumptions(indirect_calls):
|
|
407
|
+
"""The assumptions the ``indirectCalls`` declarations add to a report."""
|
|
408
|
+
if not indirect_calls:
|
|
409
|
+
return []
|
|
410
|
+
found = ["each declared indirect call can call the targets its declaration gives, for the evidence it gives, "
|
|
411
|
+
"and only those when it is declared exhaustive"]
|
|
412
|
+
if any("outside" in declaration for declaration in indirect_calls.values()):
|
|
413
|
+
found.append("each declared outside destination is where its call can leave the declared code, for the "
|
|
414
|
+
"evidence it gives; the code there is not read, and it returns to the call's next instruction")
|
|
415
|
+
if any(never_runs(declaration) for declaration in indirect_calls.values()):
|
|
416
|
+
found.append("each indirect call declared exhaustive with no targets never runs, for the evidence it gives")
|
|
417
|
+
return found
|
|
329
418
|
|
|
330
419
|
|
|
331
420
|
def call_ends(site, target, indirect_calls, no_return_calls):
|
|
@@ -4,7 +4,7 @@ from bisect import bisect_right
|
|
|
4
4
|
from pathlib import Path
|
|
5
5
|
from .image import integer
|
|
6
6
|
from .trace import LIMIT_REASON, CONTESTED_REASON, OVERLAP_REASON, walk, holding_instruction
|
|
7
|
-
from .dispatch import indirect_call_declarations, call_ends, derived_assumptions
|
|
7
|
+
from .dispatch import indirect_call_declarations, call_ends, never_runs, indirect_call_assumptions, derived_assumptions
|
|
8
8
|
|
|
9
9
|
MAX_INVENTORY = 16 * 1024 * 1024
|
|
10
10
|
MAX_ROWS = 200000
|
|
@@ -425,6 +425,11 @@ def inventory_check(image, config):
|
|
|
425
425
|
def site_classification(at):
|
|
426
426
|
return "entry-path instruction" if at in seen else CONTESTED_REASON if at in contested else "declared site"
|
|
427
427
|
listed = {site for site, *_ in ends}
|
|
428
|
+
# A call declared never to run has no target, so no call row holds it, yet it ends the branch as an
|
|
429
|
+
# exhaustive call whose every target is noReturn does; it is listed as one with no routines.
|
|
430
|
+
never = [at for at, declaration in indirect_calls.items() if never_runs(declaration)]
|
|
431
|
+
ends += [(at, image.decode(at).size, "call", [], site_classification(at)) for at in never]
|
|
432
|
+
listed |= set(never)
|
|
428
433
|
ends += [(at, row["following"] - at, "call site",
|
|
429
434
|
site_targets[at][0] if len(site_targets[at]) == 1 else site_targets[at] or None, site_classification(at))
|
|
430
435
|
for at, row in no_return_sites.items() if at not in listed]
|
|
@@ -528,15 +533,13 @@ def inventory_check(image, config):
|
|
|
528
533
|
if target_stopped:
|
|
529
534
|
summary += (" The walk that checks the targets of the noReturn calls stopped at its instruction limit, so it "
|
|
530
535
|
"can miss returns.")
|
|
531
|
-
assumptions = [call_assumption(no_return_routines, no_return_sites)]
|
|
536
|
+
assumptions = [call_assumption(no_return_routines, no_return_sites, indirect_calls)]
|
|
532
537
|
if checked:
|
|
533
538
|
assumptions.append("each interrupt the noReturn check reads returns to its next instruction"
|
|
534
539
|
+ (", except at a noReturn interrupt site" if no_return_interrupts else "")
|
|
535
540
|
+ "; interrupt handlers are not read")
|
|
536
541
|
assumptions += no_return_assumptions(no_return_routines, no_return_interrupts, no_return_sites)
|
|
537
|
-
|
|
538
|
-
assumptions.append("each declared indirect call can call the targets its declaration gives, for the evidence "
|
|
539
|
-
"it gives, and only those when it is declared exhaustive")
|
|
542
|
+
assumptions += indirect_call_assumptions(indirect_calls)
|
|
540
543
|
assumptions += derived_assumptions(image, indirect_calls)
|
|
541
544
|
indirect_rows = [declaration | {"reached": site in seen} for site, declaration in indirect_calls.items()]
|
|
542
545
|
return {"inventory": {"path": config["inventory"], "rows": len(rows)},
|
|
@@ -556,7 +559,9 @@ def inventory_check(image, config):
|
|
|
556
559
|
"partialSearch": partial, "gaps": calls["gaps"],
|
|
557
560
|
"exclusions": ["computed call targets no indirectCalls declaration gives (listed in unresolved when the "
|
|
558
561
|
"walk reaches them)", "unrelocated far calls",
|
|
559
|
-
"undeclared mappings", "prefix-started raw candidates off the entry path", "jump targets"]
|
|
562
|
+
"undeclared mappings", "prefix-started raw candidates off the entry path", "jump targets"]
|
|
563
|
+
+ (["the code a declared outside destination names, and anything it calls"]
|
|
564
|
+
if any("outside" in declaration for declaration in indirect_calls.values()) else []),
|
|
560
565
|
"interpretation": "Each distinct resolved direct call target in the searched regions, placed in the inventory's "
|
|
561
566
|
"notation and compared with its rows. A target only raw byte candidates or contested "
|
|
562
567
|
"instructions call is not shown to be code. The counts are lower bounds on the targets "
|
|
@@ -988,6 +988,10 @@ def port_access(state, ins, direction, port, value, size):
|
|
|
988
988
|
return result
|
|
989
989
|
|
|
990
990
|
|
|
991
|
+
# The interrupt mnemonics, as capstone names them without a prefix.
|
|
992
|
+
INTERRUPTS = ("int", "int1", "int3", "into")
|
|
993
|
+
|
|
994
|
+
|
|
991
995
|
def interrupt_vector(flat, ins, site):
|
|
992
996
|
"""The vector p-code's ``swi`` operation names, and whether the interrupt is conditional (INTO)."""
|
|
993
997
|
ops, _ = LIFTER.ops(flat, bytes(ins.bytes), site)
|
|
@@ -1015,7 +1019,7 @@ for names, handler in ((("mov", "movzx", "movsx", "xchg"), move), (("nop",), nop
|
|
|
1015
1019
|
(("shl", "sal", "shr", "sar"), shift), (("rol", "ror", "rcl", "rcr"), rotate),
|
|
1016
1020
|
(("mul", "imul"), multiply), (("div", "idiv"), divide),
|
|
1017
1021
|
(("cbw", "cwde", "cwd", "cdq"), conversion), (("cld", "std", "cli", "sti"), flag_write),
|
|
1018
|
-
(("in", "out"), run_plain), (
|
|
1022
|
+
(("in", "out"), run_plain), (INTERRUPTS, interrupt)):
|
|
1019
1023
|
for name in names:
|
|
1020
1024
|
HANDLERS[name] = handler
|
|
1021
1025
|
|