scientific-method-engine 6.0.0__tar.gz → 6.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.
Files changed (67) hide show
  1. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/reports.py +21 -5
  4. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/tests/test_pe.py +51 -0
  5. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/.gitignore +0 -0
  6. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/LICENSE +0 -0
  7. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/README.md +0 -0
  8. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/__init__.py +0 -0
  9. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/__main__.py +0 -0
  10. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/cli.py +0 -0
  11. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  12. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  13. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  14. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  15. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  16. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  17. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  18. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  19. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  20. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  21. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  22. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  23. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  24. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  25. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  26. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  27. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  28. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  29. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  30. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  31. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  32. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  33. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  34. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  35. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  36. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  37. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  38. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  39. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  40. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  41. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  42. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  43. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  44. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  45. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  46. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/image.py +0 -0
  47. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/loops.py +0 -0
  48. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/machine.py +0 -0
  49. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  50. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  51. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  52. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
  53. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/relational.py +0 -0
  54. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  55. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/trace.py +0 -0
  56. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/src/scientific_method_engine/x86/values.py +0 -0
  57. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/tests/oracle.py +0 -0
  58. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/tests/test_continuation_budget.py +0 -0
  59. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/tests/test_dispatch.py +0 -0
  60. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/tests/test_effect_order.py +0 -0
  61. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/tests/test_loops.py +0 -0
  62. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/tests/test_memory_scopes.py +0 -0
  63. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/tests/test_nested_frame_request.py +0 -0
  64. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/tests/test_oracle.py +0 -0
  65. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/tests/test_relational_controls.py +0 -0
  66. {scientific_method_engine-6.0.0 → scientific_method_engine-6.1.0}/tests/test_table_continuations.py +0 -0
  67. {scientific_method_engine-6.0.0 → scientific_method_engine-6.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: 6.0.0
3
+ Version: 6.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
@@ -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 = "6.0.0"
8
+ version = "6.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"
@@ -31,12 +31,16 @@ def memory_width(ins, operand):
31
31
  X87_MEMORY_STORES = {"fst", "fstp", "fist", "fistp", "fisttp", "fbstp", "fnstcw", "fstcw", "fnstsw", "fstsw",
32
32
  "fnstenv", "fstenv", "fnsave", "fsave"}
33
33
  X87_MEMORY_LOADS = {"fldcw", "fldenv", "frstor"}
34
+ # Capstone gives the memory operand of INS and OUTS no access flags: INS writes ES:[(E)DI], OUTS reads [(E)SI].
35
+ PORT_MEMORY_STORES = {"insb", "insw", "insd"}
36
+ PORT_MEMORY_LOADS = {"outsb", "outsw", "outsd"}
34
37
 
35
38
 
36
39
  def memory_access(ins, operand):
37
- if ins.mnemonic in X87_MEMORY_STORES:
40
+ m = base_mnemonic(ins)
41
+ if m in X87_MEMORY_STORES or m in PORT_MEMORY_STORES:
38
42
  return ["write"]
39
- if ins.mnemonic in X87_MEMORY_LOADS:
43
+ if m in X87_MEMORY_LOADS or m in PORT_MEMORY_LOADS:
40
44
  return ["read"]
41
45
  return [name for flag, name in ((CS_AC_READ, "read"), (CS_AC_WRITE, "write")) if operand.access & flag]
42
46
 
@@ -195,6 +199,11 @@ def incoming(image, config):
195
199
  "scope": "All bytes of declared search regions; verified calls are reachable from accepted starts. Never proves universal absence."}
196
200
 
197
201
 
202
+ # Classifications of a conditionalAccesses row in ``uses``.
203
+ CFG_OPERAND = "entry-CFG operand past a stop; values and callee effects unresolved"
204
+ PORT_OPERAND = "operand past a PE32 port access; values and continuation unresolved"
205
+
206
+
198
207
  def uses(image, config):
199
208
  query = config.get("query", {})
200
209
  offset = integer(query.get("offset"), 0, image.mask, "query offset")
@@ -283,6 +292,14 @@ def uses(image, config):
283
292
  after_stop, stop_gaps, _, _, _ = (walk(image, list(stops), instruction_limit, follow_flat_ports=True)
284
293
  if stops else ({}, [], None, None, None))
285
294
  gaps.extend(g for g in stop_gaps if g["reason"] == "instruction limit")
295
+ # In PE32 a site the stops reach only by continuing past a port access is named as such, even when
296
+ # it also depends on an unread call. The walk that ends at port accesses must finish within the
297
+ # limit for that claim; otherwise every row keeps the shared value.
298
+ port_only = set()
299
+ if image.flat and any(base_mnemonic(ins) in PORTS for ins in after_stop.values()):
300
+ before_ports, port_gaps, _, _, _ = walk(image, list(stops), instruction_limit)
301
+ if not any(g["reason"] == "instruction limit" for g in port_gaps):
302
+ port_only = set(after_stop) - set(before_ports)
286
303
  # A call past a stop was never traced either, so code after it also depends on it returning.
287
304
  starts = [(root, root, reason) for root, reason in stops.items()]
288
305
  starts += [(at, at + ins.size, "call past a stop; assumed to return")
@@ -305,8 +322,7 @@ def uses(image, config):
305
322
  for operand in ins.operands:
306
323
  if operand.type != X86_OP_MEM:
307
324
  continue
308
- kinds = [kind for flag, kind in ((CS_AC_READ, "read"), (CS_AC_WRITE, "write"))
309
- if operand.access & flag and mode in ("both", kind) and (at, kind) not in reported]
325
+ kinds = [kind for kind in memory_access(ins, operand) if mode in ("both", kind) and (at, kind) not in reported]
310
326
  if not kinds:
311
327
  continue
312
328
  if state is None:
@@ -332,7 +348,7 @@ def uses(image, config):
332
348
  "effectiveSegmentRegister": segment_name,
333
349
  "address": "overlaps query" if overlaps and segment is None else "possible alias",
334
350
  "classification": ("unverified overlapping instruction path" if at in unverified else
335
- "entry-CFG operand past a stop; values and callee effects unresolved"),
351
+ PORT_OPERAND if at in port_only else CFG_OPERAND),
336
352
  "dependsOn": depends.get(at, []),
337
353
  "reachability": "conditional on encoded branch outcomes and on execution continuing past every named stop"})
338
354
  # A control proves the search reaches a known use, which an operand found past a stop still shows.
@@ -120,6 +120,7 @@ class PEReporterTests(unittest.TestCase):
120
120
  self.assertEqual(r['matches'], [])
121
121
  row, = r['conditionalAccesses']
122
122
  self.assertEqual((row['site'], row['dependsOn']), (store, [{'site': out, 'reason': gap['reason']}]))
123
+ self.assertEqual(row['classification'], 'operand past a PE32 port access; values and continuation unresolved')
123
124
  # The inventoried store is not reported a second time as a raw candidate.
124
125
  self.assertEqual(r['rawCandidates'], [])
125
126
  self.assertIn(gap, r['gaps'])
@@ -143,6 +144,56 @@ class PEReporterTests(unittest.TestCase):
143
144
  self.assertEqual([d['site'] for d in row['dependsOn']], [CODE_RAW + 4, CODE_RAW + 5])
144
145
  self.assertEqual(row['dependsOn'][1]['reason'], 'port access past a stop; assumed to continue')
145
146
 
147
+ def test_uses_classifies_an_operand_reached_only_past_a_port_access(self):
148
+ cfg = 'entry-CFG operand past a stop; values and callee effects unresolved'
149
+ port = 'operand past a PE32 port access; values and continuation unresolved'
150
+ def row(code):
151
+ r = report(code, 'uses', query={'offset': DATA_VA, 'width': 4})
152
+ found, = r['conditionalAccesses']
153
+ return found['site'] - CODE_RAW, found['classification'], [d['site'] - CODE_RAW for d in found['dependsOn']]
154
+ # call eax; mov [DATA_VA], eax; ret: past an unread call only.
155
+ self.assertEqual(row('ff d0 a3 00 20 40 00 c3'), (2, cfg, [0]))
156
+ # mov dx, 0x3c8; out dx, al; mov [DATA_VA], eax; ret: past a port access only.
157
+ self.assertEqual(row('66 ba c8 03 ee a3 00 20 40 00 c3'), (5, port, [4]))
158
+ # call eax; mov dx, 0x3c8; out dx, al; mov [DATA_VA], eax; ret: every route from the unread call
159
+ # crosses the port access, so the row is outside the entry CFG and dependsOn names both.
160
+ self.assertEqual(row('ff d0 66 ba c8 03 ee a3 00 20 40 00 c3'), (7, port, [0, 6]))
161
+ # call eax; test eax, eax; jz store; mov dx, 0x3c8; out dx, al; store: mov [DATA_VA], eax; ret
162
+ # One route from the unread call skips the port access, so the row keeps the shared value.
163
+ c = Code().emit('ff d0 85 c0').branch('74', 'store').emit('66 ba c8 03 ee').label('store').emit('a3 00 20 40 00 c3')
164
+ self.assertEqual(row(c), (c.labels['store'], cfg, [0, c.labels['store'] - 1]))
165
+
166
+ def test_uses_claims_no_port_access_route_when_the_walk_reaches_its_limit(self):
167
+ # call eax; jz far; mov dx, 0x3c8; out dx, al; store: mov [DATA_VA], eax; ret; far: nop; nop; nop; ret
168
+ c = Code().emit('ff d0').branch('74', 'far').emit('66 ba c8 03 ee').label('store').emit('a3 00 20 40 00 c3')
169
+ c.label('far').emit('90 90 90 c3')
170
+ store = c.labels['store']
171
+ for limit, classification in ((100, 'operand past a PE32 port access; values and continuation unresolved'),
172
+ (5, 'entry-CFG operand past a stop; values and callee effects unresolved')):
173
+ with self.subTest(limit=limit):
174
+ r = report(c, 'uses', query={'offset': DATA_VA, 'width': 4}, instructionLimit=limit)
175
+ found, = r['conditionalAccesses']
176
+ self.assertEqual((found['site'] - CODE_RAW, found['classification']), (store, classification))
177
+ self.assertEqual(any(g.get('reason') == 'instruction limit' for g in r['gaps']), limit == 5)
178
+ self.assertFalse(r['negativeUsable'])
179
+
180
+ def test_uses_takes_the_access_direction_of_a_string_port_or_x87_operand_from_its_mnemonic(self):
181
+ # Capstone flags no access on an INS or OUTS memory operand and reports FSTP's store as a read.
182
+ cfg = 'entry-CFG operand past a stop; values and callee effects unresolved'
183
+ port = 'operand past a PE32 port access; values and continuation unresolved'
184
+ for name, code, expected in (('call eax; rep insb', 'ff d0 f3 6c c3', [(2, 'write', cfg)]),
185
+ ('call eax; outsd', 'ff d0 6f c3', [(2, 'read', cfg)]),
186
+ ('call eax; fstp dword [DATA_VA]', 'ff d0 d9 1d 00 20 40 00 c3', [(2, 'write', cfg)]),
187
+ ('mov dx, 0x3c8; out dx, al; insb', '66 ba c8 03 ee 6c c3', [(5, 'write', port)])):
188
+ with self.subTest(name):
189
+ r = report(code, 'uses', query={'offset': DATA_VA, 'width': 4})
190
+ self.assertEqual([(e['site'] - CODE_RAW, e['kind'], e['classification']) for e in r['conditionalAccesses']],
191
+ expected)
192
+ self.assertFalse(r['negativeUsable'])
193
+ # A read query no longer lists the FSTP store.
194
+ r = report('ff d0 d9 1d 00 20 40 00 c3', 'uses', query={'offset': DATA_VA, 'width': 4, 'access': 'read'})
195
+ self.assertEqual(r['conditionalAccesses'], [])
196
+
146
197
  def test_pop_addresses_its_destination_after_the_stack_pointer_moves(self):
147
198
  # push 1; push 2; push 3; pop dword [esp+4]; pop eax; pop ebx; ret
148
199
  regs = report('6a 01 6a 02 6a 03 8f 44 24 04 58 5b c3')['paths'][0]['registers']