scientific-method-engine 9.0.0__tar.gz → 9.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 (71) hide show
  1. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/PKG-INFO +3 -2
  2. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/README.md +2 -1
  3. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/cli.py +1 -0
  5. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/relational.py +84 -7
  6. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/trace.py +7 -2
  7. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_interrupt_models.py +51 -3
  8. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_relational_controls.py +105 -0
  9. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/.gitignore +0 -0
  10. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/LICENSE +0 -0
  11. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/__init__.py +0 -0
  12. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/__main__.py +0 -0
  13. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  14. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  15. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  16. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  17. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  18. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  19. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  20. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  21. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  22. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  23. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  24. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  25. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  26. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  27. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  28. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  29. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  30. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  31. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  32. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  33. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  34. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  35. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  36. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  37. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  38. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  39. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  40. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  41. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  42. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  43. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  44. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  45. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  46. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  47. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  48. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  49. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/image.py +0 -0
  50. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/loops.py +0 -0
  51. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/machine.py +0 -0
  52. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  53. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  54. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  55. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
  56. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/reports.py +0 -0
  57. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  58. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/src/scientific_method_engine/x86/values.py +0 -0
  59. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/oracle.py +0 -0
  60. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_continuation_budget.py +0 -0
  61. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_dispatch.py +0 -0
  62. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_effect_order.py +0 -0
  63. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_entry_frame.py +0 -0
  64. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_loops.py +0 -0
  65. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_memory_scopes.py +0 -0
  66. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_nested_frame_request.py +0 -0
  67. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_oracle.py +0 -0
  68. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_pe.py +0 -0
  69. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_successor_rule.py +0 -0
  70. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_table_continuations.py +0 -0
  71. {scientific_method_engine-9.0.0 → scientific_method_engine-9.1.0}/tests/test_x86.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 9.0.0
3
+ Version: 9.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
@@ -169,7 +169,8 @@ The trace-family commands (`trace`, `arguments`, `effects`, `returns`, `guards`,
169
169
  writer, containment, value relation and value origin) evaluated on every bounded path. A violated
170
170
  control fails the report. A control left undecided by a stop, a limit or an unread call is
171
171
  reported as `undecided` and never counts as held. Access reports also give each byte's
172
- `writeOrder`, or why it has no modeled value. See the
172
+ `writeOrder`, or why it has no modeled value. A last-writer control with an `address` asks the
173
+ same of memory the program never reads back, at a checkpoint. See the
173
174
  [controls contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#relational-controls).
174
175
 
175
176
  A trace-family query whose entry lies inside a function body names the function's entry in
@@ -153,7 +153,8 @@ The trace-family commands (`trace`, `arguments`, `effects`, `returns`, `guards`,
153
153
  writer, containment, value relation and value origin) evaluated on every bounded path. A violated
154
154
  control fails the report. A control left undecided by a stop, a limit or an unread call is
155
155
  reported as `undecided` and never counts as held. Access reports also give each byte's
156
- `writeOrder`, or why it has no modeled value. See the
156
+ `writeOrder`, or why it has no modeled value. A last-writer control with an `address` asks the
157
+ same of memory the program never reads back, at a checkpoint. See the
157
158
  [controls contract](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#relational-controls).
158
159
 
159
160
  A trace-family query whose entry lies inside a function body names the function's entry in
@@ -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 = "9.0.0"
8
+ version = "9.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"
@@ -23,6 +23,7 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
23
23
  "or continues at another address than the next instruction (ghidraFallsThroughElsewhere).\n"
24
24
  "trace, arguments, effects, returns, guards, memory and allocation check relationalControls:\n"
25
25
  "a violated control fails the report; an undecided one is reported and never counts as held.\n"
26
+ "A lastWriter control with an address inspects that memory at its checkpoint anchors without a read.\n"
26
27
  "entryFrame {from} starts an entry inside the function at from, in the frame a trace from there observed.\n"
27
28
  "Declared table continuations are separate conditional paths that spend continuationBudget\n"
28
29
  "(paths, totalSteps, maxSteps, visitLimit, stringIterations); ordinary computed transfers remain stopped.\n"
@@ -7,7 +7,9 @@ whose paths were not all read (a stop, a limit, a dropped path) is undecided, ne
7
7
  from bisect import bisect_right
8
8
  from math import inf
9
9
  from .image import integer
10
- from .machine import ALIASES, NO_WRITE, State
10
+ from .machine import ALIASES, NO_WRITE, State, StopPath
11
+ from .memory_scopes import SEGMENTS
12
+ from .values import const, op
11
13
 
12
14
  KINDS = ("reach", "order", "lastWriter", "containment", "relation", "origin")
13
15
  OPERATORS = ("eq", "ne", "lt", "le", "gt", "ge")
@@ -91,6 +93,69 @@ def _operand(operand, image, name, budget):
91
93
  _term(operand, image, name)
92
94
 
93
95
 
96
+ def _address(control, image):
97
+ """Check a lastWriter address: a segment register, an optional base register, a displacement and a width."""
98
+ address, name = control["address"], control["name"]
99
+ if not isinstance(address, dict) or set(address) - {"segment", "base", "displacement", "width"} or "segment" not in address:
100
+ raise ValueError(f"Relational control {name} address names segment, and optionally base, displacement and width")
101
+ if address["segment"] not in SEGMENTS:
102
+ raise ValueError(f"Relational control {name} address segment must be a segment register")
103
+ if "base" in address:
104
+ base = address["base"]
105
+ if (not isinstance(base, str) or base not in ALIASES or ALIASES[base][0] in SEGMENTS or ALIASES[base][1] != 0
106
+ or ALIASES[base][2] != image.bits):
107
+ raise ValueError(f"Relational control {name} address base must be a {image.bits}-bit general register")
108
+ # Signed or unsigned in the address width; a wider value would silently name another offset.
109
+ displacement = address.get("displacement", 0)
110
+ if type(displacement) is not int or not -(1 << (image.bits - 1)) <= displacement < 1 << image.bits:
111
+ raise ValueError(f"Relational control {name} address displacement must be a {image.bits}-bit integer")
112
+ integer(address.get("width"), 1, 32, "lastWriter address width")
113
+
114
+
115
+ def checkpoint_anchors(config):
116
+ """The sites of every relational control's checkpoint anchors, which the trace adds to checkpoints.
117
+
118
+ Reads controls that validate_controls accepted.
119
+ """
120
+ sites = set()
121
+ for control in config.get("relationalControls", []):
122
+ anchors = control["at"] if isinstance(control["at"], list) else [control["at"]]
123
+ sites.update(a["site"] for a in anchors if a.get("event") == "checkpoint")
124
+ return sites
125
+
126
+
127
+ def memory_probes(config):
128
+ """The lastWriter addresses to inspect at each checkpoint site: {site: [(control name, address)]}.
129
+
130
+ Reads controls that validate_controls accepted.
131
+ """
132
+ probes = {}
133
+ for control in config.get("relationalControls", []):
134
+ if control.get("kind") == "lastWriter" and "address" in control:
135
+ anchors = control["at"] if isinstance(control["at"], list) else [control["at"]]
136
+ for site in {a["site"] for a in anchors}:
137
+ probes.setdefault(site, []).append((control["name"], control["address"]))
138
+ return probes
139
+
140
+
141
+ def probe_memory(state, name, address):
142
+ """What the model holds at a lastWriter address before the instruction runs, without a read event.
143
+
144
+ The row carries ``byteProducers`` as a read of those bytes would report them, or ``unresolved``
145
+ when the address cannot be inspected.
146
+ """
147
+ offset = const(address.get("displacement", 0), state.bits)
148
+ if "base" in address:
149
+ offset = op("add", state.reg(address["base"]), offset)
150
+ segment = state.segment(address["segment"])
151
+ row = {"control": name, "segment": segment.report(), "offset": offset.report(), "width": address["width"]}
152
+ try:
153
+ keys = state.keys(segment, offset, address["width"])[3]
154
+ except StopPath as error:
155
+ return {**row, "unresolved": str(error)}
156
+ return {**row, "byteProducers": [state.byte_writer(i, key) for i, key in enumerate(keys)]}
157
+
158
+
94
159
  def validate_controls(config, image):
95
160
  """Check every relational control before tracing; return them unchanged."""
96
161
  controls = config.get("relationalControls", [])
@@ -145,11 +210,15 @@ def validate_controls(config, image):
145
210
  if not isinstance(same, dict) or set(same) != {"before", "at"} or not all(isinstance(v, str) and v for v in same.values()):
146
211
  raise ValueError(f"Relational control {name} sameValue names a before field and an at field")
147
212
  elif kind == "lastWriter":
148
- allowed |= {"writers", "byteWriters"}
149
- _anchors(control, image, events=("read",))
213
+ allowed |= {"writers", "byteWriters", "address"}
214
+ _anchors(control, image, events=("checkpoint",) if "address" in control else ("read",))
215
+ if "address" in control:
216
+ _address(control, image)
150
217
  lists = [control["writers"]] if "writers" in control else control.get("byteWriters")
151
218
  if ("writers" in control) == ("byteWriters" in control) or not isinstance(lists, list) or not 1 <= len(lists) <= 32:
152
219
  raise ValueError(f"Relational control {name} needs writers or byteWriters")
220
+ if "address" in control and "byteWriters" in control and len(lists) != control["address"]["width"]:
221
+ raise ValueError(f"Relational control {name} byteWriters lists {len(lists)} bytes; its address has {control['address']['width']}")
153
222
  for writers in lists:
154
223
  if not isinstance(writers, list) or not 1 <= len(writers) <= 64:
155
224
  raise ValueError(f"Relational control {name} writer lists hold 1..64 entries")
@@ -542,11 +611,17 @@ def _occurrence(control, path, anchor, image):
542
611
  verdicts.append(verdict)
543
612
  return _worst(verdicts), detail
544
613
  if kind == "lastWriter":
545
- lists = control.get("byteWriters") or [control["writers"]] * anchor["width"]
546
- if len(lists) != anchor["width"]:
547
- raise ValueError(f"Relational control {control['name']} byteWriters lists {len(lists)} bytes; the read at {anchor['site']} has {anchor['width']}")
614
+ accessed = anchor
615
+ if "address" in control:
616
+ accessed = next(p for p in anchor["memoryProbes"] if p["control"] == control["name"])
617
+ if "unresolved" in accessed:
618
+ return "undecided", {"reason": f"the address cannot be inspected here: {accessed['unresolved']}",
619
+ "address": {k: accessed[k] for k in ("segment", "offset", "width")}}
620
+ lists = control.get("byteWriters") or [control["writers"]] * accessed["width"]
621
+ if len(lists) != accessed["width"]:
622
+ raise ValueError(f"Relational control {control['name']} byteWriters lists {len(lists)} bytes; the access at {anchor['site']} has {accessed['width']}")
548
623
  rows, verdicts = [], []
549
- for row, allowed in zip(anchor["byteProducers"], lists):
624
+ for row, allowed in zip(accessed["byteProducers"], lists):
550
625
  if row.get("writeOrder") is not None:
551
626
  writer = events[row["writeOrder"]]
552
627
  verdict = "held" if writer["site"] in allowed else "violated"
@@ -560,6 +635,8 @@ def _occurrence(control, path, anchor, image):
560
635
  verdicts.append(verdict)
561
636
  via = path.frame_branch[order]
562
637
  detail = {"bytes": rows, "via": via and {"site": via["site"], "taken": via["taken"], "order": via["order"]}}
638
+ if accessed is not anchor:
639
+ detail["address"] = {k: accessed[k] for k in ("segment", "offset", "width")}
563
640
  wrong = [r for r in rows if r["verdict"] == "violated"]
564
641
  if wrong:
565
642
  detail["reason"] = "; ".join(f"byte {r['index']} was written at site {r['writer']['site']}, not a listed writer" if r["writer"]
@@ -11,6 +11,7 @@ from .result_flow import validate_contracts, result_contracts
11
11
  from .loops import LoopTracker
12
12
  from .memory_scopes import validate_scopes, capture_scopes, retain_scopes, scope_history
13
13
  from .pcode_backend import interrupt_vector
14
+ from .relational import checkpoint_anchors, memory_probes, probe_memory
14
15
 
15
16
  def call_target(image, site, ins):
16
17
  if ins.mnemonic in ("lcall", "ljmp"):
@@ -499,7 +500,10 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
499
500
  total_string_steps = 0
500
501
  string_limit = budget_input(config, "stringIterations")
501
502
  total_limit = budget_input(config, "totalSteps")
502
- checkpoints = set(config.get("checkpoints", []))
503
+ # A control anchored at a checkpoint gets that checkpoint; a lastWriter control with an address
504
+ # inspects it there.
505
+ probes = memory_probes(config)
506
+ checkpoints = set(config.get("checkpoints", [])) | checkpoint_anchors(config)
503
507
  # How often one path may pass the same instruction; a loop with a known bound needs it raised.
504
508
  visit_limit = budget_input(config, "visitLimit")
505
509
  # An unset field takes the value of the matching ordinary input.
@@ -732,7 +736,8 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
732
736
  elif state.visits[at] > visit_limit:
733
737
  raise StopPath(f"instruction repeated more than {visit_limit} times; raise visitLimit or read the loop's bound")
734
738
  if at in checkpoints:
735
- state.event("checkpoint", registers=snapshot(state))
739
+ state.event("checkpoint", registers=snapshot(state),
740
+ **({"memoryProbes": [probe_memory(state, n, a) for n, a in probes[at]]} if at in probes else {}))
736
741
  m, following = ins.mnemonic, at + ins.size
737
742
  is_string = string_instruction(ins)
738
743
  if (0xf2 in ins.prefix or 0xf3 in ins.prefix) and not is_string:
@@ -19,14 +19,15 @@ def verdict(result, name):
19
19
  return next(c for c in result["relationalControls"]["controls"] if c["name"] == name)
20
20
 
21
21
 
22
- def wrapper_case(test="a8 01"):
22
+ def wrapper_case(test="a8 01", read=True):
23
23
  """A caller passes one far scratch pointer twice to a wrapper around INT 33h.
24
24
 
25
25
  The wrapper stores CX then DX through the two pointers and copies BX to AX; the caller reads
26
- the scratch word into CX and tests bit zero of AL (``test``), or of CL to test the scratch word.
26
+ the scratch word into CX (unless ``read`` is false) and tests bit zero of AL (``test``), or of
27
+ CL to test the scratch word.
27
28
  """
28
29
  c = (Code().emit("1e b8 40 00 50 1e 50").branch("e8", "wrapper").emit("83 c4 08")
29
- .label("scratch").emit("8b 0e 40 00").label("test").emit(test).branch("74", "zero").emit("c3")
30
+ .label("scratch").emit("8b 0e 40 00" if read else "").label("test").emit(test).branch("74", "zero").emit("c3")
30
31
  .label("zero").emit("c3")
31
32
  .label("wrapper").emit("55 89 e5").label("int").emit("cd 33")
32
33
  .emit("c4 7e 04").label("first").emit("26 89 0d").emit("c4 7e 08").label("second").emit("26 89 15")
@@ -200,6 +201,53 @@ class InterruptModelTests(unittest.TestCase):
200
201
  self.assertEqual(verdict(r, "later store")["verdict"], "undecided")
201
202
  self.assertEqual(verdict(r, "predicate")["verdict"], "undecided")
202
203
 
204
+ def test_a_caller_that_never_reads_the_scratch_word_names_its_last_writer_at_a_checkpoint(self):
205
+ c, service = wrapper_case(read=False)
206
+ address = {"segment": "ds", "displacement": 0x40, "width": 2}
207
+
208
+ def later(writer="second"):
209
+ return control("later store", "lastWriter", at={"site": c.labels["test"], "event": "checkpoint"},
210
+ address=address, writers=[c.labels[writer]])
211
+ r = report(c, "effects", registers=FRAME, callModels=[service], relationalControls=[later(), self.wrapper_controls(c)[1]])
212
+ self.assertTrue(r["relationalControls"]["allHeld"])
213
+ self.assertFalse([e for e in r["paths"][0]["events"] if e["kind"] == "read" and e["offset"].get("value") == 0x40])
214
+ with self.assertRaisesRegex(ValueError, "later store violated"):
215
+ report(c, registers=FRAME, callModels=[service], relationalControls=[later("first")])
216
+ # Without the frame scope the path stops in the wrapper and never reaches the checkpoint.
217
+ unscoped = {k: v for k, v in service.items() if k != "preservesMemory"}
218
+ r = report(c, registers=FRAME, callModels=[unscoped], relationalControls=[later()])
219
+ self.assertEqual(verdict(r, "later store")["verdict"], "undecided")
220
+
221
+ def test_a_query_inside_the_callers_body_returns_with_the_caller_in_entry_frame(self):
222
+ # The caller passes the far address of its own frame word twice and never reads it back.
223
+ c = (Code().emit("55 89 e5 83 ec 02").label("pushes").emit("16 8d 46 fe 50 16 50").branch("e8", "wrapper")
224
+ .emit("83 c4 08").label("test").emit("a8 01").branch("74", "zero").emit("89 ec 5d c3")
225
+ .label("zero").emit("89 ec 5d c3")
226
+ .label("wrapper").emit("55 89 e5").label("int").emit("cd 33")
227
+ .emit("c4 7e 04").label("first").emit("26 89 0d").emit("c4 7e 08").label("second").emit("26 89 15")
228
+ .emit("89 d8 5d c3"))
229
+ frame = {"segment": "ss", "base": "bp", "bytes": 12, "evidence": "synthetic saved BP, return word and four argument words"}
230
+ service = model(c.labels["int"], [{"registers": {"cx": 5, "dx": 7}}], preserves=["ds", "ss", "ebp"],
231
+ preservesMemory=[frame])
232
+ regions = [{"name": "synthetic", "start": 0, "end": len(c.bytes()), "ip": 0, "segment": 0x1000, "resident": True,
233
+ "entries": [0, c.labels["pushes"]], "evidence": "synthetic declared code extent"}]
234
+ local = {"segment": "ss", "base": "bp", "displacement": -2, "width": 2}
235
+ controls = [control("predicate", "origin", at={"site": c.labels["test"], "event": "compare"}, value={"field": "left"},
236
+ expect={"inputs": {"include": [{"modeledCall": c.labels["int"], "register": "bx"}]}}),
237
+ control("later store", "lastWriter", at={"site": c.labels["test"], "event": "checkpoint"}, address=local,
238
+ writers=[c.labels["second"]])]
239
+ query = {"regions": regions, "entry": c.labels["pushes"], "registers": {"ss": 0x3000}, "callModels": [service],
240
+ "relationalControls": controls}
241
+ # Without the frame, BP and SP are unrelated unknowns: the store through BP may alias the
242
+ # wrapper's return word, and no path returns.
243
+ r = report(c, **query)
244
+ self.assertFalse([p for p in r["paths"] if p["returned"]])
245
+ self.assertEqual(verdict(r, "predicate")["verdict"], "undecided")
246
+ r = report(c, **query, entryFrame={"from": 0})
247
+ self.assertTrue(r["entryFrame"]["established"])
248
+ self.assertTrue(all(p["returned"] for p in r["paths"]))
249
+ self.assertTrue(r["relationalControls"]["allHeld"])
250
+
203
251
  def test_an_entry_frame_trace_continues_through_a_modeled_interrupt(self):
204
252
  # From the wrapper's entry, the frame trace reaches the code after the interrupt only through the model.
205
253
  c, service = wrapper_case()
@@ -36,6 +36,20 @@ class ReachTests(unittest.TestCase):
36
36
  with self.assertRaisesRegex(ValueError, "bypass violated on path"):
37
37
  run(c, [control("bypass", "reach", at={"site": c.labels["store"], "event": "write"}, expect="never")])
38
38
 
39
+ def test_a_checkpoint_anchor_gets_its_checkpoint_without_listing_it(self):
40
+ # The store site is not in checkpoints, yet the path that reaches it reports a checkpoint
41
+ # there, so a never control is violated instead of holding for want of the event.
42
+ c = self.code()
43
+ never = control("bypass", "reach", at={"site": c.labels["store"], "event": "checkpoint"}, expect="never")
44
+ with self.assertRaisesRegex(ValueError, "bypass violated on path"):
45
+ run(c, [never])
46
+ held = verdict(run(c, [never], registers={"ax": 0}), "bypass")
47
+ self.assertEqual(held["verdict"], "held")
48
+ always = control("always", "reach", at={"site": c.labels["store"], "event": "checkpoint"}, expect="always")
49
+ result = run(c, [always], registers={"ax": 1})
50
+ self.assertEqual(verdict(result, "always")["verdict"], "held")
51
+ self.assertIn(c.labels["store"], [e["site"] for p in result["paths"] for e in p["events"] if e["kind"] == "checkpoint"])
52
+
39
53
  def test_a_returned_path_without_the_site_violates_always(self):
40
54
  c = self.code()
41
55
  with self.assertRaisesRegex(ValueError, "never reached the anchor"):
@@ -292,6 +306,97 @@ class LastWriterTests(unittest.TestCase):
292
306
  with self.assertRaisesRegex(ValueError, "lists 1 bytes"):
293
307
  run(c, [control("short", "lastWriter", at=at, byteWriters=[[c.labels["low"]]])], registers=FRAME)
294
308
 
309
+ def outputs(self):
310
+ # Two stores to one word and no read of it before the return.
311
+ return Code().label("first").emit("a3 22 00").label("second").emit("89 1e 22 00").label("end").emit("c3")
312
+
313
+ def at_end(self, c, name="slot", **fields):
314
+ fields.setdefault("address", {"segment": "ds", "displacement": 0x22, "width": 2})
315
+ return control(name, "lastWriter", at={"site": c.labels["end"], "event": "checkpoint"}, **fields)
316
+
317
+ def test_an_address_at_a_checkpoint_names_the_later_store_without_a_read(self):
318
+ c = self.outputs()
319
+ r = run(c, [self.at_end(c, writers=[c.labels["second"]])], registers=FRAME)
320
+ result = verdict(r, "slot")
321
+ self.assertEqual(result["verdict"], "held")
322
+ occurrence = result["paths"][0]["occurrences"][0]
323
+ self.assertEqual([b["writer"]["site"] for b in occurrence["bytes"]], [c.labels["second"]] * 2)
324
+ self.assertEqual((occurrence["address"]["segment"]["value"], occurrence["address"]["offset"]["value"]), (0x2000, 0x22))
325
+ # The checkpoint carries the inspected bytes; the path reports no read of them.
326
+ events = r["paths"][0]["events"]
327
+ checkpoint = next(e for e in events if e["kind"] == "checkpoint")
328
+ self.assertEqual(checkpoint["memoryProbes"][0]["control"], "slot")
329
+ self.assertFalse([e for e in events if e["kind"] == "read" and e["site"] != c.labels["end"]])
330
+ with self.assertRaisesRegex(ValueError, "first violated.*byte 0 was written at site 3"):
331
+ run(c, [self.at_end(c, "first", writers=[c.labels["first"]])], registers=FRAME)
332
+
333
+ def test_an_address_through_a_base_register_reads_the_register_at_the_checkpoint(self):
334
+ c = self.outputs()
335
+ address = {"segment": "ds", "base": "bx", "displacement": 2, "width": 2}
336
+ held = self.at_end(c, writers=[c.labels["second"]], address=address)
337
+ self.assertEqual(verdict(run(c, [held], registers={**FRAME, "bx": 0x20}), "slot")["verdict"], "held")
338
+ # With BX unknown the address may be any word, which either store may or may not have reached.
339
+ result = verdict(run(c, [held], registers=FRAME), "slot")
340
+ self.assertEqual(result["verdict"], "undecided")
341
+ self.assertEqual(result["paths"][0]["occurrences"][0]["bytes"][0]["unwritten"]["cause"],
342
+ "possibly written by an aliasing write")
343
+
344
+ def test_an_address_past_a_modeled_call_or_never_written_keeps_its_cause(self):
345
+ c = (Code().label("second").emit("89 1e 22 00").label("service").branch("e8", "external").label("end").emit("c3")
346
+ .label("external").emit("c3"))
347
+ model = [{"site": c.labels["service"], "evidence": "synthetic unread service", "cases": [{}]}]
348
+ result = verdict(run(c, [self.at_end(c, writers=[c.labels["second"]])], registers=FRAME, callModels=model), "slot")
349
+ self.assertEqual(result["verdict"], "undecided")
350
+ self.assertEqual(result["paths"][0]["occurrences"][0]["bytes"][0]["unwritten"]["cause"], "dropped by a modeled call")
351
+ other = {"segment": "ds", "displacement": 0x40, "width": 1}
352
+ held = self.at_end(c, writers=["entryState"], address=other)
353
+ self.assertEqual(verdict(run(c, [held], registers=FRAME), "slot")["verdict"], "held")
354
+ with self.assertRaisesRegex(ValueError, "slot violated.*entryState is not listed"):
355
+ run(c, [self.at_end(c, writers=[c.labels["second"]], address=other)], registers=FRAME)
356
+
357
+ def test_an_address_that_cannot_be_inspected_is_undecided(self):
358
+ c = self.outputs()
359
+ crossing = {"segment": "ds", "displacement": 0xffff, "width": 2}
360
+ result = verdict(run(c, [self.at_end(c, writers=["entryState"], address=crossing)], registers=FRAME), "slot")
361
+ self.assertEqual(result["verdict"], "undecided")
362
+ self.assertIn("cannot be inspected", result["paths"][0]["occurrences"][0]["reason"])
363
+
364
+ def test_an_address_is_checked_before_tracing(self):
365
+ c = self.outputs()
366
+ end = {"site": c.labels["end"], "event": "checkpoint"}
367
+ cases = [(control("a", "lastWriter", at={"site": c.labels["end"], "event": "read"}, writers=["entryState"],
368
+ address={"segment": "ds", "width": 2}), "checkpoint events"),
369
+ (control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ax", "width": 2}), "segment register"),
370
+ (control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ds", "base": "bl", "width": 2}),
371
+ "16-bit general register"),
372
+ (control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ds", "base": "ds", "width": 2}),
373
+ "16-bit general register"),
374
+ (control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ds", "base": None, "width": 2}),
375
+ "16-bit general register"),
376
+ (control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ds", "base": ["bx"], "width": 2}),
377
+ "16-bit general register"),
378
+ (control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ds", "displacement": "2", "width": 2}),
379
+ "displacement must be a 16-bit integer"),
380
+ (control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ds", "displacement": 0x10022, "width": 2}),
381
+ "displacement must be a 16-bit integer"),
382
+ (control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ds", "displacement": -0x8001, "width": 2}),
383
+ "displacement must be a 16-bit integer"),
384
+ (control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ds", "width": 0}), "width"),
385
+ (control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ds", "width": 33}), "width"),
386
+ (control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ds", "width": 2, "index": "si"}),
387
+ "address names segment"),
388
+ (control("a", "lastWriter", at=end, byteWriters=[["entryState"]], address={"segment": "ds", "width": 2}),
389
+ "lists 1 bytes; its address has 2")]
390
+ for rule, message in cases:
391
+ with self.assertRaisesRegex(ValueError, message):
392
+ run(c, [rule], registers=FRAME)
393
+ # The widest address and a negative displacement are accepted.
394
+ widest = control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ds", "displacement": 0x40, "width": 32})
395
+ self.assertEqual(verdict(run(c, [widest], registers=FRAME), "a")["verdict"], "held")
396
+ below = control("a", "lastWriter", at=end, writers=["entryState"], address={"segment": "ds", "displacement": -2, "width": 2})
397
+ occurrence = verdict(run(c, [below], registers=FRAME), "a")["paths"][0]["occurrences"][0]
398
+ self.assertEqual(occurrence["address"]["offset"]["value"], 0xfffe)
399
+
295
400
 
296
401
  class ContainmentTests(unittest.TestCase):
297
402
  def buffer(self, length, **extra):