scientific-method-engine 2.0.0__tar.gz → 2.2.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 (60) hide show
  1. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/cli.py +1 -0
  4. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/effect_order.py +9 -4
  5. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/machine.py +27 -7
  6. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/pcode.py +23 -1
  7. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/pcode_backend.py +65 -6
  8. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/reports.py +50 -15
  9. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/trace.py +71 -2
  10. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/values.py +3 -0
  11. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/tests/oracle.py +40 -6
  12. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/tests/test_effect_order.py +14 -3
  13. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/tests/test_oracle.py +54 -1
  14. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/tests/test_pe.py +12 -0
  15. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/tests/test_x86.py +316 -9
  16. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/.gitignore +0 -0
  17. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/LICENSE +0 -0
  18. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/README.md +0 -0
  19. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/__init__.py +0 -0
  20. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/__main__.py +0 -0
  21. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  22. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  23. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  24. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  25. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  26. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  27. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  28. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  29. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  30. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  31. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  32. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  33. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  34. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  35. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  36. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  37. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  38. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  39. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  40. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  41. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  42. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  43. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  44. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  45. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  46. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  47. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  48. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  49. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  50. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  51. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  52. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  53. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/image.py +0 -0
  54. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  55. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/pe.py +0 -0
  56. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  57. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/tests/test_dispatch.py +0 -0
  58. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/tests/test_memory_scopes.py +0 -0
  59. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/tests/test_nested_frame_request.py +0 -0
  60. {scientific_method_engine-2.0.0 → scientific_method_engine-2.2.0}/tests/test_table_continuations.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 2.0.0
3
+ Version: 2.2.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 = "2.0.0"
8
+ version = "2.2.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"
@@ -18,6 +18,7 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
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
20
  "Declared table continuations are separate conditional paths; ordinary computed transfers remain stopped.\n"
21
+ "Port accesses and interrupts are hardware-boundary events; portInputs supplies port reads as assumptions.\n"
21
22
  "callModels[].preservesMemory keeps explicit, bounded pre-call byte scopes across a modeled call; other memory stays unknown.\n"
22
23
  " scientific-method-engine ghidra-scripts")
23
24
 
@@ -3,7 +3,8 @@ from bisect import bisect_right
3
3
 
4
4
 
5
5
  KINDS = {"read", "write", "call", "call-return", "return", "branch", "compare", "flag-assumption",
6
- "arithmetic", "value-transfer", "conversion", "flag-write", "flags-save", "flags-restore", "local-iret", "string-operation", "declared-jump-continuation"}
6
+ "arithmetic", "value-transfer", "conversion", "flag-write", "flags-save", "flags-restore", "local-iret", "string-operation", "declared-jump-continuation",
7
+ "hardware-boundary"}
7
8
 
8
9
 
9
10
  def _storage(event):
@@ -29,7 +30,7 @@ def effect_ordering(report):
29
30
  combined = [(False, i, p) for i, p in enumerate(report["paths"])]
30
31
  combined += [(True, i, p) for i, p in enumerate(report.get("declaredContinuationPaths", []))]
31
32
  for conditional, index, path in combined:
32
- timeline, writes, calls, witnesses = [], [], [], []
33
+ timeline, writes, calls, witnesses, hardware = [], [], [], [], []
33
34
  snapshots = {}
34
35
  pending = {}
35
36
  unknown_orders = []
@@ -38,7 +39,9 @@ def effect_ordering(report):
38
39
  kind = event["kind"]
39
40
  if kind in KINDS:
40
41
  timeline.append(event)
41
- if kind == "read":
42
+ if kind == "hardware-boundary":
43
+ hardware.append(event["order"])
44
+ elif kind == "read":
42
45
  key = _storage(event)
43
46
  if key is not None:
44
47
  snapshots.setdefault(key, {})[event["value"].get("expression")] = event
@@ -91,7 +94,9 @@ def effect_ordering(report):
91
94
  "conditionalModels": path.get("conditionalModels", []),
92
95
  "writeOrders": [w["order"] for w in writes], "calls": calls,
93
96
  "localRestorationWitnesses": witnesses,
94
- "effectCompleteWithinModel": bool(path["returned"] and not unknown_orders and not conditional),
97
+ # Port and interrupt effects stay out of writeOrders: RAM writes never stand for device state.
98
+ "hardwareBoundaryOrders": hardware,
99
+ "effectCompleteWithinModel": bool(path["returned"] and not unknown_orders and not conditional and not hardware),
95
100
  "transactionality": "not established; local writes and result codes cannot prove external rollback"})
96
101
  report["effectOrdering"] = {"paths": summaries, "declaredContinuationPaths": conditional_summaries,
97
102
  "allPathsRead": report["completeWithinModel"],
@@ -18,6 +18,13 @@ class StopPath(Exception):
18
18
  pass
19
19
 
20
20
 
21
+ class Shared(dict):
22
+ """Read-only query configuration that every copy of a path shares instead of copying."""
23
+
24
+ def __deepcopy__(self, memo):
25
+ return self
26
+
27
+
21
28
  def segment_register(ins, mem):
22
29
  """Name the segment register an explicit memory operand uses (override or stack/data default)."""
23
30
  if mem.segment:
@@ -87,6 +94,8 @@ class State:
87
94
  self.visits = {}
88
95
  self.path = []
89
96
  self.conditional = []
97
+ # Values the query supplies for port reads, by site; trace validates them.
98
+ self.port_inputs = Shared({row["site"]: row for row in config.get("portInputs", [])})
90
99
  flags = config.get("flags", {})
91
100
  if not isinstance(flags, dict) or set(flags) - {"direction"}:
92
101
  raise ValueError("Only an explicit starting direction flag is supported")
@@ -334,8 +343,9 @@ for names, condition in ((("jne", "jnz"), "z"), (("jae", "jnb", "jnc"), "c"), ((
334
343
  for name in names:
335
344
  BRANCH_CONDITIONS[name] = (condition, True)
336
345
 
337
- # One-byte opcodes of the string forms; CMPS and SCAS repeat while a comparison holds.
338
- STRING_OPCODES = (0xA4, 0xA5, 0xAA, 0xAB, 0xAC, 0xAD)
346
+ # One-byte opcodes of the string forms (MOVS, STOS, LODS, INS, OUTS); CMPS and SCAS repeat while a
347
+ # comparison holds.
348
+ STRING_OPCODES = (0xA4, 0xA5, 0xAA, 0xAB, 0xAC, 0xAD, 0x6C, 0x6D, 0x6E, 0x6F)
339
349
  COMPARE_STRING_OPCODES = (0xA6, 0xA7, 0xAE, 0xAF)
340
350
 
341
351
 
@@ -352,6 +362,16 @@ def repeated(ins):
352
362
  return 0xF3 in ins.prefix or (0xF2 in ins.prefix and compare_string(ins))
353
363
 
354
364
 
365
+ def string_width(ins, flat):
366
+ """The element width of a string form: a byte for even opcodes, else the operand size."""
367
+ return 1 if ins.opcode[0] % 2 == 0 else (4 if (0x66 in ins.prefix) != flat else 2)
368
+
369
+
370
+ def string_operation(ins):
371
+ """The string operation's name without its width suffix: movs, stos, lods, cmps, scas, ins or outs."""
372
+ return ins.mnemonic.split()[-1][:-1]
373
+
374
+
355
375
  def string_count(state, ins):
356
376
  return state.reg("ecx" if state.flat else "cx") if repeated(ins) else const(1, state.bits)
357
377
 
@@ -370,8 +390,8 @@ def string_effect(state, ins, count, remaining, charge=None):
370
390
  the count runs out, within ``remaining`` iterations, and calls ``charge(1)`` for each one,
371
391
  because it cannot reserve its iterations before they run.
372
392
  """
373
- width = 1 if ins.opcode[0] % 2 == 0 else (4 if (0x66 in ins.prefix) != state.flat else 2)
374
- operation = ins.mnemonic.split()[-1][:4]
393
+ width = string_width(ins, state.flat)
394
+ operation = string_operation(ins)
375
395
  compare = compare_string(ins)
376
396
  state.event("string-operation", operation=operation, width=width, repetitions=count.report(),
377
397
  direction=state.direction_flag.report(), repeat=repeated(ins),
@@ -384,9 +404,9 @@ def string_effect(state, ins, count, remaining, charge=None):
384
404
  return 0
385
405
  if state.direction_flag.number is None:
386
406
  raise StopPath("Direction flag unresolved; conditional string paths required")
387
- # MOVS/LODS decode their source as the second memory operand and CMPS as the first, carrying
388
- # any segment override.
389
- source_name = (segment_register(ins, ins.operands[1].mem) if operation in ("movs", "lods") else
407
+ # MOVS/LODS/OUTS decode their source as the second operand and CMPS as the first, carrying any
408
+ # segment override.
409
+ source_name = (segment_register(ins, ins.operands[1].mem) if operation in ("movs", "lods", "outs") else
390
410
  segment_register(ins, ins.operands[0].mem) if operation == "cmps" else None)
391
411
  counter = "ecx" if state.flat else "cx"
392
412
  if not compare or not repeated(ins):
@@ -95,13 +95,17 @@ class Run:
95
95
  ``registers`` holds the last value written to each register before ``setreg`` added its site,
96
96
  and ``flags`` the arithmetic flags the instruction wrote. ``present(value)`` may rewrite a
97
97
  value written to a register or memory into an equal term of the form reports use.
98
+ ``port(direction, port, value, size)`` handles SLEIGH's ``in`` (direction ``"input"``, value
99
+ None, returns the value read) and ``out`` (``"output"``) user operations; without it they
100
+ stop the path.
98
101
  """
99
102
 
100
- def __init__(self, state, ops, memory, constant=None, flags=None, present=None):
103
+ def __init__(self, state, ops, memory, constant=None, flags=None, present=None, port=None):
101
104
  self.state = state
102
105
  self.ops = ops
103
106
  self.memory = memory
104
107
  self.constant = constant
108
+ self.port = port
105
109
  self.present = present or (lambda value: value)
106
110
  self.temps = {}
107
111
  self.registers = {}
@@ -124,6 +128,13 @@ class Run:
124
128
  if code == "CALLOTHER":
125
129
  if o.userop in ("LOCK", "UNLOCK") and o.output is None:
126
130
  continue # Atomicity markers; a single path has no other bus master.
131
+ if o.userop in ("in", "out") and self.port is not None:
132
+ if o.userop == "in":
133
+ self.write(o.output, self.port("input", self.read(o.inputs[1]), None, o.output[2]))
134
+ else:
135
+ port, data = self.port_operands(o.inputs[1:])
136
+ self.port("output", self.read(port), self.read(data), data[2])
137
+ continue
127
138
  if o.userop != "segment":
128
139
  raise StopPath("Unsupported p-code user operation: " + str(o.userop))
129
140
  name = self.register_name(o.inputs[1])
@@ -139,6 +150,17 @@ class Run:
139
150
  self.write(o.output, evaluate(code, arguments, o.output[2] * 8, self.state.at))
140
151
  return None
141
152
 
153
+ def port_operands(self, inputs):
154
+ """The port and data varnodes of an ``out`` operation.
155
+
156
+ SLEIGH writes OUT as ``out(port, value)`` and OUTS as ``out(value, DX)``. The port is the
157
+ operand that is a constant or DX; the data is never either.
158
+ """
159
+ ports = [v for v in inputs if v[0] == "const" or (v[0] == "register" and self.register_name(v) == "DX")]
160
+ if len(inputs) != 2 or len(ports) != 1:
161
+ raise StopPath("p-code port output has no single port operand")
162
+ return ports[0], inputs[1] if inputs[0] == ports[0] else inputs[0]
163
+
142
164
  def register_name(self, v):
143
165
  name = LIFTER.register(self.state.flat, v[1], v[2])
144
166
  if name is None:
@@ -10,10 +10,10 @@ What this module and ``pcode.Run`` use of a ``State``:
10
10
  - Methods: ``get``, ``put``, ``reg``, ``setreg``, ``segment``, ``access``, ``address``, ``event``,
11
11
  ``set_flags``, ``forget_flags``, ``carry_value``, ``save_flags`` and ``restore_flags``.
12
12
  - Read only: ``at``, ``bits``, ``flat``, ``sp``, ``flags``, ``flag_serial``, ``flag_epoch``,
13
- ``unknown_flag_site``, ``segment_bases`` and ``value_transfers``.
13
+ ``unknown_flag_site``, ``segment_bases``, ``value_transfers``, ``events`` and ``port_inputs``.
14
14
  - Read and assigned: ``flag_values`` (the arithmetic flags p-code computed, or None), ``carry``,
15
15
  ``direction_flag`` and ``interrupt_flag``. ``conditional`` is appended to (the divide-error
16
- assumption).
16
+ and port-input assumptions).
17
17
 
18
18
  Every member above belongs to one path, and ``trace`` copies a path with ``deepcopy`` when a branch
19
19
  splits it. The backend keeps no path state of its own: ``Pypcode.__deepcopy__`` returns the same
@@ -356,7 +356,8 @@ class Frame:
356
356
  WIDTHS[value.term] = value.bits
357
357
  LEAVES.add(value.term)
358
358
  present = (lambda value: self.present(value, self)) if self.present else None
359
- self.run = Run(self.state, self.ops, self.memory, self.constant, present=present)
359
+ self.run = Run(self.state, self.ops, self.memory, self.constant, present=present,
360
+ port=lambda *access: port_access(self.state, self.ins, *access))
360
361
  self.run.execute()
361
362
  for value in [*self.loaded.values(), *self.run.temps.values(), *self.run.registers.values()]:
362
363
  if isinstance(value, Value): # Real-mode temporaries may hold a segmented Address.
@@ -470,7 +471,8 @@ class Pypcode:
470
471
  def string_iteration(self, state, ins, operation, width, source_segment):
471
472
  """Apply one iteration of an accepted string form; see ``machine.string_effect``.
472
473
 
473
- ``source_segment`` names the source operand's segment register (MOVS, LODS and CMPS only).
474
+ ``source_segment`` names the source operand's segment register (MOVS, LODS, OUTS and CMPS
475
+ only).
474
476
  p-code steps SI and DI by the direction flag. For a repeated CMPS or SCAS, returns whether
475
477
  the repeat condition holds afterwards (1, 0 or unknown); otherwise None.
476
478
  """
@@ -506,7 +508,7 @@ class Pypcode:
506
508
 
507
509
  ops, tail = string_ops(state.flat, bytes(ins.bytes), state.at, operation)
508
510
  accumulator = state.reg({1: "al", 2: "ax", 4: "eax"}[width]) if operation == "scas" else None
509
- run = Run(state, ops, memory)
511
+ run = Run(state, ops, memory, port=lambda *access: port_access(state, ins, *access))
510
512
  run.execute()
511
513
  if operation not in ("cmps", "scas"):
512
514
  return None
@@ -909,6 +911,62 @@ def flag_write(state, ins, image):
909
911
  interpretation="local flag effect only; interrupts and timing are not simulated")
910
912
 
911
913
 
914
+ OUTPUT_MEANING = ("the value leaves the instruction model at this port; device state, timing and "
915
+ "rendered output are not modeled")
916
+ INPUT_MEANING = ("the value a device returns is not modeled; a supplied value is a query assumption, "
917
+ "never native device state")
918
+
919
+
920
+ def port_access(state, ins, direction, port, value, size):
921
+ """Report one port input or output as a hardware-boundary event; return the value read.
922
+
923
+ The port number and the value written come from the p-code. A value read is unknown unless the
924
+ query's ``portInputs`` supplies one for this site, which the path then lists as an assumption.
925
+ The flat model stops after the event, because I/O privilege decides whether the access faults.
926
+ """
927
+ port = resize(port, 16)
928
+ fields = {"boundary": "port-" + direction, "mnemonic": ins.mnemonic.split()[-1], "port": port.report(),
929
+ "portKnown": port.number is not None, "width": size}
930
+ if direction == "output":
931
+ state.event("hardware-boundary", **fields, value=value.report(), interpretation=OUTPUT_MEANING)
932
+ result = None
933
+ else:
934
+ supplied = state.port_inputs.get(state.at)
935
+ if supplied is None:
936
+ result = unknown(f"port-input:{state.at}:{len(state.events)}", size * 8, state.at)
937
+ fields["valueSource"] = "unknown"
938
+ else:
939
+ result = const(supplied["value"], size * 8, state.at)
940
+ fields.update(valueSource="query assumption", evidence=supplied["evidence"])
941
+ assumption = {"site": state.at, "evidence": supplied["evidence"],
942
+ "assumption": "port input value supplied by the query; device state unconfirmed"}
943
+ # Every read at the site uses the same supplied value, so the path lists it once.
944
+ if assumption not in state.conditional:
945
+ state.conditional.append(assumption)
946
+ state.event("hardware-boundary", **fields, value=result.report(), interpretation=INPUT_MEANING)
947
+ if state.flat:
948
+ raise StopPath("port access in the flat model depends on I/O privilege, which is not modeled")
949
+ return result
950
+
951
+
952
+ def interrupt_vector(flat, ins, site):
953
+ """The vector p-code's ``swi`` operation names, and whether the interrupt is conditional (INTO)."""
954
+ ops, _ = LIFTER.ops(flat, bytes(ins.bytes), site)
955
+ call = next((o for o in ops if o.code == "CALLOTHER" and o.userop == "swi"), None)
956
+ vector = call.inputs[1][1] if call is not None and call.inputs[1][0] == "const" else None
957
+ return vector, any(o.code == "CBRANCH" for o in ops)
958
+
959
+
960
+ def interrupt(state, ins, image):
961
+ vector, conditional = interrupt_vector(state.flat, ins, state.at)
962
+ if conditional:
963
+ # INTO interrupts only when OF is set; that branch is not modeled.
964
+ raise StopPath("Unsupported instruction semantics: " + ins.mnemonic)
965
+ state.event("hardware-boundary", boundary="interrupt", mnemonic=ins.mnemonic, vector=vector,
966
+ interpretation="the interrupt handler and its effects are not modeled")
967
+ raise StopPath("interrupt handler is not modeled; later effects are not read")
968
+
969
+
912
970
  HANDLERS = {}
913
971
  for names, handler in ((("mov", "movzx", "movsx", "xchg"), move), (("nop",), nop), (("lea",), lea),
914
972
  (("lds", "les"), far_pointer), (("push",), push), (("pop",), pop), (("leave",), leave),
@@ -917,7 +975,8 @@ for names, handler in ((("mov", "movzx", "movsx", "xchg"), move), (("nop",), nop
917
975
  (("neg",), negate), (("adc", "sbb"), carry_arithmetic), (("clc", "stc", "cmc"), carry_flag),
918
976
  (("shl", "sal", "shr", "sar"), shift), (("rol", "ror", "rcl", "rcr"), rotate),
919
977
  (("mul", "imul"), multiply), (("div", "idiv"), divide),
920
- (("cbw", "cwde", "cwd", "cdq"), conversion), (("cld", "std", "cli", "sti"), flag_write)):
978
+ (("cbw", "cwde", "cwd", "cdq"), conversion), (("cld", "std", "cli", "sti"), flag_write),
979
+ (("in", "out"), run_plain), (("int", "int1", "int3", "into"), interrupt)):
921
980
  for name in names:
922
981
  HANDLERS[name] = handler
923
982
 
@@ -4,13 +4,14 @@ from bisect import bisect_right
4
4
  from collections import deque
5
5
  from capstone import CS_AC_READ, CS_AC_WRITE
6
6
  from capstone.x86 import X86_OP_IMM, X86_OP_MEM, X86_OP_REG
7
- from .machine import State, StopPath, REGISTERS, ALIASES, segment_register
7
+ from .machine import State, StopPath, REGISTERS, ALIASES, segment_register, string_instruction
8
8
  from .values import unknown
9
9
  from .effect_order import effect_ordering
10
10
  from .result_flow import return_flows
11
11
  from .image import Image, integer
12
12
  from .trace import (trace, walk, call_target, unsupported_transfer, uncovered, base_mnemonic, OVERLAP_REASON, CONTESTED_REASON,
13
- RETURNS, INTERRUPTS, PORTS)
13
+ RETURNS, INTERRUPTS, PORTS, PORT_INPUTS, port_width)
14
+ from .pcode_backend import interrupt_vector
14
15
 
15
16
 
16
17
  def entries(image):
@@ -748,16 +749,32 @@ def call_target_report(image, config):
748
749
  return result
749
750
 
750
751
 
752
+ def hardware_boundary(image, at, ins):
753
+ """The static description of one interrupt or port instruction, from its decoding and p-code."""
754
+ m = base_mnemonic(ins)
755
+ if m in INTERRUPTS:
756
+ vector, conditional = interrupt_vector(image.flat, ins, at)
757
+ return {"site": at, "boundary": "interrupt", "mnemonic": m, "vector": vector, "conditional": conditional}
758
+ port = next(o for o in ins.operands if o.type == X86_OP_IMM or (o.type == X86_OP_REG and ins.reg_name(o.reg) == "dx"))
759
+ return {"site": at, "boundary": "port-input" if m in PORT_INPUTS else "port-output", "mnemonic": m,
760
+ "port": {"source": "immediate", "value": port.imm} if port.type == X86_OP_IMM else {"source": "register", "register": "dx"},
761
+ "width": port_width(ins, image.flat), "stringForm": string_instruction(ins),
762
+ # F2 on INS/OUTS repeats on hardware too; trace stops that form as unsupported.
763
+ "repeated": 0xF2 in ins.prefix or 0xF3 in ins.prefix}
764
+
765
+
751
766
  def body(image, entry, limit=10000):
752
767
  """Every instruction one entry reaches without entering a callee, and every way out of it.
753
768
 
754
769
  Calls, interrupts and port accesses are followed to the next instruction, and each such
755
- continuation is listed as an assumption. A direct jump or conditional branch to another
756
- established entry or another region, and every far jump, is a tail transfer.
770
+ continuation is listed as an assumption. Interrupts and port accesses are also listed as
771
+ hardware boundaries. A direct jump or conditional branch to another established entry or
772
+ another region, and every far jump, is a tail transfer.
757
773
  """
758
774
  integer(limit, 1, 100000, "instruction limit")
759
775
  established = set(entries(image))
760
776
  pending, seen, exits, calls, gaps, assumed, shared = [entry], {}, [], [], [], [], set()
777
+ hardware = []
761
778
 
762
779
  def leaves(at, target):
763
780
  return (target in established and target != entry) or image.region(target) is not image.region(at)
@@ -786,6 +803,7 @@ def body(image, entry, limit=10000):
786
803
  exits.append({"site": at, "kind": "halt"})
787
804
  continue
788
805
  if m in INTERRUPTS or m in PORTS:
806
+ hardware.append(hardware_boundary(image, at, ins))
789
807
  assumed.append({"site": at, "assumption": ("the interrupt returns to the next instruction" if m in INTERRUPTS
790
808
  else "the port access continues to the next instruction")})
791
809
  pending.append(following)
@@ -850,6 +868,7 @@ def body(image, entry, limit=10000):
850
868
  "span": {"start": runs[0][0], "end": runs[-1][1]} if runs else None, "coveredBytes": covered,
851
869
  "exits": sorted(exits, key=lambda e: e["site"]), "calls": sorted(calls, key=lambda c: c["site"]),
852
870
  "assumedContinuations": sorted(assumed, key=lambda a: a["site"]), "sharedEntries": sorted(shared),
871
+ "hardwareBoundaries": sorted(hardware, key=lambda h: h["site"]),
853
872
  "gaps": gaps, "complete": bool(exits) and not gaps}
854
873
 
855
874
 
@@ -1033,19 +1052,22 @@ def _ghidra_call_edges(image, export):
1033
1052
  return integer(value, 0, len(image.data) - 1, "Ghidra " + label + " file offset")
1034
1053
  callers, unmapped, total = {}, [], 0
1035
1054
  for function in functions:
1036
- if not isinstance(function, dict) or not isinstance(function.get("address"), str) or not isinstance(function.get("edges"), list):
1055
+ # The script writes every key, with null for an address that has no file bytes. A missing key is a malformed export.
1056
+ if (not isinstance(function, dict) or "entry" not in function or not isinstance(function.get("address"), str)
1057
+ or not isinstance(function.get("edges"), list)):
1037
1058
  raise ValueError("Invalid ghidraCallEdges function")
1038
1059
  total += len(function["edges"])
1039
1060
  if total > 8192:
1040
1061
  raise ValueError("ghidraCallEdges holds more than 8192 edges")
1041
1062
  rows = []
1042
1063
  for edge in function["edges"]:
1043
- if (not isinstance(edge, dict) or not isinstance(edge.get("siteAddress"), str) or not isinstance(edge.get("flow"), str)
1044
- or not (edge.get("targetAddress") is None or isinstance(edge["targetAddress"], str))):
1064
+ if (not isinstance(edge, dict) or not {"site", "target", "targetAddress"} <= edge.keys()
1065
+ or not isinstance(edge.get("siteAddress"), str) or not isinstance(edge.get("flow"), str)
1066
+ or not (edge["targetAddress"] is None or isinstance(edge["targetAddress"], str))):
1045
1067
  raise ValueError("Invalid ghidraCallEdges edge")
1046
- rows.append({"site": offset(edge.get("site"), "site"), "siteAddress": edge["siteAddress"],
1047
- "target": offset(edge.get("target"), "target"), "targetAddress": edge["targetAddress"], "flow": edge["flow"]})
1048
- entry = offset(function.get("entry"), "entry")
1068
+ rows.append({"site": offset(edge["site"], "site"), "siteAddress": edge["siteAddress"],
1069
+ "target": offset(edge["target"], "target"), "targetAddress": edge["targetAddress"], "flow": edge["flow"]})
1070
+ entry = offset(function["entry"], "entry")
1049
1071
  if entry is None:
1050
1072
  unmapped.append(function["address"])
1051
1073
  elif entry in callers:
@@ -1075,6 +1097,7 @@ def _ghidra_cross_check(export, nodes, outgoing, omitted):
1075
1097
  for caller in compared:
1076
1098
  ours = outgoing.get(caller, [])
1077
1099
  theirs = callers[caller]
1100
+ instructions = nodes[caller]["body"]["instructions"]
1078
1101
  # A call neither analysis resolved matches on its site with no target.
1079
1102
  flows = {_ghidra_key(g): g["flow"] for g in theirs if g["site"] is not None}
1080
1103
  read = {(e["site"], e["target"]) for e in ours}
@@ -1085,11 +1108,20 @@ def _ghidra_cross_check(export, nodes, outgoing, omitted):
1085
1108
  for g in theirs:
1086
1109
  if g["site"] is not None and _ghidra_key(g) in read:
1087
1110
  continue
1111
+ ins = instructions.get(g["site"])
1112
+ if ins is not None and base_mnemonic(ins) in INTERRUPTS and _ghidra_key(g)[1] is None:
1113
+ # SLEIGH lifts INT, INT1, INT3 and INTO to a computed call with no target, while the engine assumes the
1114
+ # interrupt returns to the next instruction and records no edge. At INT1 and INT3 Ghidra's flow is a
1115
+ # terminator that ends the function there.
1116
+ rows.append({"caller": caller, "site": g["site"], "target": None, "siteAddress": g["siteAddress"],
1117
+ "targetAddress": None, "ghidraFlow": g["flow"], "result": "interrupt", "engineEdge": None,
1118
+ "ghidraFallsThrough": "TERMINATOR" not in g["flow"]})
1119
+ continue
1088
1120
  # Ghidra's edge is evidence the engine did not check; it never becomes an engine edge.
1089
1121
  rows.append({"caller": caller, "site": g["site"], "target": g["target"], "siteAddress": g["siteAddress"],
1090
1122
  "targetAddress": g["targetAddress"], "ghidraFlow": g["flow"], "result": "ghidraOnly", "checked": False,
1091
1123
  "engineEdge": next((e["id"] for e in ours if g["site"] is not None and e["site"] == g["site"]), None)})
1092
- counts = {kind: sum(r["result"] == kind for r in rows) for kind in ("agreement", "engineOnly", "ghidraOnly")}
1124
+ counts = {kind: sum(r["result"] == kind for r in rows) for kind in ("agreement", "engineOnly", "ghidraOnly", "interrupt")}
1093
1125
  not_compared = {"engineCallers": sorted(nodes.keys() - callers.keys()), "ghidraCallers": sorted(callers.keys() - nodes.keys()),
1094
1126
  "unmappedGhidraFunctions": export["unmappedFunctions"], "missingGhidraEntries": export["missingEntries"],
1095
1127
  "unreadGhidraFunctions": export["unreadFunctions"],
@@ -1097,12 +1129,15 @@ def _ghidra_cross_check(export, nodes, outgoing, omitted):
1097
1129
  # A site agrees only when every edge either analysis read there agrees.
1098
1130
  disputed = {r["site"] for r in rows if r["result"] != "agreement"}
1099
1131
  return {"comparedCallers": compared, "edges": rows, "counts": counts, "notCompared": not_compared,
1100
- "agreed": not counts["engineOnly"] and not counts["ghidraOnly"] and not any(not_compared.values()),
1132
+ "agreed": (not counts["engineOnly"] and not counts["ghidraOnly"] and not any(not_compared.values())
1133
+ and all(r["ghidraFallsThrough"] for r in rows if r["result"] == "interrupt")),
1101
1134
  "agreementSites": {r["site"] for r in rows if r["result"] == "agreement"} - disputed,
1102
1135
  "interpretation": "Edges of each caller that both the engine and the Ghidra export read, matched by site and target "
1103
1136
  "file offset; an unresolved call matches an unresolved call at its site, and a Ghidra target without a file offset "
1104
- "matches no engine edge. A ghidraOnly edge is Ghidra's claim: the engine did not check it and never adds it to "
1105
- "its graph. Agreement means both analyses read the edge, not that it executes."}
1137
+ "matches no engine edge. An interrupt row is Ghidra's targetless call at an instruction the engine read as an "
1138
+ "interrupt and assumed to return; it counts against agreed only when Ghidra's flow ends the function there. "
1139
+ "A ghidraOnly edge is Ghidra's claim: the engine did not check it and never adds it to its graph. Agreement "
1140
+ "means both analyses read the edge, not that it executes."}
1106
1141
 
1107
1142
 
1108
1143
  # These branches test CX/ECX (LOOPE/LOOPNE also ZF), so an adjacent CMP/TEST never describes their predicate.
@@ -1492,7 +1527,7 @@ def _run_report(image, config, command):
1492
1527
  if command == "returns":
1493
1528
  report = return_flows(report, config)
1494
1529
  if command != "trace":
1495
- kinds = {"arguments": ("address-formation", "read", "call", "call-return"), "effects": ("address-formation", "write", "call", "call-return", "return", "branch", "string-operation",
1530
+ kinds = {"arguments": ("address-formation", "read", "call", "call-return"), "effects": ("address-formation", "write", "call", "call-return", "return", "branch", "string-operation", "hardware-boundary",
1496
1531
  "flag-assumption", "flag-write", "flags-save", "flags-restore", "local-iret"),
1497
1532
  "returns": ("return", "call-return", "compare", "branch", "write"),
1498
1533
  "guards": ("compare", "branch", "read", "write", "call", "call-return"),
@@ -3,7 +3,7 @@ from copy import deepcopy
3
3
  from capstone.x86 import X86_OP_IMM, X86_OP_REG, X86_OP_MEM
4
4
  from .image import integer
5
5
  from .machine import (State, StopPath, REGISTERS, ALIASES, BRANCH_CONDITIONS, string_instruction,
6
- string_count, string_effect, check_string_form, compare_string, repeated)
6
+ string_count, string_effect, check_string_form, compare_string, repeated, string_width)
7
7
  from .values import const, unknown, sources, op, Value
8
8
  from .result_flow import validate_contracts, result_contracts
9
9
  from .memory_scopes import validate_scopes, capture_scopes, retain_scopes
@@ -21,6 +21,7 @@ OVERLAP_REASON = "overlapping entry-path instructions; boundary unresolved"
21
21
  RETURNS = {"ret": "near return", "retf": "far return", "iret": "interrupt return", "iretd": "interrupt return"}
22
22
  INTERRUPTS = ("int", "int1", "int3", "into")
23
23
  PORTS = ("in", "out", "insb", "insw", "insd", "outsb", "outsw", "outsd")
24
+ PORT_INPUTS = ("in", "insb", "insw", "insd")
24
25
 
25
26
 
26
27
  def base_mnemonic(ins):
@@ -110,9 +111,10 @@ def walk(image, entries, limit=10000):
110
111
  following_sites.append(target)
111
112
  if m in ("jmp", "ljmp"):
112
113
  continue
113
- if m in INTERRUPTS or m == "hlt" or m in PORTS:
114
+ if m in INTERRUPTS or m == "hlt":
114
115
  gaps.append({"site": at, "reason": "hardware or interrupt boundary"})
115
116
  continue
117
+ # A port access continues at the next instruction, as trace and body() follow it.
116
118
  if m in ("call", "lcall") and following not in following_sites:
117
119
  returns.add((at, following))
118
120
  pending.append(following)
@@ -211,6 +213,67 @@ def uncovered(start, end, spans):
211
213
  return missing
212
214
 
213
215
 
216
+ def port_width(ins, flat):
217
+ """The data width of a port instruction: its register operand, or its string element."""
218
+ if base_mnemonic(ins) in ("in", "out"):
219
+ return ins.operands[0 if base_mnemonic(ins) == "in" else 1].size
220
+ return string_width(ins, flat)
221
+
222
+
223
+ def validate_port_inputs(config, image):
224
+ """Check ``portInputs``: each row names an IN or INS site, a value that fits its width, and evidence."""
225
+ rows = config.get("portInputs", [])
226
+ if not isinstance(rows, list) or len(rows) > 64:
227
+ raise ValueError("portInputs must be a list of at most 64 rows")
228
+ if rows and image.flat:
229
+ raise ValueError("portInputs are outside the PE32 flat model, where a port access stops the path")
230
+ sites = set()
231
+ for row in rows:
232
+ if not isinstance(row, dict) or not row.get("evidence"):
233
+ raise ValueError("Port input requires site, value and evidence")
234
+ site = integer(row.get("site"), 0, len(image.data) - 1, "port input site")
235
+ if site in sites:
236
+ raise ValueError("Port input sites must be unique")
237
+ sites.add(site)
238
+ ins = image.decode(site)
239
+ if ins is None or base_mnemonic(ins) not in PORT_INPUTS:
240
+ raise ValueError("Port input site must be an IN or INS instruction")
241
+ integer(row.get("value"), 0, (1 << 8 * port_width(ins, image.flat)) - 1, "port input value")
242
+
243
+
244
+ def hardware_placement(outputs, conditional_outputs, gaps):
245
+ """Each hardware boundary site with the traced paths that reach it.
246
+
247
+ ``gaps`` are the ordinary paths' gaps. ``placement`` is ``everyTracedPath`` when every
248
+ ordinary path reaches the site and no ordinary path was dropped, ``conditional`` when a path
249
+ returned without reaching it, and ``unresolved`` when only stopped paths lack it or a limit
250
+ dropped paths.
251
+ """
252
+ rows = {}
253
+ for group, paths in (("paths", outputs), ("declaredContinuationPaths", conditional_outputs)):
254
+ for index, path in enumerate(paths):
255
+ for e in path["events"]:
256
+ if e["kind"] != "hardware-boundary":
257
+ continue
258
+ row = rows.setdefault((e["site"], e["boundary"]), {
259
+ "site": e["site"], "boundary": e["boundary"], "mnemonic": e["mnemonic"],
260
+ "paths": [], "declaredContinuationPaths": []})
261
+ # Paths are visited in index order, so a repeat visit is always the last one listed.
262
+ if row[group][-1:] != [index]:
263
+ row[group].append(index)
264
+ result = []
265
+ for (site, _), row in sorted(rows.items()):
266
+ reached = set(row["paths"])
267
+ missing = [i for i in range(len(outputs)) if i not in reached]
268
+ returned = [i for i in missing if outputs[i]["returned"]]
269
+ stopped = [i for i in missing if not outputs[i]["returned"]]
270
+ row["pathsWithout"] = {"returned": returned, "stopped": stopped}
271
+ row["placement"] = ("conditional" if returned else
272
+ "everyTracedPath" if not missing and not gaps else "unresolved")
273
+ result.append(row)
274
+ return result
275
+
276
+
214
277
  def snapshot(state):
215
278
  return {name: state.reg(name).report() for name in ALIASES}
216
279
 
@@ -233,6 +296,7 @@ def trace(image, config, continue_declared_jumps=True):
233
296
  if config.get("returnBytes", image.bits // 8) not in ((4,) if image.flat else (2, 4)):
234
297
  raise ValueError("returnBytes must agree with the selected near/far frame model")
235
298
  contracts = validate_contracts(config, image)
299
+ validate_port_inputs(config, image)
236
300
  models = config.get("callModels", [])
237
301
  if not isinstance(models, list) or len(models) > 64:
238
302
  raise ValueError("At most 64 explicit call models")
@@ -368,8 +432,12 @@ def trace(image, config, continue_declared_jumps=True):
368
432
  pending.append(child)
369
433
  created += 1
370
434
 
435
+ # Ordinary paths all finish before the first declared continuation runs; their gaps come first.
436
+ ordinary_gaps = None
371
437
  while pending or deferred:
372
438
  if not pending:
439
+ if ordinary_gaps is None:
440
+ ordinary_gaps = len(global_gaps)
373
441
  declared_continuations(deferred.pop(0))
374
442
  continue
375
443
  state = pending.pop()
@@ -633,6 +701,7 @@ def trace(image, config, continue_declared_jumps=True):
633
701
  except StopPath as error:
634
702
  finish(state, str(error))
635
703
  return {"paths": outputs, "declaredContinuationPaths": conditional_outputs, "gaps": global_gaps,
704
+ "hardwareBoundaries": hardware_placement(outputs, conditional_outputs, global_gaps[:ordinary_gaps]),
636
705
  "completeWithinModel": not global_gaps and bool(outputs) and all(p["returned"] for p in outputs),
637
706
  "nativeReachability": "unconfirmed", "stepsUsed": total_steps, "stringIterationsUsed": total_string_steps,
638
707
  "limits": {"steps": max_steps, "paths": max_paths, "depth": max_depth}}
@@ -122,6 +122,9 @@ def op(name, a, b, site=None):
122
122
  return Value(bits, const(n, bits).term, origin)
123
123
  if name in ("sub", "xor") and a.term == b.term:
124
124
  return Value(bits, const(0, bits).term, origin)
125
+ if name == "add" and a.number is not None:
126
+ # c + x is x + c, so an address built as a constant plus a register keeps the register's base.
127
+ a, b = b, a
125
128
  if name in ("add", "sub") and b.number is not None:
126
129
  delta = b.number if name == "add" else -b.number
127
130
  base = a.term