scientific-method-engine 3.2.0__tar.gz → 4.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-3.2.0 → scientific_method_engine-4.0.0}/PKG-INFO +5 -3
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/README.md +4 -2
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/pyproject.toml +1 -1
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/cli.py +2 -1
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/result_flow.py +3 -1
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/trace.py +101 -31
- scientific_method_engine-4.0.0/tests/test_continuation_budget.py +179 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_table_continuations.py +4 -2
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/.gitignore +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/LICENSE +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/__init__.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/__main__.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/__init__.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/image.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/loops.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/machine.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/pcode.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/pe.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/relational.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/reports.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/src/scientific_method_engine/x86/values.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/oracle.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_dispatch.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_effect_order.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_loops.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_memory_scopes.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_nested_frame_request.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_oracle.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_pe.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_relational_controls.py +0 -0
- {scientific_method_engine-3.2.0 → scientific_method_engine-4.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: 4.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
|
|
@@ -135,8 +135,10 @@ Evidenced segmented16 `indirectJumps` declarations also expose separate
|
|
|
135
135
|
`declaredContinuationPaths`. Ordinary paths retain their unresolved transfer;
|
|
136
136
|
conditional routes preserve prefix/child effects with target-choice, live-table
|
|
137
137
|
and selector assumptions. Effects summaries never mark those routes complete.
|
|
138
|
-
Concrete values/field addresses reject inconsistent rows
|
|
139
|
-
path
|
|
138
|
+
Concrete values/field addresses reject inconsistent rows. Continuations run after
|
|
139
|
+
every ordinary path on their own `continuationBudget` (paths, total and per-path steps,
|
|
140
|
+
visits, string iterations), so ordinary paths are the same with or without them. Overlap,
|
|
141
|
+
boundary and continuation limits remain explicit gaps or stops. Partial-table splits are
|
|
140
142
|
partial evidence, never complete dispatch or native-reachability claims. See the
|
|
141
143
|
[table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).
|
|
142
144
|
|
|
@@ -119,8 +119,10 @@ Evidenced segmented16 `indirectJumps` declarations also expose separate
|
|
|
119
119
|
`declaredContinuationPaths`. Ordinary paths retain their unresolved transfer;
|
|
120
120
|
conditional routes preserve prefix/child effects with target-choice, live-table
|
|
121
121
|
and selector assumptions. Effects summaries never mark those routes complete.
|
|
122
|
-
Concrete values/field addresses reject inconsistent rows
|
|
123
|
-
path
|
|
122
|
+
Concrete values/field addresses reject inconsistent rows. Continuations run after
|
|
123
|
+
every ordinary path on their own `continuationBudget` (paths, total and per-path steps,
|
|
124
|
+
visits, string iterations), so ordinary paths are the same with or without them. Overlap,
|
|
125
|
+
boundary and continuation limits remain explicit gaps or stops. Partial-table splits are
|
|
124
126
|
partial evidence, never complete dispatch or native-reachability claims. See the
|
|
125
127
|
[table contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#evidenced-indirect-jump-tables).
|
|
126
128
|
|
|
@@ -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 = "4.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"
|
|
@@ -19,7 +19,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
|
|
|
19
19
|
"callees compares its edges with an ExportCallEdges.java export given as ghidraCallEdges.\n"
|
|
20
20
|
"trace, arguments, effects, returns, guards, memory and allocation check relationalControls:\n"
|
|
21
21
|
"a violated control fails the report; an undecided one is reported and never counts as held.\n"
|
|
22
|
-
"Declared table continuations are separate conditional paths
|
|
22
|
+
"Declared table continuations are separate conditional paths that spend continuationBudget\n"
|
|
23
|
+
"(paths, totalSteps, maxSteps, visitLimit, stringIterations); ordinary computed transfers remain stopped.\n"
|
|
23
24
|
"Port accesses and interrupts are hardware-boundary events; portInputs supplies port reads as assumptions.\n"
|
|
24
25
|
"callModels[].preservesMemory keeps explicit, bounded pre-call byte scopes across a modeled call; other memory stays unknown.\n"
|
|
25
26
|
"Each traced path's loops record lists restart edges and what changed between iterations (loopIterationLimit).\n"
|
|
@@ -88,6 +88,8 @@ def return_flows(report, config):
|
|
|
88
88
|
consumer_limit = integer(config.get("returnConsumerLimit", 256), 1, 10000, "return consumer limit")
|
|
89
89
|
analysis_limit = integer(config.get("returnFlowAnalysisLimit", 1000000), 1, 10000000, "return flow analysis limit")
|
|
90
90
|
steps, capped = 0, False
|
|
91
|
+
# Gaps raised while declared-table continuations ran say nothing about an ordinary path.
|
|
92
|
+
ordinary_gaps = [g for g in report["gaps"] if g.get("route") != "declaredContinuation"]
|
|
91
93
|
for path in report["paths"]:
|
|
92
94
|
events = path["events"]
|
|
93
95
|
event_values = {}
|
|
@@ -138,7 +140,7 @@ def return_flows(report, config):
|
|
|
138
140
|
path["returnFlows"] = {"results": flows, "resultsOmitted": omitted, "resultLimit": limit,
|
|
139
141
|
"consumerLimit": consumer_limit,
|
|
140
142
|
"complete": not omitted and all(not f["consumersOmitted"] and f["consumerScanComplete"] for f in flows)
|
|
141
|
-
and path["returned"] and not
|
|
143
|
+
and path["returned"] and not ordinary_gaps,
|
|
142
144
|
"interpretation": "conditional static dependency paths; encodings are declared evidence, not live occurrence; a branch never establishes initialization, accepted contents or extent"}
|
|
143
145
|
report["returnFlowAnalysis"] = {"limit": analysis_limit, "steps": steps, "capped": capped}
|
|
144
146
|
return report
|
|
@@ -279,14 +279,34 @@ def snapshot(state):
|
|
|
279
279
|
return {name: state.reg(name).report() for name in ALIASES}
|
|
280
280
|
|
|
281
281
|
|
|
282
|
+
STRING_BUDGET_STOP = "String iteration budget exhausted"
|
|
283
|
+
CONTINUATION_BUDGET_RANGES = {"paths": (0, 256), "totalSteps": (1, 100000), "maxSteps": (1, 10000),
|
|
284
|
+
"visitLimit": (1, 4096), "stringIterations": (0, 65536)}
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
def validate_continuation_budget(config):
|
|
288
|
+
"""Return the fields a config sets in continuationBudget, rejecting unknown keys and out-of-range values."""
|
|
289
|
+
budget = config.get("continuationBudget", {})
|
|
290
|
+
if not isinstance(budget, dict):
|
|
291
|
+
raise ValueError("continuationBudget must be an object")
|
|
292
|
+
unknown_keys = sorted(set(budget) - set(CONTINUATION_BUDGET_RANGES))
|
|
293
|
+
if unknown_keys:
|
|
294
|
+
raise ValueError("continuationBudget accepts only " + ", ".join(CONTINUATION_BUDGET_RANGES)
|
|
295
|
+
+ "; unknown: " + ", ".join(unknown_keys))
|
|
296
|
+
return {key: integer(value, *CONTINUATION_BUDGET_RANGES[key], "continuationBudget." + key)
|
|
297
|
+
for key, value in budget.items()}
|
|
298
|
+
|
|
299
|
+
|
|
282
300
|
def trace(image, config, continue_declared_jumps=True, track_loops=True):
|
|
283
301
|
"""Trace bounded paths, preserving declared-table continuations as separate conditional evidence.
|
|
284
302
|
|
|
285
303
|
Ordinary paths run first. A path stopped at a declared indirect jump is then
|
|
286
|
-
continued once per surviving table target
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
304
|
+
continued once per surviving table target. Continuations spend their own
|
|
305
|
+
continuationBudget, so ordinary paths are the same with or without them, and
|
|
306
|
+
what the ordinary paths spend never leaves the continuations without budget.
|
|
307
|
+
Callers that read only ordinary paths pass continue_declared_jumps=False.
|
|
308
|
+
Callers that never report the paths pass track_loops=False, and their paths
|
|
309
|
+
carry no ``loops`` record.
|
|
290
310
|
"""
|
|
291
311
|
entry = integer(config.get("entry"), 0, len(image.data) - 1, "entry")
|
|
292
312
|
if not any(entry in r["entries"] for r in image.regions):
|
|
@@ -322,6 +342,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
|
|
|
322
342
|
for r, n in case.get("registers", {}).items():
|
|
323
343
|
if r not in ALIASES or type(n) is not int or not 0 <= n < 1 << ALIASES[r][2]:
|
|
324
344
|
raise ValueError("Invalid model register")
|
|
345
|
+
explicit_continuation_budget = validate_continuation_budget(config)
|
|
325
346
|
root = State(entry, image, config)
|
|
326
347
|
# Each path carries its own loop record; forks copy it with the rest of the state.
|
|
327
348
|
root.loops = (LoopTracker(integer(config.get("loopIterationLimit", 64), 1, 1024, "loopIterationLimit"))
|
|
@@ -340,6 +361,13 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
|
|
|
340
361
|
checkpoints = set(config.get("checkpoints", []))
|
|
341
362
|
# How often one path may pass the same instruction; a loop with a known bound needs it raised.
|
|
342
363
|
visit_limit = integer(config.get("visitLimit", 4), 1, 4096, "visitLimit")
|
|
364
|
+
# An unset field takes the value of the matching ordinary input.
|
|
365
|
+
continuation_budget = {"paths": max_paths, "totalSteps": total_limit, "maxSteps": max_steps,
|
|
366
|
+
"visitLimit": visit_limit, "stringIterations": string_limit, **explicit_continuation_budget}
|
|
367
|
+
ordinary_max_paths = max_paths
|
|
368
|
+
# Set once every ordinary path has finished. From then on every traced state is a continuation.
|
|
369
|
+
continuing = False
|
|
370
|
+
first_continuation_gap = None
|
|
343
371
|
|
|
344
372
|
def charge(n):
|
|
345
373
|
nonlocal total_string_steps
|
|
@@ -357,6 +385,9 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
|
|
|
357
385
|
string_effect(s, ins, count, remaining)
|
|
358
386
|
|
|
359
387
|
def finish(s, reason=None, returned=False):
|
|
388
|
+
if continuing and reason and reason.startswith(STRING_BUDGET_STOP):
|
|
389
|
+
# machine.py names no budget; a continuation's string iterations come from continuationBudget.
|
|
390
|
+
reason = "Continuation s" + reason[1:]
|
|
360
391
|
path = {"returned": returned, "stop": reason, "stopSite": None if returned else s.at, "steps": s.steps,
|
|
361
392
|
"instructionPath": s.path, "guards": s.guards, "events": s.events,
|
|
362
393
|
"registers": snapshot(s), "conditionalModels": s.conditional}
|
|
@@ -376,21 +407,6 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
|
|
|
376
407
|
nonlocal created, boundary_budget
|
|
377
408
|
declaration = image.indirect_jumps[s.at]
|
|
378
409
|
ins = image.decode(s.at)
|
|
379
|
-
root_entry = s.frames[-1]["entry"]
|
|
380
|
-
if root_entry not in boundary_cache:
|
|
381
|
-
if boundary_budget < 1:
|
|
382
|
-
global_gaps.append({"site": s.at, "reason": "conditional table boundary instruction limit"})
|
|
383
|
-
return
|
|
384
|
-
seen, walk_gaps, _, _, contested = walk(image, [root_entry], boundary_budget)
|
|
385
|
-
# walk drops rejected overlapping starts and contested instructions from seen,
|
|
386
|
-
# but it decoded them, so they are charged with the established ones.
|
|
387
|
-
overlapping = sum(g["reason"] == OVERLAP_REASON for g in walk_gaps)
|
|
388
|
-
boundary_budget -= max(1, len(seen) + len(contested) + overlapping)
|
|
389
|
-
# A truncated walk never saw the instructions that could contest a target start.
|
|
390
|
-
if any(g["reason"] == "instruction limit" for g in walk_gaps):
|
|
391
|
-
seen = {}
|
|
392
|
-
boundary_cache[root_entry] = seen
|
|
393
|
-
seen = boundary_cache[root_entry]
|
|
394
410
|
try:
|
|
395
411
|
value = s.get(ins, ins.operands[0], image)
|
|
396
412
|
address = s.address(ins, ins.operands[0]) if ins.operands[0].type == X86_OP_MEM else None
|
|
@@ -416,6 +432,28 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
|
|
|
416
432
|
if previous is not None and row["rawOffset"] not in previous:
|
|
417
433
|
continue
|
|
418
434
|
groups.setdefault(row["target"], []).append(row)
|
|
435
|
+
if not groups:
|
|
436
|
+
# No table row agrees with the operand, so no route exists to drop or to walk to.
|
|
437
|
+
return
|
|
438
|
+
if created >= max_paths:
|
|
439
|
+
# Spent or zero path budget: the routes are not followed, so no boundary walk is needed.
|
|
440
|
+
global_gaps.append({"site": s.at, "reason": "path limit"})
|
|
441
|
+
return
|
|
442
|
+
root_entry = s.frames[-1]["entry"]
|
|
443
|
+
if root_entry not in boundary_cache:
|
|
444
|
+
if boundary_budget < 1:
|
|
445
|
+
global_gaps.append({"site": s.at, "reason": "conditional table boundary instruction limit"})
|
|
446
|
+
return
|
|
447
|
+
seen, walk_gaps, _, _, contested = walk(image, [root_entry], boundary_budget)
|
|
448
|
+
# walk drops rejected overlapping starts and contested instructions from seen,
|
|
449
|
+
# but it decoded them, so they are charged with the established ones.
|
|
450
|
+
overlapping = sum(g["reason"] == OVERLAP_REASON for g in walk_gaps)
|
|
451
|
+
boundary_budget -= max(1, len(seen) + len(contested) + overlapping)
|
|
452
|
+
# A truncated walk never saw the instructions that could contest a target start.
|
|
453
|
+
if any(g["reason"] == "instruction limit" for g in walk_gaps):
|
|
454
|
+
seen = {}
|
|
455
|
+
boundary_cache[root_entry] = seen
|
|
456
|
+
seen = boundary_cache[root_entry]
|
|
419
457
|
for target, rows in groups.items():
|
|
420
458
|
if target not in seen:
|
|
421
459
|
global_gaps.append({"site": s.at, "target": target,
|
|
@@ -435,26 +473,41 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
|
|
|
435
473
|
{"segment": address[0].report(), "offset": address[1].report(), "segmentRegister": address[2]},
|
|
436
474
|
"meaning": "conditional target choice from source table; selector, live table contents and reachability unverified"}
|
|
437
475
|
child.declared_jump_assumptions = [*getattr(child, "declared_jump_assumptions", []), assumption]
|
|
476
|
+
if not hasattr(child, "continuation_steps"):
|
|
477
|
+
# Per-path continuation limits count from the first declared jump the path continues past.
|
|
478
|
+
child.continuation_steps, child.continuation_visits = 0, {}
|
|
438
479
|
child.event("declared-jump-continuation", **{k: v for k, v in assumption.items() if k != "site"})
|
|
439
480
|
child.at = target
|
|
440
481
|
pending.append(child)
|
|
441
482
|
created += 1
|
|
442
483
|
|
|
443
484
|
# Ordinary paths all finish before the first declared continuation runs; their gaps come first.
|
|
444
|
-
ordinary_gaps = None
|
|
445
485
|
while pending or deferred:
|
|
446
486
|
if not pending:
|
|
447
|
-
if
|
|
448
|
-
|
|
487
|
+
if not continuing:
|
|
488
|
+
# Ordinary tracing is over. Its counters are final, and continuations start on their own budget.
|
|
489
|
+
continuing = True
|
|
490
|
+
ordinary_steps, ordinary_string_steps = total_steps, total_string_steps
|
|
491
|
+
created = total_steps = total_string_steps = 0
|
|
492
|
+
max_paths = continuation_budget["paths"]
|
|
493
|
+
total_limit = continuation_budget["totalSteps"]
|
|
494
|
+
string_limit = continuation_budget["stringIterations"]
|
|
495
|
+
first_continuation_gap = len(global_gaps)
|
|
449
496
|
declared_continuations(deferred.pop(0))
|
|
450
497
|
continue
|
|
451
498
|
state = pending.pop()
|
|
452
499
|
try:
|
|
453
500
|
while True:
|
|
454
|
-
if
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
501
|
+
if continuing:
|
|
502
|
+
if state.continuation_steps >= continuation_budget["maxSteps"]:
|
|
503
|
+
raise StopPath("continuation step limit; loop progress unresolved")
|
|
504
|
+
if total_steps >= total_limit:
|
|
505
|
+
raise StopPath("continuation instruction budget exhausted")
|
|
506
|
+
else:
|
|
507
|
+
if state.steps >= max_steps:
|
|
508
|
+
raise StopPath("step limit; loop progress unresolved")
|
|
509
|
+
if total_steps >= total_limit:
|
|
510
|
+
raise StopPath("total instruction budget exhausted")
|
|
458
511
|
total_steps += 1
|
|
459
512
|
at = state.at
|
|
460
513
|
ins = image.decode(at)
|
|
@@ -465,7 +518,13 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
|
|
|
465
518
|
if state.loops is not None:
|
|
466
519
|
state.loops.arrive(state, at, ins)
|
|
467
520
|
state.visits[at] = state.visits.get(at, 0) + 1
|
|
468
|
-
if
|
|
521
|
+
if continuing:
|
|
522
|
+
state.continuation_steps += 1
|
|
523
|
+
state.continuation_visits[at] = state.continuation_visits.get(at, 0) + 1
|
|
524
|
+
if state.continuation_visits[at] > continuation_budget["visitLimit"]:
|
|
525
|
+
raise StopPath(f"instruction repeated more than {continuation_budget['visitLimit']} times after "
|
|
526
|
+
"the declared jump; raise continuationBudget.visitLimit or read the loop's bound")
|
|
527
|
+
elif state.visits[at] > visit_limit:
|
|
469
528
|
raise StopPath(f"instruction repeated more than {visit_limit} times; raise visitLimit or read the loop's bound")
|
|
470
529
|
if at in checkpoints:
|
|
471
530
|
state.event("checkpoint", registers=snapshot(state))
|
|
@@ -713,8 +772,19 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True):
|
|
|
713
772
|
state.at = following
|
|
714
773
|
except StopPath as error:
|
|
715
774
|
finish(state, str(error))
|
|
775
|
+
if continuing:
|
|
776
|
+
# Only continuation states are traced after the switch: deferred states are popped only when
|
|
777
|
+
# pending is empty, and every state pending holds from then on descends from a continuation.
|
|
778
|
+
continuation_steps, continuation_string_steps = total_steps, total_string_steps
|
|
779
|
+
for gap in global_gaps[first_continuation_gap:]:
|
|
780
|
+
gap["route"] = "declaredContinuation"
|
|
781
|
+
else:
|
|
782
|
+
ordinary_steps, ordinary_string_steps = total_steps, total_string_steps
|
|
783
|
+
continuation_steps = continuation_string_steps = 0
|
|
716
784
|
return {"paths": outputs, "declaredContinuationPaths": conditional_outputs, "gaps": global_gaps,
|
|
717
|
-
"hardwareBoundaries": hardware_placement(outputs, conditional_outputs, global_gaps[:
|
|
718
|
-
"completeWithinModel": not global_gaps and bool(outputs) and all(p["returned"] for p in outputs),
|
|
719
|
-
"nativeReachability": "unconfirmed", "stepsUsed":
|
|
720
|
-
"
|
|
785
|
+
"hardwareBoundaries": hardware_placement(outputs, conditional_outputs, global_gaps[:first_continuation_gap]),
|
|
786
|
+
"completeWithinModel": not global_gaps[:first_continuation_gap] and bool(outputs) and all(p["returned"] for p in outputs),
|
|
787
|
+
"nativeReachability": "unconfirmed", "stepsUsed": ordinary_steps, "stringIterationsUsed": ordinary_string_steps,
|
|
788
|
+
"continuationStepsUsed": continuation_steps, "continuationStringIterationsUsed": continuation_string_steps,
|
|
789
|
+
"limits": {"steps": max_steps, "paths": ordinary_max_paths, "depth": max_depth,
|
|
790
|
+
"continuation": continuation_budget}}
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
"""Declared-table continuations spend their own budget and never change the ordinary paths."""
|
|
2
|
+
import json
|
|
3
|
+
import unittest
|
|
4
|
+
import test_dispatch # noqa: F401 (puts the engine sources on sys.path)
|
|
5
|
+
from scientific_method_engine.x86.image import Image
|
|
6
|
+
from scientific_method_engine.x86.reports import run_report
|
|
7
|
+
from scientific_method_engine.x86.trace import trace
|
|
8
|
+
|
|
9
|
+
RETURN_ONE = bytes.fromhex("b8 01 00 c3")
|
|
10
|
+
SPIN = bytes.fromhex("eb fe")
|
|
11
|
+
COPY_TWO = bytes.fromhex("b9 02 00 fc f3 a4 c3")
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def fan_out(stages, targets=(RETURN_ONE, bytes.fromhex("b8 02 00 c3"))):
|
|
15
|
+
"""Build a function whose first branch reaches a declared table jump and whose other
|
|
16
|
+
branch forks on `stages` independent unknown bytes, so ordinary routes number 2**stages."""
|
|
17
|
+
code = bytearray(bytes.fromhex("72 00"))
|
|
18
|
+
for i in range(stages):
|
|
19
|
+
address = 0x100 + i
|
|
20
|
+
code += bytes([0x80, 0x3E, address & 0xFF, address >> 8, 0x00, 0x74, 0x00])
|
|
21
|
+
code += b"\xc3"
|
|
22
|
+
dispatcher = len(code)
|
|
23
|
+
code[1] = dispatcher - 2
|
|
24
|
+
code += bytes.fromhex("ff e3")
|
|
25
|
+
starts = []
|
|
26
|
+
for target in targets:
|
|
27
|
+
starts.append(len(code))
|
|
28
|
+
code += target
|
|
29
|
+
end = len(code)
|
|
30
|
+
table = len(code)
|
|
31
|
+
for start in starts:
|
|
32
|
+
code += start.to_bytes(2, "little")
|
|
33
|
+
config = {"entry": 0, "registers": {"ds": 0x2000, "es": 0x3000, "si": 0x10, "di": 0x20},
|
|
34
|
+
"regions": [{"name": "code", "start": 0, "end": end, "segment": 4096, "ip": 0,
|
|
35
|
+
"entries": [0], "evidence": "constructed mappings"}],
|
|
36
|
+
"indirectJumps": [{"site": dispatcher, "evidence": "constructed BX consumer", "exhaustive": True,
|
|
37
|
+
"table": {"start": table, "count": len(targets), "stride": 2,
|
|
38
|
+
"evidence": "constructed words"}}]}
|
|
39
|
+
return bytes(code), config, dispatcher
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def ordinary(report):
|
|
43
|
+
"""Everything a report says about ordinary paths, including derived analyses such as returnFlows."""
|
|
44
|
+
return json.dumps({"paths": report["paths"], "stepsUsed": report["stepsUsed"],
|
|
45
|
+
"stringIterationsUsed": report["stringIterationsUsed"],
|
|
46
|
+
"completeWithinModel": report["completeWithinModel"],
|
|
47
|
+
"effectPaths": report.get("effectOrdering", {}).get("paths"),
|
|
48
|
+
"allPathsRead": report.get("effectOrdering", {}).get("allPathsRead"),
|
|
49
|
+
"gaps": [g for g in report["gaps"] if "route" not in g]}, sort_keys=True)
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class ContinuationBudgetTests(unittest.TestCase):
|
|
53
|
+
def test_continuations_run_after_ordinary_paths_spend_the_shared_budget(self):
|
|
54
|
+
data, config, dispatcher = fan_out(4)
|
|
55
|
+
r = run_report(data, {**config, "maxPaths": 8}, "effects")
|
|
56
|
+
self.assertEqual(len(r["paths"]), 8)
|
|
57
|
+
self.assertTrue(any(g["reason"] == "path limit" and "route" not in g for g in r["gaps"]))
|
|
58
|
+
routes = r["declaredContinuationPaths"]
|
|
59
|
+
self.assertEqual(sorted(p["registers"]["ax"]["value"] for p in routes), [1, 2])
|
|
60
|
+
self.assertTrue(all(p["returned"] and p["declaredJumpAssumptions"][0]["site"] == dispatcher for p in routes))
|
|
61
|
+
self.assertEqual(r["limits"]["paths"], 8)
|
|
62
|
+
self.assertEqual(r["limits"]["continuation"],
|
|
63
|
+
{"paths": 8, "totalSteps": 20000, "maxSteps": 512, "visitLimit": 4, "stringIterations": 4096})
|
|
64
|
+
self.assertEqual(r["continuationStepsUsed"], 4)
|
|
65
|
+
self.assertFalse(r["completeWithinModel"])
|
|
66
|
+
self.assertTrue(all(not p["effectCompleteWithinModel"] for p in r["effectOrdering"]["declaredContinuationPaths"]))
|
|
67
|
+
|
|
68
|
+
def test_ordinary_paths_are_identical_whatever_the_continuations_spend(self):
|
|
69
|
+
# Two stages leave every ordinary path returned except the one stopped at the jump.
|
|
70
|
+
for stages, max_paths in ((4, 8), (2, 64)):
|
|
71
|
+
data, config, _ = fan_out(stages)
|
|
72
|
+
config = {**config, "maxPaths": max_paths}
|
|
73
|
+
image = Image(data, config)
|
|
74
|
+
unread = trace(image, image.config, continue_declared_jumps=False)
|
|
75
|
+
for command in ("trace", "returns", "effects"):
|
|
76
|
+
baseline = run_report(data, {**config, "continuationBudget": {"paths": 0}}, command)
|
|
77
|
+
if command == "trace":
|
|
78
|
+
self.assertEqual(json.dumps(unread["paths"], sort_keys=True), json.dumps(baseline["paths"], sort_keys=True))
|
|
79
|
+
for budget in ({}, {"paths": 1}, {"paths": 256, "totalSteps": 100000, "maxSteps": 10000,
|
|
80
|
+
"visitLimit": 4096, "stringIterations": 65536},
|
|
81
|
+
{"totalSteps": 1}, {"maxSteps": 1}):
|
|
82
|
+
r = run_report(data, {**config, "continuationBudget": budget}, command)
|
|
83
|
+
self.assertEqual(ordinary(r), ordinary(baseline), (stages, command, budget))
|
|
84
|
+
|
|
85
|
+
def test_raising_the_continuation_budget_leaves_the_ordinary_report_size_alone(self):
|
|
86
|
+
data, config, _ = fan_out(6)
|
|
87
|
+
small = run_report(data, {**config, "maxPaths": 4}, "trace")
|
|
88
|
+
large = run_report(data, {**config, "maxPaths": 4, "continuationBudget": {"paths": 256}}, "trace")
|
|
89
|
+
self.assertEqual(len(large["paths"]), 4)
|
|
90
|
+
self.assertEqual(ordinary(large), ordinary(small))
|
|
91
|
+
self.assertEqual(len(large["declaredContinuationPaths"]), 2)
|
|
92
|
+
|
|
93
|
+
def test_path_limit_is_a_continuation_gap(self):
|
|
94
|
+
data, config, dispatcher = fan_out(2)
|
|
95
|
+
r = run_report(data, {**config, "continuationBudget": {"paths": 0}}, "trace")
|
|
96
|
+
self.assertFalse(r["declaredContinuationPaths"])
|
|
97
|
+
self.assertIn({"site": dispatcher, "reason": "path limit", "route": "declaredContinuation"}, r["gaps"])
|
|
98
|
+
self.assertFalse(r["completeWithinModel"])
|
|
99
|
+
r = run_report(data, {**config, "continuationBudget": {"paths": 1}}, "trace")
|
|
100
|
+
self.assertEqual(len(r["declaredContinuationPaths"]), 1)
|
|
101
|
+
self.assertIn({"site": dispatcher, "reason": "path limit", "route": "declaredContinuation"}, r["gaps"])
|
|
102
|
+
|
|
103
|
+
def test_a_spent_path_budget_leaves_one_gap_per_stopped_path(self):
|
|
104
|
+
# No boundary walk runs, so a boundary budget too small for one still leaves only the path-limit gap.
|
|
105
|
+
data, config, dispatcher = fan_out(1)
|
|
106
|
+
r = run_report(data, {**config, "instructionLimit": 1, "continuationBudget": {"paths": 0}}, "trace")
|
|
107
|
+
self.assertEqual([g for g in r["gaps"] if g.get("route")],
|
|
108
|
+
[{"site": dispatcher, "reason": "path limit", "route": "declaredContinuation"}])
|
|
109
|
+
|
|
110
|
+
def test_a_spent_path_budget_leaves_no_gap_where_no_row_matches(self):
|
|
111
|
+
# A concrete operand outside the table has no route to drop, whatever the path budget.
|
|
112
|
+
data, config, _ = fan_out(1)
|
|
113
|
+
config = {**config, "registers": {**config["registers"], "bx": 0x7777}}
|
|
114
|
+
for budget in ({}, {"paths": 0}):
|
|
115
|
+
r = run_report(data, {**config, "continuationBudget": budget}, "trace")
|
|
116
|
+
self.assertFalse(r["declaredContinuationPaths"])
|
|
117
|
+
self.assertFalse([g for g in r["gaps"] if g.get("route")], budget)
|
|
118
|
+
|
|
119
|
+
def test_forks_inside_a_continuation_spend_its_paths(self):
|
|
120
|
+
fork = bytes.fromhex("80 3e 00 02 00 74 00 c3")
|
|
121
|
+
data, config, _ = fan_out(2, targets=(fork,))
|
|
122
|
+
r = run_report(data, {**config, "continuationBudget": {"paths": 1}}, "trace")
|
|
123
|
+
self.assertEqual(len(r["declaredContinuationPaths"]), 1)
|
|
124
|
+
gaps = [g for g in r["gaps"] if g.get("route") == "declaredContinuation"]
|
|
125
|
+
self.assertEqual([g["reason"] for g in gaps], ["path limit"])
|
|
126
|
+
r = run_report(data, {**config, "continuationBudget": {"paths": 2}}, "trace")
|
|
127
|
+
self.assertEqual(len(r["declaredContinuationPaths"]), 2)
|
|
128
|
+
self.assertFalse(any(g.get("route") for g in r["gaps"]))
|
|
129
|
+
|
|
130
|
+
def test_total_and_per_path_step_limits_stop_continuations(self):
|
|
131
|
+
data, config, _ = fan_out(2)
|
|
132
|
+
r = run_report(data, {**config, "continuationBudget": {"totalSteps": 1}}, "trace")
|
|
133
|
+
# Each route needs two instructions, so the one budgeted step stops both.
|
|
134
|
+
self.assertEqual([p["stop"] for p in r["declaredContinuationPaths"]],
|
|
135
|
+
["continuation instruction budget exhausted"] * 2)
|
|
136
|
+
self.assertEqual(r["continuationStepsUsed"], 1)
|
|
137
|
+
r = run_report(data, {**config, "continuationBudget": {"maxSteps": 1}}, "trace")
|
|
138
|
+
self.assertTrue(all(p["stop"] == "continuation step limit; loop progress unresolved"
|
|
139
|
+
for p in r["declaredContinuationPaths"]))
|
|
140
|
+
self.assertFalse(any(p["returned"] for p in r["declaredContinuationPaths"]))
|
|
141
|
+
self.assertFalse(r["completeWithinModel"])
|
|
142
|
+
|
|
143
|
+
def test_continuation_steps_count_from_the_declared_jump(self):
|
|
144
|
+
# The ordinary prefix (jc, jmp bx) takes two steps; maxSteps 2 would leave a whole-path count no room.
|
|
145
|
+
data, config, _ = fan_out(2)
|
|
146
|
+
r = run_report(data, {**config, "maxSteps": 2}, "trace")
|
|
147
|
+
self.assertTrue(all(p["returned"] for p in r["declaredContinuationPaths"]))
|
|
148
|
+
self.assertTrue(all(p["steps"] == 4 for p in r["declaredContinuationPaths"]))
|
|
149
|
+
|
|
150
|
+
def test_visit_limit_counts_repeats_after_the_declared_jump(self):
|
|
151
|
+
data, config, _ = fan_out(2, targets=(SPIN,))
|
|
152
|
+
r = run_report(data, {**config, "visitLimit": 2, "continuationBudget": {"visitLimit": 3}}, "trace")
|
|
153
|
+
(route,) = r["declaredContinuationPaths"]
|
|
154
|
+
self.assertEqual(route["stop"], "instruction repeated more than 3 times after the declared jump; "
|
|
155
|
+
"raise continuationBudget.visitLimit or read the loop's bound")
|
|
156
|
+
self.assertEqual(route["instructionPath"].count(route["stopSite"]), 4)
|
|
157
|
+
self.assertFalse(r["completeWithinModel"])
|
|
158
|
+
|
|
159
|
+
def test_string_iteration_limit_stops_a_continuation(self):
|
|
160
|
+
data, config, _ = fan_out(2, targets=(COPY_TWO,))
|
|
161
|
+
r = run_report(data, config, "trace")
|
|
162
|
+
self.assertTrue(r["declaredContinuationPaths"][0]["returned"])
|
|
163
|
+
self.assertEqual(r["continuationStringIterationsUsed"], 2)
|
|
164
|
+
self.assertEqual(r["stringIterationsUsed"], 0)
|
|
165
|
+
r = run_report(data, {**config, "stringIterations": 0, "continuationBudget": {"stringIterations": 1}}, "trace")
|
|
166
|
+
(route,) = r["declaredContinuationPaths"]
|
|
167
|
+
self.assertFalse(route["returned"])
|
|
168
|
+
self.assertEqual(route["stop"], "Continuation string iteration budget exhausted; remaining effects unresolved")
|
|
169
|
+
|
|
170
|
+
def test_invalid_budgets_are_rejected(self):
|
|
171
|
+
data, config, _ = fan_out(1)
|
|
172
|
+
for budget in ([], {"path": 1}, {"paths": 257}, {"paths": -1}, {"totalSteps": 0}, {"maxSteps": 10001},
|
|
173
|
+
{"visitLimit": 0}, {"stringIterations": 65537}, {"paths": True}, {"paths": 1.5}):
|
|
174
|
+
with self.assertRaises(ValueError, msg=budget):
|
|
175
|
+
run_report(data, {**config, "continuationBudget": budget}, "trace")
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
if __name__ == "__main__":
|
|
179
|
+
unittest.main()
|
{scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_table_continuations.py
RENAMED
|
@@ -47,7 +47,7 @@ class TableContinuationTests(unittest.TestCase):
|
|
|
47
47
|
|
|
48
48
|
def test_limits_do_not_leave_a_positive_continuation_contract(self):
|
|
49
49
|
data, config = fixture()
|
|
50
|
-
for change in ({"
|
|
50
|
+
for change in ({"continuationBudget": {"paths": 0}}, {"instructionLimit": 1}):
|
|
51
51
|
r = run_report(data, {**config, **change}, "trace")
|
|
52
52
|
self.assertFalse(any(p["returned"] for p in r["declaredContinuationPaths"]))
|
|
53
53
|
self.assertFalse(r["completeWithinModel"])
|
|
@@ -125,7 +125,9 @@ class TableContinuationTests(unittest.TestCase):
|
|
|
125
125
|
self.assertEqual([(p["returned"], p["stop"]) for p in declared["paths"]],
|
|
126
126
|
[(p["returned"], p["stop"]) for p in plain["paths"]])
|
|
127
127
|
self.assertEqual(len(declared["paths"]), 3)
|
|
128
|
-
|
|
128
|
+
# The ordinary paths spent all three paths, and the continuations still start on their own budget.
|
|
129
|
+
self.assertEqual(len(declared["declaredContinuationPaths"]), 3)
|
|
130
|
+
self.assertTrue(all(p["returned"] for p in declared["declaredContinuationPaths"]))
|
|
129
131
|
|
|
130
132
|
def test_operand_read_stays_out_of_the_stopped_ordinary_path(self):
|
|
131
133
|
data, config = fixture()
|
|
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-3.2.0 → scientific_method_engine-4.0.0}/tests/test_effect_order.py
RENAMED
|
File without changes
|
|
File without changes
|
{scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_memory_scopes.py
RENAMED
|
File without changes
|
{scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_nested_frame_request.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
{scientific_method_engine-3.2.0 → scientific_method_engine-4.0.0}/tests/test_relational_controls.py
RENAMED
|
File without changes
|
|
File without changes
|