scientific-method-engine 2.0.0__tar.gz → 2.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 (60) hide show
  1. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/cli.py +1 -0
  4. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/effect_order.py +9 -4
  5. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/machine.py +27 -7
  6. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/pcode.py +23 -1
  7. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/pcode_backend.py +65 -6
  8. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/reports.py +24 -5
  9. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/trace.py +71 -2
  10. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/values.py +3 -0
  11. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/tests/oracle.py +40 -6
  12. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/tests/test_effect_order.py +14 -3
  13. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/tests/test_oracle.py +54 -1
  14. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/tests/test_pe.py +12 -0
  15. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/tests/test_x86.py +245 -5
  16. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/.gitignore +0 -0
  17. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/LICENSE +0 -0
  18. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/README.md +0 -0
  19. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/__init__.py +0 -0
  20. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/__main__.py +0 -0
  21. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  22. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  23. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  24. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  25. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  26. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  27. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  28. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  29. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  30. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  31. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  32. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  33. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  34. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  35. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  36. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  37. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  38. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  39. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  40. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  41. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  42. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  43. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  44. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  45. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  46. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  47. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  48. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  49. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  50. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  51. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  52. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  53. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/image.py +0 -0
  54. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  55. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
  56. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  57. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/tests/test_dispatch.py +0 -0
  58. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/tests/test_memory_scopes.py +0 -0
  59. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.0}/tests/test_nested_frame_request.py +0 -0
  60. {scientific_method_engine-2.0.0 → scientific_method_engine-2.1.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.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 = "2.0.0"
8
+ version = "2.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"
@@ -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
 
@@ -1492,7 +1511,7 @@ def _run_report(image, config, command):
1492
1511
  if command == "returns":
1493
1512
  report = return_flows(report, config)
1494
1513
  if command != "trace":
1495
- kinds = {"arguments": ("address-formation", "read", "call", "call-return"), "effects": ("address-formation", "write", "call", "call-return", "return", "branch", "string-operation",
1514
+ kinds = {"arguments": ("address-formation", "read", "call", "call-return"), "effects": ("address-formation", "write", "call", "call-return", "return", "branch", "string-operation", "hardware-boundary",
1496
1515
  "flag-assumption", "flag-write", "flags-save", "flags-restore", "local-iret"),
1497
1516
  "returns": ("return", "call-return", "compare", "branch", "write"),
1498
1517
  "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
@@ -7,7 +7,7 @@ engine resolved to a constant at the routine's return with Unicorn's value there
7
7
  import sys
8
8
  from pathlib import Path
9
9
 
10
- from unicorn import UC_ARCH_X86, UC_MODE_16, Uc
10
+ from unicorn import UC_ARCH_X86, UC_HOOK_INSN, UC_HOOK_INTR, UC_MODE_16, Uc
11
11
  from unicorn import x86_const as U
12
12
 
13
13
  sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
@@ -25,9 +25,16 @@ def configuration(data, registers, **extra):
25
25
  "entry": 0, "registers": registers, **extra}
26
26
 
27
27
 
28
- def unicorn(data, registers, direction=None):
29
- """Registers after running ``data`` up to its first byte-0xC3 return reached, as Unicorn sees them."""
28
+ def unicorn(data, registers, direction=None, ports=None, outputs=None):
29
+ """Registers after running ``data`` up to its first byte-0xC3 return reached, as Unicorn sees them.
30
+
31
+ A port read returns ``ports[port]``; each port write is appended to ``outputs`` as
32
+ ``(port, size, value)``.
33
+ """
30
34
  uc = Uc(UC_ARCH_X86, UC_MODE_16)
35
+ uc.hook_add(UC_HOOK_INSN, lambda uc, port, size, _: (ports or {})[port], None, 1, 0, U.UC_X86_INS_IN)
36
+ uc.hook_add(UC_HOOK_INSN, lambda uc, port, size, value, _: (outputs if outputs is not None else []).append((port, size, value)),
37
+ None, 1, 0, U.UC_X86_INS_OUT)
31
38
  uc.mem_map(0, 0x110000)
32
39
  base = SEGMENT * 16
33
40
  uc.mem_write(base, data)
@@ -49,21 +56,48 @@ def unicorn(data, registers, direction=None):
49
56
  return stopped.get("at"), {name: uc.reg_read(getattr(U, "UC_X86_REG_" + name.upper())) for name in names}
50
57
 
51
58
 
52
- def check(test, code, registers=None, direction=None, resolved=()):
59
+ def interrupt(code):
60
+ """The interrupt number Unicorn raises first when running ``code``, or None."""
61
+ data = bytes.fromhex(code)
62
+ uc = Uc(UC_ARCH_X86, UC_MODE_16)
63
+ uc.mem_map(0, 0x110000)
64
+ uc.mem_write(SEGMENT * 16, data)
65
+ uc.reg_write(U.UC_X86_REG_CS, SEGMENT)
66
+ for name, value in STACK.items():
67
+ uc.reg_write(getattr(U, "UC_X86_REG_" + name.upper()), value)
68
+ raised = []
69
+
70
+ def hook(uc, number, _):
71
+ raised.append(number)
72
+ uc.emu_stop()
73
+ uc.hook_add(UC_HOOK_INTR, hook)
74
+ uc.emu_start(SEGMENT * 16, SEGMENT * 16 + len(data), count=100)
75
+ return raised[0] if raised else None
76
+
77
+
78
+ def check(test, code, registers=None, direction=None, resolved=(), ports=None, port_inputs=None):
53
79
  """Compare the engine's resolved registers with Unicorn's for one synthetic routine.
54
80
 
55
81
  Routines write any memory they read, because the engine starts with memory unknown and
56
- Unicorn with zeros. ``resolved`` names registers the engine must resolve.
82
+ Unicorn with zeros. ``resolved`` names registers the engine must resolve. ``ports`` gives
83
+ Unicorn's port reads and ``port_inputs`` the engine's ``portInputs`` rows for the same values;
84
+ every port write the engine reports must match Unicorn's, in order.
57
85
  """
58
86
  data = bytes.fromhex(code)
59
87
  registers = {**STACK, **(registers or {})}
60
88
  flags = {} if direction is None else {"flags": {"direction": direction}}
89
+ if port_inputs:
90
+ flags["portInputs"] = port_inputs
61
91
  result = run_report(data, configuration(data, registers, **flags), "trace")
62
92
  test.assertEqual(len(result["paths"]), 1, "the oracle compares one resolved path")
63
93
  path = result["paths"][0]
64
94
  test.assertTrue(path["returned"], path["stop"])
65
- at, expected = unicorn(data, registers, direction)
95
+ outputs = []
96
+ at, expected = unicorn(data, registers, direction, ports, outputs)
66
97
  test.assertIsNotNone(at, "Unicorn did not reach a return")
98
+ written = [(e["port"]["value"], e["width"], e["value"]["value"]) for e in path["events"]
99
+ if e["kind"] == "hardware-boundary" and e["boundary"] == "port-output"]
100
+ test.assertEqual(written, outputs, f"port writes after {code}")
67
101
  compared = 0
68
102
  for name, row in path["registers"].items():
69
103
  if name in expected and row["value"] is not None:
@@ -97,11 +97,12 @@ class EffectOrderTests(unittest.TestCase):
97
97
  # The model invalidates stack memory too; no surviving snapshot value is guessed.
98
98
  self.assertFalse(p["localRestorationWitnesses"])
99
99
 
100
- def test_port_stop_and_path_caps_cannot_prove_absent_later_effects(self):
101
- p = self.paths(report("c7 06 20 00 01 00 ee c7 06 22 00 02 00 c3", "effects"))[0]
100
+ def test_interrupt_stop_and_path_caps_cannot_prove_absent_later_effects(self):
101
+ p = self.paths(report("c7 06 20 00 01 00 cd 10 c7 06 22 00 02 00 c3", "effects"))[0]
102
102
  self.assertFalse(p["returned"])
103
103
  self.assertEqual(p["stop"]["writesBeforeCount"], 1)
104
- self.assertIn("port", p["stop"]["reason"].lower())
104
+ self.assertIn("interrupt", p["stop"]["reason"])
105
+ self.assertEqual(len(p["hardwareBoundaryOrders"]), 1)
105
106
  r = report("85 c0 74 06 c7 06 20 00 01 00 c3", "effects", maxPaths=1)
106
107
  self.assertFalse(r["effectOrdering"]["allPathsRead"])
107
108
  self.assertTrue(r["gaps"])
@@ -109,6 +110,16 @@ class EffectOrderTests(unittest.TestCase):
109
110
  self.assertFalse(self.paths(r)[0]["returned"])
110
111
  self.assertEqual(self.paths(r)[0]["stop"]["writesBeforeCount"], 1)
111
112
 
113
+ def test_port_output_is_a_boundary_event_apart_from_ram_writes(self):
114
+ p = self.paths(report("c7 06 20 00 01 00 ee c7 06 22 00 02 00 c3", "effects"))[0]
115
+ self.assertTrue(p["returned"])
116
+ port = next(e for e in p["timeline"] if e["kind"] == "hardware-boundary")
117
+ self.assertEqual(p["hardwareBoundaryOrders"], [port["order"]])
118
+ self.assertNotIn(port["order"], p["writeOrders"])
119
+ self.assertEqual(len(p["writeOrders"]), 2)
120
+ # Device effects are outside the model, so the path's effects are not complete within it.
121
+ self.assertFalse(p["effectCompleteWithinModel"])
122
+
112
123
 
113
124
  if __name__ == "__main__":
114
125
  unittest.main()
@@ -1,7 +1,10 @@
1
1
  """Unicorn oracle cases per instruction group (ADR 0003). Synthetic machine code only."""
2
2
  import unittest
3
3
 
4
- from oracle import STACK, check, configuration, run_report
4
+ from capstone import CS_ARCH_X86, CS_MODE_16, Cs
5
+
6
+ from oracle import STACK, check, configuration, interrupt, run_report
7
+ from scientific_method_engine.x86.pcode_backend import interrupt_vector
5
8
 
6
9
  DATA = {"ds": 0x3000, "es": 0x4000}
7
10
  SAME = {"ds": 0x4000, "es": 0x4000}
@@ -231,5 +234,55 @@ class StringOperations(unittest.TestCase):
231
234
  resolved=("al", "si", "di"))
232
235
 
233
236
 
237
+ class PortAccess(unittest.TestCase):
238
+ """Port reads take the value the query supplies; Unicorn's hook returns the same value."""
239
+
240
+ def test_in_and_out_with_immediate_and_dx_ports(self):
241
+ check(self, "ba c803 b0 05 ee b8 3412 ef e6 21 e4 60 89 c3 ed 66 ed c3",
242
+ ports={0x60: 0x7f, 0x3c8: 0x1234abcd},
243
+ port_inputs=[{"site": 12, "value": 0x7f, "evidence": "synthetic oracle input"},
244
+ {"site": 16, "value": 0xabcd, "evidence": "synthetic oracle input"},
245
+ {"site": 17, "value": 0x1234abcd, "evidence": "synthetic oracle input"}],
246
+ resolved=("al", "bx", "eax"))
247
+
248
+ def test_string_port_forms_step_si_and_di(self):
249
+ # outsb x2 from DS:0x10, then insw x2 into ES:0x20 and read the words back.
250
+ check(self, "fc be1000 c7040102 ba c803 b90200 f36e bf2000 b90200 f36d 268b1e2000 268b0e2200 c3",
251
+ registers=DATA, ports={0x3c8: 0x5aa5},
252
+ port_inputs=[{"site": 22, "value": 0x5aa5, "evidence": "synthetic oracle input"}],
253
+ resolved=("si", "di", "bx", "cx"))
254
+
255
+ def test_backward_outs_word(self):
256
+ check(self, "fd be1200 c7041122 c744fe3344 ba c803 6f 6f c3", registers=DATA, resolved=("si",))
257
+
258
+
259
+ class Interrupts(unittest.TestCase):
260
+ """The vector the engine reports from p-code is the interrupt Unicorn raises."""
261
+
262
+ def test_interrupt_vectors(self):
263
+ # Unicorn rejects INT1 (F1) as an invalid instruction, so it has no oracle case.
264
+ for code in ("b4 4c cd 21", "cd 10", "cc"):
265
+ with self.subTest(code=code):
266
+ data = bytes.fromhex(code + " c3")
267
+ result = run_report(data, configuration(data, STACK), "trace")
268
+ row, = [e for e in result["paths"][0]["events"] if e["kind"] == "hardware-boundary"]
269
+ self.assertEqual(row["vector"], interrupt(code))
270
+
271
+ def test_into_vector_and_stop(self):
272
+ # INTO raises its vector only when OF is set. The engine does not model that branch, so
273
+ # the path stops at INTO; the vector p-code names must still be the one Unicorn raises.
274
+ overflow, clear = "b0 7f 04 01 ce", "b0 00 04 01 ce"
275
+ self.assertIsNone(interrupt(clear))
276
+ into, = Cs(CS_ARCH_X86, CS_MODE_16).disasm(bytes.fromhex("ce"), 4)
277
+ vector, conditional = interrupt_vector(False, into, 4)
278
+ self.assertTrue(conditional)
279
+ self.assertEqual(vector, interrupt(overflow))
280
+ data = bytes.fromhex(overflow + " c3")
281
+ result = run_report(data, configuration(data, STACK), "trace")
282
+ path, = result["paths"]
283
+ self.assertFalse(path["returned"])
284
+ self.assertEqual(path["stop"], "Unsupported instruction semantics: into")
285
+
286
+
234
287
  if __name__ == "__main__":
235
288
  unittest.main()
@@ -88,6 +88,18 @@ class PEReporterTests(unittest.TestCase):
88
88
  roles = [e['role'] for e in events(r, 'read') if e['role'] and e['role'].startswith('string')]
89
89
  self.assertEqual(sorted(roles), ['string-destination', 'string-source'])
90
90
 
91
+ def test_port_access_reports_its_boundary_and_stops_on_io_privilege(self):
92
+ # mov dx, 0x3c8; out dx, al; ret
93
+ r = report('66 ba c8 03 ee c3')
94
+ path, = r['paths']
95
+ self.assertFalse(path['returned'])
96
+ self.assertIn('I/O privilege', path['stop'])
97
+ row, = events(r, 'hardware-boundary')
98
+ self.assertEqual((row['boundary'], row['port']['value'], row['width']), ('port-output', 0x3c8, 1))
99
+ self.assertEqual(r['hardwareBoundaries'][0]['placement'], 'everyTracedPath')
100
+ with self.assertRaisesRegex(ValueError, 'flat model'):
101
+ report('ec c3', portInputs=[{'site': CODE_RAW, 'value': 1, 'evidence': 'synthetic'}])
102
+
91
103
  def test_pop_addresses_its_destination_after_the_stack_pointer_moves(self):
92
104
  # push 1; push 2; push 3; pop dword [esp+4]; pop eax; pop ebx; ret
93
105
  regs = report('6a 01 6a 02 6a 03 8f 44 24 04 58 5b c3')['paths'][0]['registers']
@@ -749,6 +749,242 @@ class CallOrderTests(unittest.TestCase):
749
749
  self.assertIsNone(r["callers"][0]["calls"][0]["cleanup"]["argumentBytes"])
750
750
 
751
751
 
752
+ class HardwareBoundaryTests(unittest.TestCase):
753
+ """Port accesses and interrupts are hardware-boundary events, kept apart from RAM accesses."""
754
+
755
+ def boundaries(self, result, kind=None):
756
+ return [e for e in events(result, "hardware-boundary") if kind is None or e["boundary"] == kind]
757
+
758
+ def test_port_output_reports_port_provenance_width_and_value(self):
759
+ # mov dx, 0x3c8; mov al, 5; out dx, al; out 0x21, al; mov dx, [0x200]; out dx, ax; ret
760
+ r = report("ba c8 03 b0 05 ee e6 21 8b 16 00 02 ef c3", registers={"ds": 0x2000})
761
+ self.assertTrue(r["completeWithinModel"])
762
+ rows = self.boundaries(r, "port-output")
763
+ self.assertEqual([(e["port"]["value"], e["portKnown"], e["width"]) for e in rows],
764
+ [(0x3c8, True, 1), (0x21, True, 1), (None, False, 2)])
765
+ self.assertEqual(rows[0]["value"]["value"], 5)
766
+ self.assertIn(8, rows[2]["port"]["producers"])
767
+ self.assertIn("rendered output are not modeled", rows[0]["interpretation"])
768
+ # The port writes never become RAM writes.
769
+ self.assertFalse(events(r, "write"))
770
+ self.assertEqual([e["site"] for e in events(r, "read")], [8])
771
+
772
+ def test_port_input_is_unknown_unless_the_query_supplies_it_as_an_assumption(self):
773
+ code = "e4 60 3c 01 74 03 b3 01 c3 b3 02 c3"
774
+ r = report(code)
775
+ read = self.boundaries(r, "port-input")
776
+ self.assertEqual({e["valueSource"] for e in read}, {"unknown"})
777
+ self.assertTrue(all(e["value"]["value"] is None for e in read))
778
+ self.assertEqual(len(r["paths"]), 2)
779
+ self.assertTrue(all(not p["conditionalModels"] for p in r["paths"]))
780
+ supplied = report(code, portInputs=[{"site": 0, "value": 1, "evidence": "synthetic device reply"}])
781
+ self.assertEqual(len(supplied["paths"]), 1)
782
+ path = supplied["paths"][0]
783
+ row = self.boundaries(supplied, "port-input")[0]
784
+ self.assertEqual((row["value"]["value"], row["valueSource"], row["evidence"]), (1, "query assumption", "synthetic device reply"))
785
+ self.assertEqual(path["conditionalModels"], [{"site": 0, "evidence": "synthetic device reply",
786
+ "assumption": "port input value supplied by the query; device state unconfirmed"}])
787
+ self.assertEqual(path["registers"]["bl"]["value"], 2)
788
+
789
+ def test_uses_reads_past_a_port_access(self):
790
+ data = bytes.fromhex("ba c8 03 ee a1 00 02 c3")
791
+ r = run_report(data, configuration(data, query={"offset": 0x200, "width": 2}, controls=[4]), "uses")
792
+ self.assertEqual([e["site"] for e in r["matches"]], [4])
793
+
794
+ def test_two_reads_of_one_port_are_distinct_unknowns(self):
795
+ r = report("e4 60 88 c3 e4 60 c3")
796
+ first, second = self.boundaries(r, "port-input")
797
+ self.assertNotEqual(first["value"]["expression"], second["value"]["expression"])
798
+
799
+ def test_port_inputs_are_validated_against_the_decoded_instruction(self):
800
+ code = "e4 60 ed 6c ee c3"
801
+ good = [{"site": 0, "value": 255, "evidence": "synthetic"}, {"site": 2, "value": 0xffff, "evidence": "synthetic"},
802
+ {"site": 3, "value": 255, "evidence": "synthetic"}]
803
+ self.assertTrue(report(code, portInputs=good, registers={"es": 0x2000}, flags={"direction": 0})["paths"])
804
+ for rows, message in (([{"site": 4, "value": 1, "evidence": "synthetic"}], "IN or INS"),
805
+ ([{"site": 0, "value": 256, "evidence": "synthetic"}], "port input value"),
806
+ ([{"site": 2, "value": 0x10000, "evidence": "synthetic"}], "port input value"),
807
+ ([{"site": 0, "value": 1}], "evidence"),
808
+ ([{"site": 0, "value": 1, "evidence": "a"}, {"site": 0, "value": 2, "evidence": "b"}], "unique"),
809
+ ([{"site": 0, "value": 1, "evidence": "synthetic"}] * 65, "at most 64"),
810
+ ({"site": 0}, "list")):
811
+ with self.subTest(message=message):
812
+ with self.assertRaisesRegex(ValueError, message):
813
+ report(code, portInputs=rows)
814
+
815
+ def test_placement_separates_every_path_conditional_and_unresolved(self):
816
+ # out 0x20, al on every path; out 0x21, al only when AL is zero.
817
+ c = Code().emit("e6 20 84 c0").branch("74", "zero").emit("c3").label("zero").emit("e6 21 c3")
818
+ r = report(c)
819
+ rows = {row["site"]: row for row in r["hardwareBoundaries"]}
820
+ self.assertEqual(rows[0]["placement"], "everyTracedPath")
821
+ self.assertEqual(rows[0]["paths"], [0, 1])
822
+ zero = rows[c.labels["zero"]]
823
+ self.assertEqual(zero["placement"], "conditional")
824
+ self.assertEqual(len(zero["pathsWithout"]["returned"]), 1)
825
+ # A path dropped at the limit, or one stopped before the site, leaves placement unresolved.
826
+ capped = report(c, maxPaths=1)
827
+ self.assertTrue(capped["gaps"])
828
+ self.assertTrue(all(row["placement"] != "everyTracedPath" for row in capped["hardwareBoundaries"]))
829
+ c = Code().emit("84 c0").branch("74", "stop").emit("e6 20 c3").label("stop").emit("0f 0b")
830
+ stopped = report(c)
831
+ self.assertEqual(stopped["hardwareBoundaries"][0]["placement"], "unresolved")
832
+ self.assertEqual(len(stopped["hardwareBoundaries"][0]["pathsWithout"]["stopped"]), 1)
833
+
834
+ def test_rep_outs_reads_ram_and_writes_ports_as_separate_events(self):
835
+ # cld; mov cx, 2; mov dx, 0x3c9; mov si, 0x100; rep outsb; ret
836
+ code = "fc b9 02 00 ba c9 03 be 00 01 f3 6e c3"
837
+ r = report(code, registers={"ds": 0x2000})
838
+ path = r["paths"][0]
839
+ self.assertTrue(path["returned"])
840
+ sources = [e for e in path["events"] if e["kind"] == "read" and e["role"] == "string-source"]
841
+ ports = self.boundaries(r, "port-output")
842
+ self.assertEqual([e["offset"]["value"] for e in sources], [0x100, 0x101])
843
+ self.assertEqual([e["port"]["value"] for e in ports], [0x3c9, 0x3c9])
844
+ # Each port write carries the byte read from RAM, and is not itself a RAM write.
845
+ self.assertEqual([e["value"]["expression"] for e in ports], [e["value"]["expression"] for e in sources])
846
+ self.assertFalse(events(r, "write"))
847
+ self.assertEqual(path["registers"]["si"]["value"], 0x102)
848
+ self.assertEqual(path["registers"]["cx"]["value"], 0)
849
+ # The memory report keeps RAM only; effects keeps both.
850
+ self.assertFalse(events(report(code, "memory", registers={"ds": 0x2000}), "hardware-boundary"))
851
+ self.assertEqual(len(events(report(code, "effects", registers={"ds": 0x2000}), "hardware-boundary")), 2)
852
+
853
+ def test_rep_ins_writes_ram_from_unknown_or_supplied_port_values(self):
854
+ # cld; mov cx, 2; mov dx, 0x60; mov di, 0x100; rep insb; ret
855
+ code = "fc b9 02 00 ba 60 00 bf 00 01 f3 6c c3"
856
+ r = report(code, registers={"es": 0x2000})
857
+ writes = events(r, "write")
858
+ self.assertEqual([(e["offset"]["value"], e["effectiveSegmentRegister"], e["role"]) for e in writes],
859
+ [(0x100, "es", "string-destination"), (0x101, "es", "string-destination")])
860
+ self.assertTrue(all(e["value"]["value"] is None for e in writes))
861
+ supplied = report(code, registers={"es": 0x2000}, portInputs=[{"site": 10, "value": 9, "evidence": "synthetic"}])
862
+ self.assertEqual([e["value"]["value"] for e in events(supplied, "write")], [9, 9])
863
+ self.assertEqual(len(supplied["paths"][0]["conditionalModels"]), 1)
864
+
865
+ def test_string_port_forms_with_unknown_direction_or_count_follow_string_rules(self):
866
+ r = report("b9 02 00 f3 6e c3", registers={"ds": 0x2000})
867
+ self.assertEqual(len(r["paths"]), 2)
868
+ self.assertTrue(events(r, "flag-assumption"))
869
+ r = report("f3 6e c3", flags={"direction": 0})
870
+ self.assertIn("count unresolved", r["paths"][0]["stop"])
871
+ r = report("fc b9 05 00 f3 6e c3", stringIterations=4)
872
+ self.assertIn("budget exhausted", r["paths"][0]["stop"])
873
+ self.assertFalse(self.boundaries(r))
874
+
875
+ def test_interrupt_is_a_boundary_event_that_stops_the_path(self):
876
+ r = report("c7 06 00 02 01 00 cd 21 c3", registers={"ds": 0x2000})
877
+ path = r["paths"][0]
878
+ self.assertFalse(path["returned"])
879
+ self.assertEqual(path["stop"], "interrupt handler is not modeled; later effects are not read")
880
+ row = self.boundaries(r, "interrupt")[0]
881
+ self.assertEqual((row["site"], row["vector"]), (6, 0x21))
882
+ self.assertEqual(r["hardwareBoundaries"][0]["placement"], "everyTracedPath")
883
+ self.assertEqual(self.boundaries(report("cc"), "interrupt")[0]["vector"], 3)
884
+ # INTO interrupts only when OF is set; that condition is not modeled.
885
+ into = report("ce c3")
886
+ self.assertEqual(into["paths"][0]["stop"], "Unsupported instruction semantics: into")
887
+ self.assertFalse(self.boundaries(into))
888
+
889
+ def test_bounds_lists_each_hardware_boundary_statically(self):
890
+ r = report("e4 60 ed ee e6 21 f3 6e f2 6d 6d cd 10 ce c3", "bounds")
891
+ self.assertTrue(r["complete"])
892
+ self.assertEqual(r["hardwareBoundaries"], [
893
+ {"site": 0, "boundary": "port-input", "mnemonic": "in", "port": {"source": "immediate", "value": 0x60},
894
+ "width": 1, "stringForm": False, "repeated": False},
895
+ {"site": 2, "boundary": "port-input", "mnemonic": "in", "port": {"source": "register", "register": "dx"},
896
+ "width": 2, "stringForm": False, "repeated": False},
897
+ {"site": 3, "boundary": "port-output", "mnemonic": "out", "port": {"source": "register", "register": "dx"},
898
+ "width": 1, "stringForm": False, "repeated": False},
899
+ {"site": 4, "boundary": "port-output", "mnemonic": "out", "port": {"source": "immediate", "value": 0x21},
900
+ "width": 1, "stringForm": False, "repeated": False},
901
+ {"site": 6, "boundary": "port-output", "mnemonic": "outsb", "port": {"source": "register", "register": "dx"},
902
+ "width": 1, "stringForm": True, "repeated": True},
903
+ {"site": 8, "boundary": "port-input", "mnemonic": "insw", "port": {"source": "register", "register": "dx"},
904
+ "width": 2, "stringForm": True, "repeated": True},
905
+ {"site": 10, "boundary": "port-input", "mnemonic": "insw", "port": {"source": "register", "register": "dx"},
906
+ "width": 2, "stringForm": True, "repeated": False},
907
+ {"site": 11, "boundary": "interrupt", "mnemonic": "int", "vector": 0x10, "conditional": False},
908
+ {"site": 13, "boundary": "interrupt", "mnemonic": "into", "vector": 4, "conditional": True}])
909
+ self.assertEqual(len(r["assumedContinuations"]), 9)
910
+
911
+
912
+ class EffectiveSegmentTests(unittest.TestCase):
913
+ """Frame-derived offsets keep their own provenance; the addressing register picks the segment."""
914
+
915
+ FRAME = "55 89 e5 83 ec 08 " # push bp; mov bp, sp; sub sp, 8
916
+
917
+ def access(self, result, site, kind="read"):
918
+ return next(e for e in events(result, kind) if e["site"] == site)
919
+
920
+ def test_bp_offset_moved_or_added_into_bx_uses_ds(self):
921
+ for setup in ("8d 5e fc", "89 eb 83 c3 fc", "bb fc ff 01 eb"): # lea; mov+add; mov+add bp
922
+ with self.subTest(setup=setup):
923
+ code = self.FRAME + setup + " 8b 07 c9 c3"
924
+ site = len(bytes.fromhex(self.FRAME + setup))
925
+ r = report(code)
926
+ read = self.access(r, site)
927
+ self.assertEqual(read["effectiveSegmentRegister"], "ds")
928
+ self.assertEqual(read["segment"]["expression"], ("unknown", "initial:ds"))
929
+ # The offset keeps its entry-SP provenance, separate from the DS segment that addresses it.
930
+ self.assertEqual(read["offset"]["expression"], ("offset", ("unknown", "entry:sp"), 0xfffa))
931
+ self.assertEqual(read["interval"]["segment"], ("unknown", "initial:ds"))
932
+ self.assertNotIn("argument", read)
933
+
934
+ def test_bp_offset_indexed_through_bx_uses_ds(self):
935
+ code = self.FRAME + "89 eb 01 f3 8b 07 c9 c3" # mov bx, bp; add bx, si; mov ax, [bx]
936
+ read = self.access(report(code), len(bytes.fromhex(self.FRAME)) + 4)
937
+ self.assertEqual(read["effectiveSegmentRegister"], "ds")
938
+ self.assertIn("entry:sp", repr(read["offset"]["expression"]))
939
+ self.assertIn("initial:esi", repr(read["offset"]["expression"]))
940
+
941
+ def test_segment_override_and_bp_base_use_ss(self):
942
+ code = self.FRAME + "8d 5e fc 36 8b 07 8b 56 fc c9 c3"
943
+ r = report(code)
944
+ start = len(bytes.fromhex(self.FRAME)) + 3
945
+ self.assertEqual(self.access(r, start)["effectiveSegmentRegister"], "ss")
946
+ self.assertEqual(self.access(r, start + 3)["effectiveSegmentRegister"], "ss")
947
+
948
+ def test_ds_and_frame_accesses_alias_only_when_segment_equality_is_established(self):
949
+ # Store through DS:[BX] with BX = BP - 4 (by LEA, or as -4 + BP), then read SS:[BP - 4].
950
+ cases = (({}, None), ({"ds": 0x2000, "ss": 0x3000}, None), ({"ds": 0x2000, "ss": 0x2000}, 0x1234))
951
+ for setup in ("8d 5e fc", "bb fc ff 01 eb"):
952
+ code = self.FRAME + setup + " c7 07 34 12 8b 46 fc c9 c3"
953
+ read_site = len(bytes.fromhex(self.FRAME + setup)) + 4
954
+ for registers, expected in cases:
955
+ with self.subTest(setup=setup, registers=registers):
956
+ r = report(code, registers=registers)
957
+ self.assertEqual(self.access(r, read_site)["value"]["value"], expected)
958
+ read_site = len(bytes.fromhex(self.FRAME)) + 7
959
+ # Instructions that copy SS into DS establish the equality on the path that runs them.
960
+ r = report(self.FRAME + "16 1f 8d 5e fc c7 07 34 12 8b 46 fc c9 c3")
961
+ self.assertEqual(self.access(r, read_site + 2)["value"]["value"], 0x1234)
962
+
963
+ def test_ds_store_over_unknown_segments_invalidates_frame_bytes_instead_of_merging(self):
964
+ # Write SS:[BP - 4], then DS:[BX] at the same offset, then read SS:[BP - 4] back.
965
+ code = self.FRAME + "c7 46 fc 11 11 8d 5e fc c7 07 22 22 8b 46 fc c9 c3"
966
+ r = report(code)
967
+ store = self.access(r, len(bytes.fromhex(self.FRAME)) + 8, "write")
968
+ self.assertEqual(store["effectiveSegmentRegister"], "ds")
969
+ self.assertGreater(store["uncertainAliasesInvalidated"], 0)
970
+ self.assertIsNone(self.access(r, len(bytes.fromhex(self.FRAME)) + 12)["value"]["value"])
971
+
972
+ def test_callee_segment_changes_and_modeled_calls_stay_explicit(self):
973
+ # The callee loads DS; the caller's later [bx] read uses the DS the callee left.
974
+ c = Code().emit("bb 00 01").branch("e8", "callee").label("after").emit("8b 07 c3")
975
+ c.label("callee").emit("b8 00 50 8e d8 c3")
976
+ r = report(c)
977
+ read = self.access(r, c.labels["after"])
978
+ self.assertEqual(read["segment"]["value"], 0x5000)
979
+ self.assertIn(c.labels["callee"] + 3, read["segment"]["producers"])
980
+ modeled = report(c, callModels=[{"site": 3, "evidence": "synthetic service", "cases": [{}]}])
981
+ read = self.access(modeled, c.labels["after"])
982
+ self.assertEqual(read["segment"]["expression"], ("unknown", "modeled-call:3:ds"))
983
+ preserved = report(c, registers={"ds": 0x2000},
984
+ callModels=[{"site": 3, "evidence": "synthetic service", "preserves": ["ds"], "cases": [{}]}])
985
+ self.assertEqual(self.access(preserved, c.labels["after"])["segment"]["value"], 0x2000)
986
+
987
+
752
988
  class ReporterTests(unittest.TestCase):
753
989
  def test_register_parts_preserve_neighbor(self):
754
990
  r = report("b8 34 12 b0 00 c3")
@@ -871,9 +1107,12 @@ class ReporterTests(unittest.TestCase):
871
1107
  self.assertTrue(r["gaps"])
872
1108
  self.assertFalse(r["completeWithinModel"])
873
1109
 
874
- def test_hardware_is_a_boundary(self):
875
- for code in ("cd 21 c3", "ee c3", "f3 a5 c3"):
1110
+ def test_interrupts_and_unbounded_strings_stop_while_ports_continue_as_boundary_events(self):
1111
+ for code in ("cd 21 c3", "f3 a5 c3"):
876
1112
  self.assertFalse(report(code)["completeWithinModel"])
1113
+ r = report("ee c3")
1114
+ self.assertTrue(r["completeWithinModel"])
1115
+ self.assertEqual([e["boundary"] for e in events(r, "hardware-boundary")], ["port-output"])
877
1116
 
878
1117
  def test_uses_follow_entries_across_intervening_data(self):
879
1118
  data = bytes.fromhex("a1 00 02 c3 ff ff a1 00 02 c3")
@@ -1211,14 +1450,15 @@ class ReporterTests(unittest.TestCase):
1211
1450
  self.assertEqual(alone["verdict"], "one established entry reaches this site")
1212
1451
 
1213
1452
  def test_walk_reads_prefixed_returns_ports_and_jumps(self):
1214
- # "repz ret" and "rep insb" end the walk, "bnd jmp" is followed like a plain jmp, and int1 is a boundary.
1453
+ # "repz ret" ends the walk, "rep insb" continues to the next instruction, "bnd jmp" is followed
1454
+ # like a plain jmp, and interrupts are boundaries.
1215
1455
  def run(code):
1216
1456
  data = bytes.fromhex(code)
1217
1457
  return walk(Image(data, configuration(data)), [0])
1218
1458
  seen, gaps, _, _, _ = run("f3 c3 cc")
1219
1459
  self.assertEqual((sorted(seen), gaps), ([0], []))
1220
- _, gaps, _, _, _ = run("f3 6c cc")
1221
- self.assertEqual(gaps, [{"site": 0, "reason": "hardware or interrupt boundary"}])
1460
+ seen, gaps, _, _, _ = run("f3 6c cc")
1461
+ self.assertEqual((sorted(seen), gaps), ([0, 2], [{"site": 2, "reason": "hardware or interrupt boundary"}]))
1222
1462
  seen, gaps, edges, _, _ = run("f2 e9 01 00 cc c3")
1223
1463
  self.assertEqual((sorted(seen), gaps), ([0, 5], []))
1224
1464
  self.assertEqual((edges[0]["kind"], edges[0]["target"]), ("jmp", 5))