scientific-method-engine 5.0.0__tar.gz → 6.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 (67) hide show
  1. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/PKG-INFO +1 -1
  2. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/pyproject.toml +1 -1
  3. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/cli.py +2 -1
  4. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/reports.py +31 -14
  5. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/tests/test_x86.py +78 -6
  6. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/.gitignore +0 -0
  7. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/LICENSE +0 -0
  8. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/README.md +0 -0
  9. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/__init__.py +0 -0
  10. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/__main__.py +0 -0
  11. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  12. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  13. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  14. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  15. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  16. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  17. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  18. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  19. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  20. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  21. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  22. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  23. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  24. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  25. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  26. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  27. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  28. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  29. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  30. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  31. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  32. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  33. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  34. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  35. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  36. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  37. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  38. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  39. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  40. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  41. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  42. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  43. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  44. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  45. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  46. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/image.py +0 -0
  47. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/loops.py +0 -0
  48. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/machine.py +0 -0
  49. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  50. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  51. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  52. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/pe.py +0 -0
  53. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/relational.py +0 -0
  54. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  55. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/trace.py +0 -0
  56. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/src/scientific_method_engine/x86/values.py +0 -0
  57. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/tests/oracle.py +0 -0
  58. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/tests/test_continuation_budget.py +0 -0
  59. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/tests/test_dispatch.py +0 -0
  60. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/tests/test_effect_order.py +0 -0
  61. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/tests/test_loops.py +0 -0
  62. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/tests/test_memory_scopes.py +0 -0
  63. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/tests/test_nested_frame_request.py +0 -0
  64. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/tests/test_oracle.py +0 -0
  65. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/tests/test_pe.py +0 -0
  66. {scientific_method_engine-5.0.0 → scientific_method_engine-6.0.0}/tests/test_relational_controls.py +0 -0
  67. {scientific_method_engine-5.0.0 → scientific_method_engine-6.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: 5.0.0
3
+ Version: 6.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 = "5.0.0"
8
+ version = "6.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"
@@ -16,7 +16,8 @@ INSTRUCTION_SEMANTICS = f"pypcode {pypcode.__version__} (Ghidra SLEIGH x86)"
16
16
  USAGE = ("Usage: scientific-method-engine <operand|operand-candidates|target|bounds|owner|callees|trace|uses|arguments|"
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
- "callees compares its edges with an ExportCallEdges.java export given as ghidraCallEdges.\n"
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
21
  "trace, arguments, effects, returns, guards, memory and allocation check relationalControls:\n"
21
22
  "a violated control fails the report; an undecided one is reported and never counts as held.\n"
22
23
  "Declared table continuations are separate conditional paths that spend continuationBudget\n"
@@ -1105,6 +1105,17 @@ def _ghidra_key(g):
1105
1105
  return g["site"], g["target"]
1106
1106
 
1107
1107
 
1108
+ def _ghidra_falls_through(g):
1109
+ """Whether Ghidra continues to the next instruction at an exported edge's site, and what that was read from.
1110
+
1111
+ The export's fallsThrough also reflects a user's fall-through override. Copies of the script that leave it out
1112
+ are read by the flow type's name, which misses such an override.
1113
+ """
1114
+ exported = g["fallsThrough"] is not None
1115
+ return {"ghidraFallsThrough": g["fallsThrough"] if exported else "TERMINATOR" not in g["flow"],
1116
+ "ghidraFallsThroughBasis": "fallsThrough" if exported else "flowName"}
1117
+
1118
+
1108
1119
  def _ghidra_cross_check(export, nodes, outgoing, omitted):
1109
1120
  """Compare the engine's edges with Ghidra's for each caller both read; a Ghidra-only edge stays unchecked."""
1110
1121
  callers = export["callers"]
@@ -1115,12 +1126,18 @@ def _ghidra_cross_check(export, nodes, outgoing, omitted):
1115
1126
  theirs = callers[caller]
1116
1127
  instructions = nodes[caller]["body"]["instructions"]
1117
1128
  # A call neither analysis resolved matches on its site with no target.
1118
- flows = {_ghidra_key(g): g["flow"] for g in theirs if g["site"] is not None}
1129
+ matches = {_ghidra_key(g): g for g in theirs if g["site"] is not None}
1119
1130
  read = {(e["site"], e["target"]) for e in ours}
1120
1131
  for e in ours:
1121
- flow = flows.get((e["site"], e["target"]))
1122
- rows.append({"caller": caller, "site": e["site"], "target": e["target"], "engineEdge": e["id"],
1123
- "result": "engineOnly" if flow is None else "agreement", "ghidraFlow": flow})
1132
+ g = matches.get((e["site"], e["target"]))
1133
+ row = {"caller": caller, "site": e["site"], "target": e["target"], "engineEdge": e["id"],
1134
+ "result": "engineOnly" if g is None else "agreement", "ghidraFlow": g["flow"] if g else None}
1135
+ # The engine reads on past every call and every conditional tail transfer, and stops at a jmp or ljmp.
1136
+ # Ghidra ends the function at a call to a callee it treats as non-returning (CALL_TERMINATOR) or at an
1137
+ # instruction whose fall-through a user cleared.
1138
+ if g is not None and (e["kind"] != "tail transfer" or base_mnemonic(instructions[e["site"]]) not in ("jmp", "ljmp")):
1139
+ row |= _ghidra_falls_through(g)
1140
+ rows.append(row)
1124
1141
  for g in theirs:
1125
1142
  if g["site"] is not None and _ghidra_key(g) in read:
1126
1143
  continue
@@ -1128,34 +1145,34 @@ def _ghidra_cross_check(export, nodes, outgoing, omitted):
1128
1145
  if ins is not None and base_mnemonic(ins) in INTERRUPTS and _ghidra_key(g)[1] is None:
1129
1146
  # SLEIGH lifts INT, INT1, INT3 and INTO to a computed call with no target, while the engine assumes the
1130
1147
  # interrupt returns to the next instruction and records no edge. At INT1 and INT3 Ghidra's flow is a
1131
- # terminator that ends the function there. Ghidra's own fallsThrough also reflects a user override; an
1132
- # export without it is read by the flow type's name.
1133
- exported = g["fallsThrough"] is not None
1148
+ # terminator that ends the function there.
1134
1149
  rows.append({"caller": caller, "site": g["site"], "target": None, "siteAddress": g["siteAddress"],
1135
1150
  "targetAddress": None, "ghidraFlow": g["flow"], "result": "interrupt", "engineEdge": None,
1136
- "ghidraFallsThrough": g["fallsThrough"] if exported else "TERMINATOR" not in g["flow"],
1137
- "ghidraFallsThroughBasis": "fallsThrough" if exported else "flowName"})
1151
+ **_ghidra_falls_through(g)})
1138
1152
  continue
1139
1153
  # Ghidra's edge is evidence the engine did not check; it never becomes an engine edge.
1140
1154
  rows.append({"caller": caller, "site": g["site"], "target": g["target"], "siteAddress": g["siteAddress"],
1141
1155
  "targetAddress": g["targetAddress"], "ghidraFlow": g["flow"], "result": "ghidraOnly", "checked": False,
1142
1156
  "engineEdge": next((e["id"] for e in ours if g["site"] is not None and e["site"] == g["site"]), None)})
1143
1157
  counts = {kind: sum(r["result"] == kind for r in rows) for kind in ("agreement", "engineOnly", "ghidraOnly", "interrupt")}
1158
+ counts["ghidraEndsFunction"] = sum(r.get("ghidraFallsThrough") is False for r in rows)
1144
1159
  not_compared = {"engineCallers": sorted(nodes.keys() - callers.keys()), "ghidraCallers": sorted(callers.keys() - nodes.keys()),
1145
1160
  "unmappedGhidraFunctions": export["unmappedFunctions"], "missingGhidraEntries": export["missingEntries"],
1146
1161
  "unreadGhidraFunctions": export["unreadFunctions"],
1147
1162
  "omittedEngineRoutes": [o["id"] for o in omitted if o["entry"] in callers]}
1148
- # A site agrees only when every edge either analysis read there agrees.
1149
- disputed = {r["site"] for r in rows if r["result"] != "agreement"}
1163
+ # A site agrees only when every edge either analysis read there agrees and Ghidra continues past it as the engine does.
1164
+ disputed = {r["site"] for r in rows if r["result"] != "agreement" or r.get("ghidraFallsThrough") is False}
1150
1165
  return {"comparedCallers": compared, "edges": rows, "counts": counts, "notCompared": not_compared,
1151
1166
  "agreed": (not counts["engineOnly"] and not counts["ghidraOnly"] and not any(not_compared.values())
1152
- and all(r["ghidraFallsThrough"] for r in rows if r["result"] == "interrupt")),
1167
+ and not counts["ghidraEndsFunction"]),
1153
1168
  "agreementSites": {r["site"] for r in rows if r["result"] == "agreement"} - disputed,
1154
1169
  "interpretation": "Edges of each caller that both the engine and the Ghidra export read, matched by site and target "
1155
1170
  "file offset; an unresolved call matches an unresolved call at its site, and a Ghidra target without a file offset "
1156
1171
  "matches no engine edge. An interrupt row is Ghidra's targetless call at an instruction the engine read as an "
1157
- "interrupt and assumed to return; it counts against agreed only when Ghidra's flow ends the function there, read "
1158
- "from the export's fallsThrough or, in an export without it, from the flow name (ghidraFallsThroughBasis). "
1172
+ "interrupt and assumed to return. The engine reads on past every call, conditional jump and interrupt, so an "
1173
+ "interrupt row or an agreement at a call or conditional tail transfer counts against agreed when Ghidra "
1174
+ "ends the function there (ghidraFallsThrough false, counted in ghidraEndsFunction), read from the export's "
1175
+ "fallsThrough or, in an export without it, from the flow name (ghidraFallsThroughBasis). "
1159
1176
  "A ghidraOnly edge is Ghidra's claim: the engine did not check it and never adds it to its graph. Agreement "
1160
1177
  "means both analyses read the edge, not that it executes."}
1161
1178
 
@@ -615,7 +615,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
615
615
  # Ghidra's computed target never becomes an engine edge.
616
616
  self.assertIsNone(r["edges"][2]["target"])
617
617
  self.assertEqual(r["edges"][2]["classification"], "unresolved")
618
- self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 2, "ghidraOnly": 1, "interrupt": 0})
618
+ self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 2, "ghidraOnly": 1, "interrupt": 0, "ghidraEndsFunction": 0})
619
619
  self.assertEqual(check["comparedCallers"], [0, b])
620
620
  self.assertEqual(check["notCompared"]["engineCallers"], [a])
621
621
  self.assertFalse(check["agreed"])
@@ -629,7 +629,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
629
629
  r = run_report(data, cfg, "callees")
630
630
  check = r["ghidraCrossCheck"]
631
631
  self.assertTrue(check["agreed"])
632
- self.assertEqual(check["counts"], {"agreement": 2, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 0})
632
+ self.assertEqual(check["counts"], {"agreement": 2, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 0, "ghidraEndsFunction": 0})
633
633
  # Agreement on an unresolved call leaves the engine's edge unresolved.
634
634
  self.assertEqual(r["edges"][1]["classification"], "unresolved")
635
635
 
@@ -641,7 +641,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
641
641
  cfg = configuration(data, ghidraCallEdges=export)
642
642
  cfg["regions"][0]["entries"] = [0, 6]
643
643
  check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
644
- self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 1, "ghidraOnly": 1, "interrupt": 0})
644
+ self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 1, "ghidraOnly": 1, "interrupt": 0, "ghidraEndsFunction": 0})
645
645
  self.assertFalse(check["agreed"])
646
646
  cfg["controls"] = {"ghidraAgreementSites": [3]}
647
647
  with self.assertRaisesRegex(ValueError, "positive control missed: ghidraAgreementSites"):
@@ -657,7 +657,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
657
657
  r = run_report(data, cfg, "callees")
658
658
  check = r["ghidraCrossCheck"]
659
659
  self.assertTrue(check["agreed"])
660
- self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 2})
660
+ self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 2, "ghidraEndsFunction": 0})
661
661
  rows = [e for e in check["edges"] if e["result"] == "interrupt"]
662
662
  self.assertEqual([(e["site"], e["ghidraFallsThrough"]) for e in rows], [(0, True), (2, True)])
663
663
  self.assertEqual([e["site"] for e in r["edges"]], [3])
@@ -682,7 +682,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
682
682
  data = bytes.fromhex("cc c3")
683
683
  cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, None, "COMPUTED_CALL_TERMINATOR")]}))
684
684
  check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
685
- self.assertEqual(check["counts"], {"agreement": 0, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 1})
685
+ self.assertEqual(check["counts"], {"agreement": 0, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 1, "ghidraEndsFunction": 1})
686
686
  self.assertFalse(check["agreed"])
687
687
 
688
688
  def test_the_exported_falls_through_decides_an_interrupt_over_the_flow_name(self):
@@ -710,6 +710,78 @@ class GhidraCrossCheckTests(unittest.TestCase):
710
710
  self.assertEqual(rows, [(0, True, "flowName"), (2, False, "flowName")])
711
711
  self.assertFalse(check["agreed"])
712
712
 
713
+ def test_a_call_ghidra_ends_the_function_at_counts_against_agreed(self):
714
+ # call 4; ret; ret. Both analyses have the call. The engine reads on to the ret after it, while Ghidra ends
715
+ # the function at the call when it treats the callee as non-returning or a user cleared the fall-through.
716
+ data = bytes.fromhex("e8 01 00 c3 c3")
717
+ for flow, falls_through, agreed in (("UNCONDITIONAL_CALL", True, True), ("UNCONDITIONAL_CALL", False, False),
718
+ ("CALL_TERMINATOR", False, False), ("CALL_TERMINATOR", True, True)):
719
+ with self.subTest(flow=flow, fallsThrough=falls_through):
720
+ cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, 4, flow, falls_through)], 4: []}))
721
+ cfg["regions"][0]["entries"] = [0, 4]
722
+ check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
723
+ [row] = check["edges"]
724
+ self.assertEqual(row["result"], "agreement")
725
+ self.assertEqual((row["ghidraFallsThrough"], row["ghidraFallsThroughBasis"]), (falls_through, "fallsThrough"))
726
+ self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 0,
727
+ "ghidraEndsFunction": 0 if falls_through else 1})
728
+ self.assertEqual(check["agreed"], agreed)
729
+ # A call Ghidra ends the function at is no agreement site.
730
+ cfg["controls"] = {"ghidraAgreementSites": [0]}
731
+ if agreed:
732
+ run_report(data, cfg, "callees")
733
+ else:
734
+ with self.assertRaisesRegex(ValueError, "positive control missed: ghidraAgreementSites"):
735
+ run_report(data, cfg, "callees")
736
+
737
+ def test_a_call_in_an_export_without_falls_through_reads_the_flow_name(self):
738
+ # Copies of ExportCallEdges.java written before fallsThrough was added: CALL_TERMINATOR ends the function, and a
739
+ # cleared fall-through on an UNCONDITIONAL_CALL goes unseen. The row names the flow name as its basis.
740
+ data = bytes.fromhex("e8 01 00 c3 c3")
741
+ for flow, falls_through in (("UNCONDITIONAL_CALL", True), ("CALL_TERMINATOR", False)):
742
+ with self.subTest(flow=flow):
743
+ cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, 4, flow)], 4: []}))
744
+ cfg["regions"][0]["entries"] = [0, 4]
745
+ check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
746
+ [row] = check["edges"]
747
+ self.assertEqual((row["ghidraFallsThrough"], row["ghidraFallsThroughBasis"]), (falls_through, "flowName"))
748
+ self.assertEqual(check["counts"]["ghidraEndsFunction"], 0 if falls_through else 1)
749
+ self.assertEqual(check["agreed"], falls_through)
750
+
751
+ def test_an_agreed_tail_transfer_keeps_agreed_without_a_falls_through(self):
752
+ # jmp 3; ret; ret. Neither analysis continues past an unconditional jump into another function.
753
+ data = bytes.fromhex("eb 01 c3 c3")
754
+ cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, 3, "UNCONDITIONAL_JUMP", False)], 3: []}),
755
+ controls={"ghidraAgreementSites": [0]})
756
+ cfg["regions"][0]["entries"] = [0, 3]
757
+ check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
758
+ [row] = check["edges"]
759
+ self.assertEqual(row["result"], "agreement")
760
+ self.assertNotIn("ghidraFallsThrough", row)
761
+ self.assertEqual(check["counts"]["ghidraEndsFunction"], 0)
762
+ self.assertTrue(check["agreed"])
763
+
764
+ def test_a_conditional_tail_transfer_ghidra_ends_the_function_at_counts_against_agreed(self):
765
+ # je 3; ret; ret. The engine reads on past the conditional jump into the entry at 3; Ghidra ends the function
766
+ # there when a user cleared the jump's fall-through.
767
+ data = bytes.fromhex("74 01 c3 c3")
768
+ for falls_through in (True, False):
769
+ with self.subTest(fallsThrough=falls_through):
770
+ cfg = configuration(data, ghidraCallEdges=ghidra_export(data, {0: [(0, 3, "CONDITIONAL_JUMP", falls_through)], 3: []}))
771
+ cfg["regions"][0]["entries"] = [0, 3]
772
+ check = run_report(data, cfg, "callees")["ghidraCrossCheck"]
773
+ [row] = check["edges"]
774
+ self.assertEqual(row["result"], "agreement")
775
+ self.assertEqual(row["ghidraFallsThrough"], falls_through)
776
+ self.assertEqual(check["counts"]["ghidraEndsFunction"], 0 if falls_through else 1)
777
+ self.assertEqual(check["agreed"], falls_through)
778
+ cfg["controls"] = {"ghidraAgreementSites": [0]}
779
+ if falls_through:
780
+ run_report(data, cfg, "callees")
781
+ else:
782
+ with self.assertRaisesRegex(ValueError, "positive control missed: ghidraAgreementSites"):
783
+ run_report(data, cfg, "callees")
784
+
713
785
  def test_a_ghidra_target_at_an_interrupt_or_a_targetless_call_elsewhere_stays_ghidra_only(self):
714
786
  # int 21h; int 10h; nop; call 8; ret. Ghidra resolves the first interrupt to a file offset and the second to an
715
787
  # address without file bytes, and claims a call at the nop.
@@ -731,7 +803,7 @@ class GhidraCrossCheckTests(unittest.TestCase):
731
803
  cfg["regions"][0]["entries"] = [0, 6]
732
804
  r = run_report(data, cfg, "callees")
733
805
  check = r["ghidraCrossCheck"]
734
- self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 0})
806
+ self.assertEqual(check["counts"], {"agreement": 1, "engineOnly": 0, "ghidraOnly": 0, "interrupt": 0, "ghidraEndsFunction": 0})
735
807
  self.assertEqual(check["notCompared"]["omittedEngineRoutes"], [r["omittedRoutes"][0]["id"]])
736
808
  self.assertFalse(check["agreed"])
737
809