scientific-method-engine 3.0.0__tar.gz → 3.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-3.0.0 → scientific_method_engine-3.1.0}/PKG-INFO +9 -1
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/README.md +8 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/pyproject.toml +1 -1
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/cli.py +2 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/machine.py +53 -1
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/memory_scopes.py +11 -2
- scientific_method_engine-3.1.0/src/scientific_method_engine/x86/relational.py +745 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/reports.py +18 -2
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/trace.py +3 -2
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_memory_scopes.py +5 -3
- scientific_method_engine-3.1.0/tests/test_relational_controls.py +561 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/.gitignore +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/LICENSE +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/__init__.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/__main__.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/image.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/pcode.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/src/scientific_method_engine/x86/values.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/oracle.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_dispatch.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_effect_order.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_nested_frame_request.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_oracle.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_pe.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.0}/tests/test_table_continuations.py +0 -0
- {scientific_method_engine-3.0.0 → scientific_method_engine-3.1.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.
|
|
3
|
+
Version: 3.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
|
|
@@ -142,3 +142,11 @@ survive the model's memory invalidation, and each scope is reported with the mod
|
|
|
142
142
|
return and the effect summary. Everything else the service may do stays unknown. This input needs
|
|
143
143
|
prepared protocol 3, so upgrade the reader and the engine together. See the
|
|
144
144
|
[call model contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#limits-and-assumptions).
|
|
145
|
+
|
|
146
|
+
The trace-family commands (`trace`, `arguments`, `effects`, `returns`, `guards`, `memory`,
|
|
147
|
+
`allocation`) check `relationalControls`: assertions over reported values (reach, order, last
|
|
148
|
+
writer, containment, value relation and value origin) evaluated on every bounded path. A violated
|
|
149
|
+
control fails the report. A control left undecided by a stop, a limit or an unread call is
|
|
150
|
+
reported as `undecided` and never counts as held. Access reports also give each byte's
|
|
151
|
+
`writeOrder`, or why it has no modeled value. See the
|
|
152
|
+
[controls contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#relational-controls).
|
|
@@ -126,3 +126,11 @@ survive the model's memory invalidation, and each scope is reported with the mod
|
|
|
126
126
|
return and the effect summary. Everything else the service may do stays unknown. This input needs
|
|
127
127
|
prepared protocol 3, so upgrade the reader and the engine together. See the
|
|
128
128
|
[call model contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#limits-and-assumptions).
|
|
129
|
+
|
|
130
|
+
The trace-family commands (`trace`, `arguments`, `effects`, `returns`, `guards`, `memory`,
|
|
131
|
+
`allocation`) check `relationalControls`: assertions over reported values (reach, order, last
|
|
132
|
+
writer, containment, value relation and value origin) evaluated on every bounded path. A violated
|
|
133
|
+
control fails the report. A control left undecided by a stop, a limit or an unread call is
|
|
134
|
+
reported as `undecided` and never counts as held. Access reports also give each byte's
|
|
135
|
+
`writeOrder`, or why it has no modeled value. See the
|
|
136
|
+
[controls contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#relational-controls).
|
|
@@ -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 = "3.
|
|
8
|
+
version = "3.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"
|
|
@@ -17,6 +17,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
|
|
|
17
17
|
"effects|returns|memory|incoming|call-order|guards|allocation|dispatch> <config.json|->\n"
|
|
18
18
|
"effects includes ordered path writes/calls and local restoration witnesses; transactionality remains unestablished.\n"
|
|
19
19
|
"callees compares its edges with an ExportCallEdges.java export given as ghidraCallEdges.\n"
|
|
20
|
+
"trace, arguments, effects, returns, guards, memory and allocation check relationalControls:\n"
|
|
21
|
+
"a violated control fails the report; an undecided one is reported and never counts as held.\n"
|
|
20
22
|
"Declared table continuations are separate conditional paths; ordinary computed transfers remain stopped.\n"
|
|
21
23
|
"Port accesses and interrupts are hardware-boundary events; portInputs supplies port reads as assumptions.\n"
|
|
22
24
|
"callModels[].preservesMemory keeps explicit, bounded pre-call byte scopes across a modeled call; other memory stays unknown.\n"
|
|
@@ -67,6 +67,17 @@ class State:
|
|
|
67
67
|
# Keys grouped by (segment, base) so a write scans only groups that can alias it.
|
|
68
68
|
self.memory_groups = {}
|
|
69
69
|
self.memory_epoch = 0
|
|
70
|
+
# The order of the write event that stored each modeled byte. lost_memory holds the
|
|
71
|
+
# byteProducers "unwritten" row of bytes with no value that an ordinary write explains (a
|
|
72
|
+
# possibly aliasing write dropped them) or that a preservesMemory scope kept without a
|
|
73
|
+
# value. memory_cleared is the order of the event that dropped every byte (a modeled call),
|
|
74
|
+
# or None. writes maps each alias group to {domain: order of the last write with it} since
|
|
75
|
+
# that event, so a read of a byte this path never stored can name a write that may have
|
|
76
|
+
# stored it without scanning the writes of its own group.
|
|
77
|
+
self.memory_writers = {}
|
|
78
|
+
self.lost_memory = {}
|
|
79
|
+
self.memory_cleared = None
|
|
80
|
+
self.writes = {}
|
|
70
81
|
# Bytes a preservesMemory scope kept without a value (ADR 0009): key -> the unknown term
|
|
71
82
|
# name they had before the modeled call. They stay unread: no value, no producer.
|
|
72
83
|
self.unread_memory = {}
|
|
@@ -161,6 +172,11 @@ class State:
|
|
|
161
172
|
self.memory.clear()
|
|
162
173
|
self.memory_groups.clear()
|
|
163
174
|
self.unread_memory.clear()
|
|
175
|
+
self.memory_writers.clear()
|
|
176
|
+
self.lost_memory.clear()
|
|
177
|
+
self.writes.clear()
|
|
178
|
+
# The caller records the event that explains the loss right after clearing.
|
|
179
|
+
self.memory_cleared = len(self.events)
|
|
164
180
|
self.memory_epoch += 1
|
|
165
181
|
|
|
166
182
|
def unread_term(self, key):
|
|
@@ -171,6 +187,37 @@ class State:
|
|
|
171
187
|
"""The modeled value of one memory byte, or an unknown term produced by the current site."""
|
|
172
188
|
return self.memory[key] if key in self.memory else unknown(self.unread_term(key), 8, self.at)
|
|
173
189
|
|
|
190
|
+
def unwritten(self, key):
|
|
191
|
+
"""Why a byte has no modeled value: the cause and the order of the event behind it."""
|
|
192
|
+
# Writes to the key's own (segment, base) group store other offsets; any other write may alias.
|
|
193
|
+
# A later aliasing write is newer than the one that dropped the byte, so it is the one named.
|
|
194
|
+
lost = self.lost_memory.get(key)
|
|
195
|
+
group, a = key[:2], key_domain(key, self.bits, self.flat)
|
|
196
|
+
latest = None
|
|
197
|
+
for other, domains in self.writes.items():
|
|
198
|
+
if other == group:
|
|
199
|
+
continue
|
|
200
|
+
if a is None:
|
|
201
|
+
# Every write may alias a byte with no concrete domain; the group's newest decides.
|
|
202
|
+
order = max(domains.values())
|
|
203
|
+
else:
|
|
204
|
+
order = max((o for b, o in domains.items() if b is None or not (a[1] <= b[0] or b[1] <= a[0])), default=None)
|
|
205
|
+
if order is not None and (latest is None or order > latest):
|
|
206
|
+
latest = order
|
|
207
|
+
if latest is not None and (lost is None or lost["order"] is None or latest > lost["order"]):
|
|
208
|
+
return {"cause": "possibly written by an aliasing write", "order": latest}
|
|
209
|
+
if lost is not None:
|
|
210
|
+
return dict(lost)
|
|
211
|
+
if self.memory_cleared is not None:
|
|
212
|
+
return {"cause": "dropped by a modeled call", "order": self.memory_cleared}
|
|
213
|
+
return {"cause": "no write on this path", "order": None}
|
|
214
|
+
|
|
215
|
+
def byte_writer(self, index, key):
|
|
216
|
+
"""The byteProducers row of one accessed byte: its producers and the write that stored it."""
|
|
217
|
+
if key in self.memory:
|
|
218
|
+
return {"index": index, "producers": producers(self.memory[key]), "writeOrder": self.memory_writers.get(key)}
|
|
219
|
+
return {"index": index, "producers": [], "writeOrder": None, "unwritten": self.unwritten(key)}
|
|
220
|
+
|
|
174
221
|
def reg(self, name):
|
|
175
222
|
root, low, bits = alias(name)
|
|
176
223
|
value = extract(self.regs[root], low, bits)
|
|
@@ -225,6 +272,7 @@ class State:
|
|
|
225
272
|
self.memory_epoch += 1
|
|
226
273
|
|
|
227
274
|
written = written_domain(seg, base, delta, width, self.bits, self.flat)
|
|
275
|
+
self.writes.setdefault((seg, base), {})[written] = len(self.events)
|
|
228
276
|
for group, members in list(self.memory_groups.items()):
|
|
229
277
|
if group == (seg, base):
|
|
230
278
|
continue
|
|
@@ -233,12 +281,16 @@ class State:
|
|
|
233
281
|
uncertain.append(key)
|
|
234
282
|
self.memory.pop(key, None)
|
|
235
283
|
self.unread_memory.pop(key, None)
|
|
284
|
+
self.memory_writers.pop(key, None)
|
|
285
|
+
self.lost_memory[key] = {"cause": "dropped by a possibly aliasing write", "order": len(self.events)}
|
|
236
286
|
members.discard(key)
|
|
237
287
|
if not members:
|
|
238
288
|
del self.memory_groups[group]
|
|
239
289
|
for i, key in enumerate(keys):
|
|
240
290
|
self.memory[key] = extract(write, i * 8, 8)
|
|
241
291
|
self.unread_memory.pop(key, None)
|
|
292
|
+
self.memory_writers[key] = len(self.events)
|
|
293
|
+
self.lost_memory.pop(key, None)
|
|
242
294
|
self.memory_groups.setdefault((seg, base), set()).update(keys)
|
|
243
295
|
value = write
|
|
244
296
|
missing = []
|
|
@@ -257,7 +309,7 @@ class State:
|
|
|
257
309
|
event = self.event("write" if write is not None else "read", segment=segment.report(), offset=offset.report(),
|
|
258
310
|
width=width, effectiveSegmentRegister=addressing_register, segmentInterpretation="base" if self.flat else "selector-paragraph", interval={"segment": seg, "base": base, "start": delta, "end": delta + width},
|
|
259
311
|
value=value.report(), missingByteProducers=missing,
|
|
260
|
-
byteProducers=[
|
|
312
|
+
byteProducers=[self.byte_writer(i, key) for i, key in enumerate(keys)],
|
|
261
313
|
guards=deepcopy(relevant), role=role,
|
|
262
314
|
uncertainAliasesInvalidated=len(uncertain))
|
|
263
315
|
f = self.frames[-1]
|
|
@@ -95,12 +95,21 @@ def capture_scopes(state, model):
|
|
|
95
95
|
return values, unread, descriptions
|
|
96
96
|
|
|
97
97
|
|
|
98
|
-
def
|
|
98
|
+
def scope_history(state, values, unread):
|
|
99
|
+
"""Snapshot, before the call, the write that stored each captured byte and why each uncached one has no value."""
|
|
100
|
+
return ({key: state.memory_writers[key] for key in values if key in state.memory_writers},
|
|
101
|
+
{key: state.unwritten(key) for key in unread})
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def retain_scopes(state, values, unread, history):
|
|
99
105
|
"""Put the captured bytes back after the model invalidated memory. Later writes still apply.
|
|
100
106
|
|
|
101
|
-
All scoped keys are concrete linear bytes, so they share one alias group.
|
|
107
|
+
All scoped keys are concrete linear bytes, so they share one alias group. ``history`` from
|
|
108
|
+
``scope_history`` keeps each byte's reported writer, or its reason for having no value.
|
|
102
109
|
"""
|
|
103
110
|
state.memory.update(values)
|
|
104
111
|
state.unread_memory.update(unread)
|
|
112
|
+
state.memory_writers.update(history[0])
|
|
113
|
+
state.lost_memory.update(history[1])
|
|
105
114
|
if values or unread:
|
|
106
115
|
state.memory_groups.setdefault((("linear",), ("absolute",)), set()).update(values, unread)
|