scientific-method-engine 6.3.0__tar.gz → 7.0.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 (68) hide show
  1. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/cli.py +2 -1
  4. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/reports.py +66 -26
  5. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/tests/test_x86.py +93 -13
  6. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/.gitignore +0 -0
  7. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/LICENSE +0 -0
  8. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/README.md +0 -0
  9. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/__init__.py +0 -0
  10. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/__main__.py +0 -0
  11. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  12. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  13. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  14. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  15. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  16. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  17. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  18. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  19. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  20. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  21. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  22. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  23. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  24. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  25. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  26. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  27. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  28. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  29. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  30. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  31. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  32. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  33. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  34. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  35. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  36. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  37. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  38. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  39. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  40. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  41. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  42. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  43. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  44. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  45. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  46. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/image.py +0 -0
  47. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/loops.py +0 -0
  48. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/machine.py +0 -0
  49. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  50. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  51. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  52. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/pe.py +0 -0
  53. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/relational.py +0 -0
  54. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  55. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/trace.py +0 -0
  56. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/src/scientific_method_engine/x86/values.py +0 -0
  57. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/tests/oracle.py +0 -0
  58. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/tests/test_continuation_budget.py +0 -0
  59. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/tests/test_dispatch.py +0 -0
  60. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/tests/test_effect_order.py +0 -0
  61. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/tests/test_entry_frame.py +0 -0
  62. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/tests/test_loops.py +0 -0
  63. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/tests/test_memory_scopes.py +0 -0
  64. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/tests/test_nested_frame_request.py +0 -0
  65. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/tests/test_oracle.py +0 -0
  66. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/tests/test_pe.py +0 -0
  67. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.0}/tests/test_relational_controls.py +0 -0
  68. {scientific_method_engine-6.3.0 → scientific_method_engine-7.0.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: 6.3.0
3
+ Version: 7.0.0
4
4
  Summary: Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code.
5
5
  Project-URL: Source, https://github.com/kibertoad/refurbished-dinosaurs-toolkit/tree/main/packages/scientific-method-engine
6
6
  Author: kibertoad
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  name = "scientific-method-engine"
7
7
  # The release workflow writes the published version from the package's release tag.
8
- version = "6.3.0"
8
+ version = "7.0.0"
9
9
  description = "Bounded instruction-derived x86 evidence reports for segmented MZ/FBOV and PE32/i386 code."
10
10
  readme = "README.md"
11
11
  requires-python = ">=3.12"
@@ -17,7 +17,8 @@ USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bou
17
17
  "effects|returns|memory|incoming|call-order|guards|allocation|dispatch> <config.json|->\n"
18
18
  "effects includes ordered path writes/calls and local restoration witnesses; transactionality remains unestablished.\n"
19
19
  "callees compares its edges with an ExportCallEdges.java export given as ghidraCallEdges;\n"
20
- "agreed is false where Ghidra ends the function at a call, conditional jump or interrupt the engine reads past (ghidraEndsFunction).\n"
20
+ "agreed is false where Ghidra ends the function at a call, conditional jump or interrupt the engine reads past (ghidraEndsFunction),\n"
21
+ "or continues past a jmp, ljmp, return or hlt the engine stops at (ghidraContinues).\n"
21
22
  "trace, arguments, effects, returns, guards, memory and allocation check relationalControls:\n"
22
23
  "a violated control fails the report; an undecided one is reported and never counts as held.\n"
23
24
  "entryFrame {from} starts an entry inside the function at from, in the frame a trace from there observed.\n"
@@ -1041,7 +1041,7 @@ def callees(image, config):
1041
1041
  and not s["omittedRoutes"]
1042
1042
  and not any(d.get("reason") in capped for at in s["entries"] for d in nodes[at]["dependencies"])
1043
1043
  and not any(d.get("reason") in capped for i in s["dependencyEdges"] for d in edges[i]["dependencies"]))
1044
- cross_check = _ghidra_cross_check(export, nodes, outgoing, omitted) if export is not None else None
1044
+ cross_check = _ghidra_cross_check(image, export, nodes, outgoing, omitted) if export is not None else None
1045
1045
  known = {"sharedSites": {e["site"] for e in edges if shared_control(e)},
1046
1046
  "recursiveSites": {e["site"] for e in edges if e["classification"] == "recursivePath"},
1047
1047
  "writeSites": {o["site"] for n in nodes.values() for o in n["memoryObservations"] if o["boundaryUsable"] and "write" in o["access"]},
@@ -1121,22 +1121,60 @@ def _ghidra_key(g):
1121
1121
  return g["site"], g["target"]
1122
1122
 
1123
1123
 
1124
+ # The flow types Ghidra's RefType builds with a fall-through (FlowType.hasFallthrough). Every other flow type ends the
1125
+ # function at its instruction, CONDITIONAL_CALL_TERMINATOR included.
1126
+ GHIDRA_FALL_THROUGH_FLOWS = frozenset((
1127
+ "FALL_THROUGH", "CONDITIONAL_JUMP", "UNCONDITIONAL_CALL", "CONDITIONAL_CALL", "CONDITIONAL_TERMINATOR",
1128
+ "COMPUTED_CALL", "CONDITIONAL_COMPUTED_CALL", "CONDITIONAL_COMPUTED_JUMP", "CALL_OVERRIDE_UNCONDITIONAL",
1129
+ "CALLOTHER_OVERRIDE_CALL"))
1130
+
1131
+
1124
1132
  def _ghidra_falls_through(g):
1125
1133
  """Whether Ghidra continues to the next instruction at an exported edge's site, and what that was read from.
1126
1134
 
1127
1135
  The export's fallsThrough also reflects a user's fall-through override. Copies of the script that leave it out
1128
- are read by the flow type's name, which misses such an override.
1136
+ are read by the flow type's name, which misses such an override: a flow type Ghidra gives a fall-through
1137
+ (GHIDRA_FALL_THROUGH_FLOWS) continues, and every other one ends the function.
1129
1138
  """
1130
1139
  exported = g["fallsThrough"] is not None
1131
- return {"ghidraFallsThrough": g["fallsThrough"] if exported else "TERMINATOR" not in g["flow"],
1140
+ named = g["flow"] in GHIDRA_FALL_THROUGH_FLOWS
1141
+ return {"ghidraFallsThrough": g["fallsThrough"] if exported else named,
1132
1142
  "ghidraFallsThroughBasis": "fallsThrough" if exported else "flowName"}
1133
1143
 
1134
1144
 
1135
- def _ghidra_cross_check(export, nodes, outgoing, omitted):
1145
+ def _engine_reads_on(image, ins):
1146
+ """Whether the engine's body reading continues to the instruction after ins.
1147
+
1148
+ It stops at a jmp, ljmp, return or hlt, and reads on past every other instruction, including a call, a conditional
1149
+ jump and an interrupt. At a transfer outside the frame model it stops with a gap, so the result is None: the engine
1150
+ decided nothing there. It is None too when the engine did not read ins.
1151
+ """
1152
+ if ins is None or unsupported_transfer(image, ins):
1153
+ return None
1154
+ m = base_mnemonic(ins)
1155
+ return not (m in RETURNS or m in ("hlt", "jmp", "ljmp"))
1156
+
1157
+
1158
+ def _ghidra_cross_check(image, export, nodes, outgoing, omitted):
1136
1159
  """Compare the engine's edges with Ghidra's for each caller both read; a Ghidra-only edge stays unchecked."""
1137
1160
  callers = export["callers"]
1138
1161
  compared = sorted(nodes.keys() & callers.keys())
1139
1162
  rows = []
1163
+ # Rows where Ghidra ends the function at an instruction the engine reads past, and rows where Ghidra continues past
1164
+ # an instruction the engine stops at. Either way the two analyses disagree on the function's extent.
1165
+ ends, continues = [], []
1166
+
1167
+ def compare_extent(row, g, ins):
1168
+ reads_on = _engine_reads_on(image, ins)
1169
+ if reads_on is None:
1170
+ return row
1171
+ row |= _ghidra_falls_through(g)
1172
+ if reads_on and row["ghidraFallsThrough"] is False:
1173
+ ends.append(row)
1174
+ elif not reads_on and row["ghidraFallsThrough"] is True:
1175
+ continues.append(row)
1176
+ return row
1177
+
1140
1178
  for caller in compared:
1141
1179
  ours = outgoing.get(caller, [])
1142
1180
  theirs = callers[caller]
@@ -1148,12 +1186,9 @@ def _ghidra_cross_check(export, nodes, outgoing, omitted):
1148
1186
  g = matches.get((e["site"], e["target"]))
1149
1187
  row = {"caller": caller, "site": e["site"], "target": e["target"], "engineEdge": e["id"],
1150
1188
  "result": "engineOnly" if g is None else "agreement", "ghidraFlow": g["flow"] if g else None}
1151
- # The engine reads on past every call and every conditional tail transfer, and stops at a jmp or ljmp.
1152
1189
  # Ghidra ends the function at a call to a callee it treats as non-returning (CALL_TERMINATOR) or at an
1153
- # instruction whose fall-through a user cleared.
1154
- if g is not None and (e["kind"] != "tail transfer" or base_mnemonic(instructions[e["site"]]) not in ("jmp", "ljmp")):
1155
- row |= _ghidra_falls_through(g)
1156
- rows.append(row)
1190
+ # instruction whose fall-through a user cleared, and continues past a jmp a user gave a fall-through.
1191
+ rows.append(row if g is None else compare_extent(row, g, instructions[e["site"]]))
1157
1192
  for g in theirs:
1158
1193
  if g["site"] is not None and _ghidra_key(g) in read:
1159
1194
  continue
@@ -1162,35 +1197,40 @@ def _ghidra_cross_check(export, nodes, outgoing, omitted):
1162
1197
  # SLEIGH lifts INT, INT1, INT3 and INTO to a computed call with no target, while the engine assumes the
1163
1198
  # interrupt returns to the next instruction and records no edge. At INT1 and INT3 Ghidra's flow is a
1164
1199
  # terminator that ends the function there.
1165
- rows.append({"caller": caller, "site": g["site"], "target": None, "siteAddress": g["siteAddress"],
1166
- "targetAddress": None, "ghidraFlow": g["flow"], "result": "interrupt", "engineEdge": None,
1167
- **_ghidra_falls_through(g)})
1200
+ rows.append(compare_extent({"caller": caller, "site": g["site"], "target": None, "siteAddress": g["siteAddress"],
1201
+ "targetAddress": None, "ghidraFlow": g["flow"], "result": "interrupt",
1202
+ "engineEdge": None}, g, ins))
1168
1203
  continue
1169
- # Ghidra's edge is evidence the engine did not check; it never becomes an engine edge.
1170
- rows.append({"caller": caller, "site": g["site"], "target": g["target"], "siteAddress": g["siteAddress"],
1171
- "targetAddress": g["targetAddress"], "ghidraFlow": g["flow"], "result": "ghidraOnly", "checked": False,
1172
- "engineEdge": next((e["id"] for e in ours if g["site"] is not None and e["site"] == g["site"]), None)})
1204
+ # Ghidra's edge is evidence the engine did not check; it never becomes an engine edge. Its fall-through is
1205
+ # still compared where the engine read the instruction at its site.
1206
+ engine_edge = next((e["id"] for e in ours if g["site"] is not None and e["site"] == g["site"]), None)
1207
+ rows.append(compare_extent({"caller": caller, "site": g["site"], "target": g["target"], "siteAddress": g["siteAddress"],
1208
+ "targetAddress": g["targetAddress"], "ghidraFlow": g["flow"], "result": "ghidraOnly",
1209
+ "checked": False, "engineEdge": engine_edge}, g, ins))
1173
1210
  counts = {kind: sum(r["result"] == kind for r in rows) for kind in ("agreement", "engineOnly", "ghidraOnly", "interrupt")}
1174
- counts["ghidraEndsFunction"] = sum(r.get("ghidraFallsThrough") is False for r in rows)
1211
+ counts["ghidraEndsFunction"] = len(ends)
1212
+ counts["ghidraContinues"] = len(continues)
1175
1213
  not_compared = {"engineCallers": sorted(nodes.keys() - callers.keys()), "ghidraCallers": sorted(callers.keys() - nodes.keys()),
1176
1214
  "unmappedGhidraFunctions": export["unmappedFunctions"], "missingGhidraEntries": export["missingEntries"],
1177
1215
  "unreadGhidraFunctions": export["unreadFunctions"],
1178
1216
  "omittedEngineRoutes": [o["id"] for o in omitted if o["entry"] in callers]}
1179
- # A site agrees only when every edge either analysis read there agrees and Ghidra continues past it as the engine does.
1180
- disputed = {r["site"] for r in rows if r["result"] != "agreement" or r.get("ghidraFallsThrough") is False}
1217
+ # A site agrees only when every edge either analysis read there agrees and Ghidra continues past it exactly when the
1218
+ # engine does.
1219
+ disputed = {r["site"] for r in rows if r["result"] != "agreement"} | {r["site"] for r in ends + continues}
1181
1220
  return {"comparedCallers": compared, "edges": rows, "counts": counts, "notCompared": not_compared,
1182
1221
  "agreed": (not counts["engineOnly"] and not counts["ghidraOnly"] and not any(not_compared.values())
1183
- and not counts["ghidraEndsFunction"]),
1222
+ and not counts["ghidraEndsFunction"] and not counts["ghidraContinues"]),
1184
1223
  "agreementSites": {r["site"] for r in rows if r["result"] == "agreement"} - disputed,
1185
1224
  "interpretation": "Edges of each caller that both the engine and the Ghidra export read, matched by site and target "
1186
1225
  "file offset; an unresolved call matches an unresolved call at its site, and a Ghidra target without a file offset "
1187
1226
  "matches no engine edge. An interrupt row is Ghidra's targetless call at an instruction the engine read as an "
1188
- "interrupt and assumed to return. The engine reads on past every call, conditional jump and interrupt, so an "
1189
- "interrupt row or an agreement at a call or conditional tail transfer counts against agreed when Ghidra "
1190
- "ends the function there (ghidraFallsThrough false, counted in ghidraEndsFunction), read from the export's "
1191
- "fallsThrough or, in an export without it, from the flow name (ghidraFallsThroughBasis). "
1192
- "A ghidraOnly edge is Ghidra's claim: the engine did not check it and never adds it to its graph. Agreement "
1193
- "means both analyses read the edge, not that it executes."}
1227
+ "interrupt and assumed to return. A row at an instruction the engine read carries whether Ghidra continues "
1228
+ "to the next instruction there (ghidraFallsThrough), read from the export's fallsThrough or, in an export "
1229
+ "without it, from the flow name (ghidraFallsThroughBasis). The engine reads on past every call, conditional jump "
1230
+ "and interrupt and stops at a jmp, ljmp, return or hlt. A row where Ghidra ends the function at an instruction "
1231
+ "the engine reads past (ghidraEndsFunction) or continues past one the engine stops at (ghidraContinues) "
1232
+ "counts against agreed. A ghidraOnly edge is Ghidra's claim: the engine did not check it and never adds it "
1233
+ "to its graph. Agreement means both analyses read the edge, not that it executes."}
1194
1234
 
1195
1235
 
1196
1236
  # These branches test CX/ECX (LOOPE/LOOPNE also ZF), so an adjacent CMP/TEST never describes their predicate.
@@ -681,7 +681,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
681
681
  # Ghidra's computed target never becomes an engine edge.
682
682
  self.assertIsNone(r["edges"][2]["target"])
683
683
  self.assertEqual(r["edges"][2]["classification"], "unresolved")
684
- self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 2, "ghidraOnly": 1, "interrupt": 0, "ghidraEndsFunction": 0})
684
+ self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 2, "ghidraOnly": 1, "interrupt": 0, "ghidraEndsFunction": 0, "ghidraContinues": 0})
685
685
  self.assertEqual(check["comparedCallers"], [0, b])
686
686
  self.assertEqual(check["notCompared"]["engineCallers"], [a])
687
687
  self.assertFalse(check["agreed"])
@@ -695,7 +695,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
695
695
  r = run_report(data, cfg, "callees")
696
696
  check = r["ghidraCrossCheck"]
697
697
  self.assertTrue(check["agreed"])
698
- self.assertEqual(check["counts"], {"agreement": 2, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 0, "ghidraEndsFunction": 0})
698
+ self.assertEqual(check["counts"], {"agreement": 2, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 0, "ghidraEndsFunction": 0, "ghidraContinues": 0})
699
699
  # Agreement on an unresolved call leaves the engine's edge unresolved.
700
700
  self.assertEqual(r["edges"][1]["classification"], "unresolved")
701
701
 
@@ -707,7 +707,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
707
707
  cfg = configuration(data, ghidraCallEdges=export)
708
708
  cfg["regions"][0]["entries"] = [0, 6]
709
709
  check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
710
- self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 1, "ghidraOnly": 1, "interrupt": 0, "ghidraEndsFunction": 0})
710
+ self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 1, "ghidraOnly": 1, "interrupt": 0, "ghidraEndsFunction": 0, "ghidraContinues": 0})
711
711
  self.assertFalse(check["agreed"])
712
712
  cfg["controls"] = {"ghidraAgreementSites": [3]}
713
713
  with self.assertRaisesRegex(ValueError, "positive control missed: ghidraAgreementSites"):
@@ -723,7 +723,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
723
723
  r = run_report(data, cfg, "callees")
724
724
  check = r["ghidraCrossCheck"]
725
725
  self.assertTrue(check["agreed"])
726
- self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 2, "ghidraEndsFunction": 0})
726
+ self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 2, "ghidraEndsFunction": 0, "ghidraContinues": 0})
727
727
  rows = [e for e in check["edges"] if e["result"] == "interrupt"]
728
728
  self.assertEqual([(e["site"], e["ghidraFallsThrough"]) for e in rows], [(0, True), (2, True)])
729
729
  self.assertEqual([e["site"] for e in r["edges"]], [3])
@@ -748,7 +748,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
748
748
  data = bytes.fromhex("cc c3")
749
749
  cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, None, "COMPUTED_CALL_TERMINATOR")]}))
750
750
  check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
751
- self.assertEqual(check["counts"], {"agreement": 0, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 1, "ghidraEndsFunction": 1})
751
+ self.assertEqual(check["counts"], {"agreement": 0, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 1, "ghidraEndsFunction": 1, "ghidraContinues": 0})
752
752
  self.assertFalse(check["agreed"])
753
753
 
754
754
  def test_the_exported_falls_through_decides_an_interrupt_over_the_flow_name(self):
@@ -790,7 +790,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
790
790
  self.assertEqual(row["result"], "agreement")
791
791
  self.assertEqual((row["ghidraFallsThrough"], row["ghidraFallsThroughBasis"]), (falls_through, "fallsThrough"))
792
792
  self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 0,
793
- "ghidraEndsFunction": 0 if falls_through else 1})
793
+ "ghidraEndsFunction": 0 if falls_through else 1, "ghidraContinues": 0})
794
794
  self.assertEqual(check["agreed"], agreed)
795
795
  # A call Ghidra ends the function at is no agreement site.
796
796
  cfg["controls"] = {"ghidraAgreementSites": [0]}
@@ -814,19 +814,99 @@ class GhidraCrossCheckTests(unittest.TestCase):
814
814
  self.assertEqual(check["counts"]["ghidraEndsFunction"], 0 if falls_through else 1)
815
815
  self.assertEqual(check["agreed"], falls_through)
816
816
 
817
- def test_an_agreed_tail_transfer_keeps_agreed_without_a_falls_through(self):
818
- # jmp 3; ret; ret. Neither analysis continues past an unconditional jump into another function.
817
+ def test_a_jmp_tail_transfer_ghidra_continues_past_counts_against_agreed(self):
818
+ # jmp 3; ret; ret. The engine stops at the unconditional jump into the entry at 3. Ghidra stops there too,
819
+ # unless a user gave the jump a fall-through.
819
820
  data = bytes.fromhex("eb 01 c3 c3")
820
- cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, 3, "UNCONDITIONAL_JUMP", False)], 3: []}),
821
+ for falls_through in (False, True):
822
+ with self.subTest(fallsThrough=falls_through):
823
+ cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, 3, "UNCONDITIONAL_JUMP", falls_through)], 3: []}))
824
+ cfg["regions"][0]["entries"] = [0, 3]
825
+ check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
826
+ [row] = check["edges"]
827
+ self.assertEqual(row["result"], "agreement")
828
+ self.assertEqual((row["ghidraFallsThrough"], row["ghidraFallsThroughBasis"]), (falls_through, "fallsThrough"))
829
+ self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 0,
830
+ "ghidraEndsFunction": 0, "ghidraContinues": 1 if falls_through else 0})
831
+ self.assertEqual(check["agreed"], not falls_through)
832
+ # A jump Ghidra continues past is no agreement site.
833
+ cfg["controls"] = {"ghidraAgreementSites": [0]}
834
+ if falls_through:
835
+ with self.assertRaisesRegex(ValueError, "positive control missed: ghidraAgreementSites"):
836
+ run_report(data, cfg, "callees")
837
+ else:
838
+ run_report(data, cfg, "callees")
839
+
840
+ def test_a_jmp_in_an_export_without_falls_through_reads_the_flow_name(self):
841
+ # An unconditional jump's flow never falls through, so an export from an older copy of the script agrees at the
842
+ # jump. A user's fall-through override on it goes unseen.
843
+ data = bytes.fromhex("eb 01 c3 c3")
844
+ cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, 3, "UNCONDITIONAL_JUMP")], 3: []}),
821
845
  controls={"ghidraAgreementSites": [0]})
822
846
  cfg["regions"][0]["entries"] = [0, 3]
823
847
  check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
824
848
  [row] = check["edges"]
825
- self.assertEqual(row["result"], "agreement")
826
- self.assertNotIn("ghidraFallsThrough", row)
827
- self.assertEqual(check["counts"]["ghidraEndsFunction"], 0)
849
+ self.assertEqual((row["ghidraFallsThrough"], row["ghidraFallsThroughBasis"]), (False, "flowName"))
850
+ self.assertEqual(check["counts"]["ghidraContinues"], 0)
828
851
  self.assertTrue(check["agreed"])
829
852
 
853
+ def test_a_conditional_flow_name_falls_through_as_ghidra_defines_it(self):
854
+ # je 3; ret; ret. The engine reads on past the conditional jump. Ghidra's CONDITIONAL_TERMINATOR has a
855
+ # fall-through, while its CONDITIONAL_CALL_TERMINATOR does not, although both names contain TERMINATOR.
856
+ data = bytes.fromhex("74 01 c3 c3")
857
+ for flow, falls_through in (("CONDITIONAL_TERMINATOR", True), ("CONDITIONAL_CALL_TERMINATOR", False)):
858
+ with self.subTest(flow=flow):
859
+ cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, 3, flow)], 3: []}))
860
+ cfg["regions"][0]["entries"] = [0, 3]
861
+ check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
862
+ [row] = check["edges"]
863
+ self.assertEqual((row["ghidraFallsThrough"], row["ghidraFallsThroughBasis"]), (falls_through, "flowName"))
864
+ self.assertEqual(check["counts"]["ghidraEndsFunction"], 0 if falls_through else 1)
865
+ self.assertEqual(check["agreed"], falls_through)
866
+
867
+ def test_a_ghidra_only_call_carries_where_ghidra_ends_the_function(self):
868
+ # call 4; ret; ret; ret. The engine resolves the call to 4 and reads on to the ret after it. Ghidra resolves it
869
+ # to 5, and ends the function there when it treats that callee as non-returning.
870
+ data = bytes.fromhex("e8 01 00 c3 c3 c3")
871
+ for flow, falls_through in (("UNCONDITIONAL_CALL", True), ("CALL_TERMINATOR", False)):
872
+ with self.subTest(flow=flow):
873
+ cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, 5, flow, falls_through)], 4: [], 5: []}))
874
+ cfg["regions"][0]["entries"] = [0, 4, 5]
875
+ check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
876
+ [ours, theirs] = check["edges"]
877
+ self.assertEqual((ours["result"], ours["target"]), ("engineOnly", 4))
878
+ self.assertNotIn("ghidraFallsThrough", ours)
879
+ self.assertEqual((theirs["result"], theirs["target"], theirs["engineEdge"]), ("ghidraOnly", 5, ours["engineEdge"]))
880
+ self.assertEqual((theirs["ghidraFallsThrough"], theirs["ghidraFallsThroughBasis"]), (falls_through, "fallsThrough"))
881
+ self.assertEqual(check["counts"], {"agreement": 0, "engineOnly": 1, "ghidraOnly": 1, "interrupt": 0,
882
+ "ghidraEndsFunction": 0 if falls_through else 1, "ghidraContinues": 0})
883
+ self.assertFalse(check["agreed"])
884
+
885
+ def test_a_ghidra_only_edge_at_an_instruction_the_engine_did_not_read_has_no_falls_through(self):
886
+ # ret; ret. Ghidra claims a call at 1, past the end of the engine's body for the entry at 0, so the engine has no
887
+ # reading there to compare Ghidra's fall-through with.
888
+ data = bytes.fromhex("c3 c3")
889
+ cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(1, None, "COMPUTED_CALL_TERMINATOR", False)]}))
890
+ check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
891
+ [row] = check["edges"]
892
+ self.assertEqual(row["result"], "ghidraOnly")
893
+ self.assertNotIn("ghidraFallsThrough", row)
894
+ self.assertEqual((check["counts"]["ghidraEndsFunction"], check["counts"]["ghidraContinues"]), (0, 0))
895
+ self.assertFalse(check["agreed"])
896
+
897
+ def test_a_ghidra_only_edge_at_a_transfer_outside_the_frame_model_has_no_falls_through(self):
898
+ # o32 call 7; ret; ret. The engine stops at the operand-size call with a gap and decides nothing about
899
+ # fall-through there, so Ghidra's terminator is not compared.
900
+ data = bytes.fromhex("66 e8 01 00 00 00 c3 c3")
901
+ cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, 7, "CALL_TERMINATOR", False)], 7: []}))
902
+ cfg["regions"][0]["entries"] = [0, 7]
903
+ check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
904
+ [row] = check["edges"]
905
+ self.assertEqual(row["result"], "ghidraOnly")
906
+ self.assertNotIn("ghidraFallsThrough", row)
907
+ self.assertEqual((check["counts"]["ghidraEndsFunction"], check["counts"]["ghidraContinues"]), (0, 0))
908
+ self.assertFalse(check["agreed"])
909
+
830
910
  def test_a_conditional_tail_transfer_ghidra_ends_the_function_at_counts_against_agreed(self):
831
911
  # je 3; ret; ret. The engine reads on past the conditional jump into the entry at 3; Ghidra ends the function
832
912
  # there when a user cleared the jump's fall-through.
@@ -869,7 +949,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
869
949
  cfg["regions"][0]["entries"] = [0, 6]
870
950
  r = run_report(data, cfg, "callees")
871
951
  check = r["ghidraCrossCheck"]
872
- self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 0, "ghidraEndsFunction": 0})
952
+ self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 0, "ghidraEndsFunction": 0, "ghidraContinues": 0})
873
953
  self.assertEqual(check["notCompared"]["omittedEngineRoutes"], [r["omittedRoutes"][0]["id"]])
874
954
  self.assertFalse(check["agreed"])
875
955