scientific-method-engine 4.1.0__tar.gz → 5.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 (69) hide show
  1. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/PKG-INFO +6 -3
  2. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/README.md +5 -2
  3. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/cli.py +5 -3
  5. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +8 -1
  6. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +3 -11
  7. scientific_method_engine-5.0.0/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +79 -0
  8. scientific_method_engine-5.0.0/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +78 -0
  9. scientific_method_engine-5.0.0/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +130 -0
  10. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/argument_frames.py +6 -5
  11. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/effect_order.py +7 -4
  12. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/machine.py +4 -0
  13. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/memory_scopes.py +15 -0
  14. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/pcode_backend.py +2 -2
  15. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/reports.py +27 -10
  16. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/trace.py +16 -4
  17. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/tests/test_memory_scopes.py +41 -8
  18. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/tests/test_oracle.py +19 -2
  19. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/tests/test_pe.py +43 -0
  20. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/tests/test_x86.py +62 -4
  21. scientific_method_engine-4.1.0/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -156
  22. scientific_method_engine-4.1.0/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -168
  23. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/.gitignore +0 -0
  24. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/LICENSE +0 -0
  25. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/__init__.py +0 -0
  26. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/__main__.py +0 -0
  27. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  28. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  29. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  30. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  31. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  32. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  33. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  34. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  35. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  36. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  37. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  38. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  39. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  40. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  41. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  42. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  43. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  44. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  45. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  46. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  47. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  48. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  49. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  50. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  51. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  52. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  53. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  54. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  55. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/image.py +0 -0
  56. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/loops.py +0 -0
  57. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  58. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/pe.py +0 -0
  59. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/relational.py +0 -0
  60. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  61. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/src/scientific_method_engine/x86/values.py +0 -0
  62. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/tests/oracle.py +0 -0
  63. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/tests/test_continuation_budget.py +0 -0
  64. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/tests/test_dispatch.py +0 -0
  65. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/tests/test_effect_order.py +0 -0
  66. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/tests/test_loops.py +0 -0
  67. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/tests/test_nested_frame_request.py +0 -0
  68. {scientific_method_engine-4.1.0 → scientific_method_engine-5.0.0}/tests/test_relational_controls.py +0 -0
  69. {scientific_method_engine-4.1.0 → scientific_method_engine-5.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: 4.1.0
3
+ Version: 5.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
@@ -50,7 +50,10 @@ print to the analyzer log and cap their output. `ReportScalarConstants`, `Report
50
50
  for the other report scripts, a result count equal to the cap means the same.
51
51
  `analyzeHeadless` can exit with code 0 after a script failed to load, so check the log for the
52
52
  script's own result lines ([the Ghidra workflow](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/ghidra-workflow.md)
53
- says what a run must show). The scripts compile against Ghidra 12.1.
53
+ says what a run must show). The scripts compile against Ghidra 12.1. `ReportConstantFirstArgumentCalls`,
54
+ `ReportFirstArgumentCallSummary` and `ReportCallSitesWithScalars` load a shared helper from the
55
+ `scientificmethod/` directory beside them, so pass the directory the command prints as `-scriptPath`,
56
+ or copy that subdirectory along with the scripts.
54
57
 
55
58
  Reading code and data:
56
59
 
@@ -89,7 +92,7 @@ Exporting for comparison (each writes one file and refuses to overwrite where no
89
92
  |---|---|---|
90
93
  | `ExportBoundedFlow` | entry, instruction limit (1..10000), output path under `analysis/original/` | instruction metadata of one bounded flow as JSON |
91
94
  | `ExportFunctionInventory` | output TSV path (must not exist) | every function's start and body size |
92
- | `ExportCallEdges` | output JSON path (must not exist), function limit (1..128), one or more function entries | the call and tail-jump edges of the functions Ghidra reaches breadth-first from the entries, with file offsets, as the `ghidraCallEdges` input of `callees` |
95
+ | `ExportCallEdges` | output JSON path (must not exist), function limit (1..128), one or more function entries | the call and tail-jump edges of the functions Ghidra reaches breadth-first from the entries, with file offsets, Ghidra's flow type (after any flow override) and `fallsThrough` (whether Ghidra continues to the next instruction at the site, after any fall-through override), as the `ghidraCallEdges` input of `callees` |
93
96
  | `ExportFunctionFingerprints` | output TSV path (replaced only when the export completes) | per-function and per-instruction fingerprints with addresses normalized, for matching functions across versions |
94
97
 
95
98
  Repairing the analysis (these change the Ghidra program, so run them before reports and keep the
@@ -34,7 +34,10 @@ print to the analyzer log and cap their output. `ReportScalarConstants`, `Report
34
34
  for the other report scripts, a result count equal to the cap means the same.
35
35
  `analyzeHeadless` can exit with code 0 after a script failed to load, so check the log for the
36
36
  script's own result lines ([the Ghidra workflow](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/ghidra-workflow.md)
37
- says what a run must show). The scripts compile against Ghidra 12.1.
37
+ says what a run must show). The scripts compile against Ghidra 12.1. `ReportConstantFirstArgumentCalls`,
38
+ `ReportFirstArgumentCallSummary` and `ReportCallSitesWithScalars` load a shared helper from the
39
+ `scientificmethod/` directory beside them, so pass the directory the command prints as `-scriptPath`,
40
+ or copy that subdirectory along with the scripts.
38
41
 
39
42
  Reading code and data:
40
43
 
@@ -73,7 +76,7 @@ Exporting for comparison (each writes one file and refuses to overwrite where no
73
76
  |---|---|---|
74
77
  | `ExportBoundedFlow` | entry, instruction limit (1..10000), output path under `analysis/original/` | instruction metadata of one bounded flow as JSON |
75
78
  | `ExportFunctionInventory` | output TSV path (must not exist) | every function's start and body size |
76
- | `ExportCallEdges` | output JSON path (must not exist), function limit (1..128), one or more function entries | the call and tail-jump edges of the functions Ghidra reaches breadth-first from the entries, with file offsets, as the `ghidraCallEdges` input of `callees` |
79
+ | `ExportCallEdges` | output JSON path (must not exist), function limit (1..128), one or more function entries | the call and tail-jump edges of the functions Ghidra reaches breadth-first from the entries, with file offsets, Ghidra's flow type (after any flow override) and `fallsThrough` (whether Ghidra continues to the next instruction at the site, after any fall-through override), as the `ghidraCallEdges` input of `callees` |
77
80
  | `ExportFunctionFingerprints` | output TSV path (replaced only when the export completes) | per-function and per-instruction fingerprints with addresses normalized, for matching functions across versions |
78
81
 
79
82
  Repairing the analysis (these change the Ghidra program, so run them before reports and keep the
@@ -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 = "4.1.0"
8
+ version = "5.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"
@@ -73,9 +73,11 @@ def main(argv):
73
73
  raise ValueError("preparedProtocol is set by the reader and cannot be supplied")
74
74
  data, identity = read_source(config, base)
75
75
  result = run_report(data, config, command)
76
- print(json.dumps({"schema": "bounded-x86-v1", "decoder": DECODER,
77
- "instructionSemantics": INSTRUCTION_SEMANTICS, "sourceIdentity": identity,
78
- "status": "Conditional static report; never promotes an evidence entry", **result}, indent=2))
76
+ report = {"schema": "bounded-x86-v1", "decoder": DECODER, "instructionSemantics": INSTRUCTION_SEMANTICS,
77
+ "sourceIdentity": identity, "status": "Conditional static report; never promotes an evidence entry", **result}
78
+ # The reader parses the prepared path's output and prints it indented itself, so the pipe carries
79
+ # compact JSON and stays within the reader's output cap. A config file run prints for people.
80
+ print(json.dumps(report, separators=(",", ":")) if config_path == "-" else json.dumps(report, indent=2))
79
81
 
80
82
 
81
83
  def run():
@@ -104,12 +104,19 @@ public class ExportCallEdges extends GhidraScript {
104
104
  println("Exported the call edges of " + exported + " functions to " + output);
105
105
  }
106
106
 
107
+ // The flow is Ghidra's flow type after any flow override. fallsThrough is true when Ghidra continues to
108
+ // the next instruction at the site. getFallThrough() reflects a fall-through override, which can clear it
109
+ // or send it to another address; hasFallthrough() stays true for the second, so it is not used.
107
110
  private String edge(Instruction instruction, Address target, FlowType flow) {
111
+ Address fallThrough = instruction.getFallThrough();
112
+ boolean fallsThrough = fallThrough != null
113
+ && fallThrough.equals(instruction.getAddress().addWrap(instruction.getDefaultFallThroughOffset()));
108
114
  return "{\"site\": " + offset(instruction.getAddress())
109
115
  + ", \"siteAddress\": " + quote(instruction.getAddress().toString())
110
116
  + ", \"target\": " + (target == null ? "null" : offset(target))
111
117
  + ", \"targetAddress\": " + (target == null ? "null" : quote(target.toString()))
112
- + ", \"flow\": " + quote(flow.toString()) + "}";
118
+ + ", \"flow\": " + quote(flow.toString())
119
+ + ", \"fallsThrough\": " + fallsThrough + "}";
113
120
  }
114
121
 
115
122
  // The file offset the engine uses for an address, or null when the address has no file bytes.
@@ -14,6 +14,8 @@ import ghidra.program.model.scalar.Scalar;
14
14
  import ghidra.program.model.symbol.Reference;
15
15
  import ghidra.program.model.symbol.ReferenceIterator;
16
16
 
17
+ import scientificmethod.FirstArgumentLookBack;
18
+
17
19
  import java.util.ArrayList;
18
20
  import java.util.HashSet;
19
21
  import java.util.List;
@@ -78,7 +80,7 @@ public class ReportCallSitesWithScalars extends GhidraScript {
78
80
  private List<Instruction> argumentSetup(Instruction call) {
79
81
  List<Instruction> setup = new ArrayList<>();
80
82
  Instruction later = call;
81
- while (setup.size() < PRECEDING_INSTRUCTIONS && !isFlowTarget(later)) {
83
+ while (setup.size() < PRECEDING_INSTRUCTIONS && !FirstArgumentLookBack.isFlowTarget(currentProgram, later)) {
82
84
  Instruction cursor = later.getPrevious();
83
85
  if (cursor == null || !later.getAddress().equals(cursor.getFallThrough())
84
86
  || cursor.getFlowType().isCall()) break;
@@ -88,16 +90,6 @@ public class ReportCallSitesWithScalars extends GhidraScript {
88
90
  return setup;
89
91
  }
90
92
 
91
- // A function entry counts too: a callback or table entry reaches it without a reference Ghidra recorded.
92
- private boolean isFlowTarget(Instruction instruction) {
93
- if (currentProgram.getFunctionManager().getFunctionAt(instruction.getAddress()) != null) return true;
94
- ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(instruction.getAddress());
95
- while (references.hasNext()) {
96
- if (references.next().getReferenceType().isFlow()) return true;
97
- }
98
- return false;
99
- }
100
-
101
93
  // Ghidra types an immediate operand SCALAR, adding ADDRESS when it points into the program
102
94
  // (PUSH 0x41c000). A memory operand is never SCALAR: a displacement makes it DYNAMIC, and an
103
95
  // absolute one such as PUSH [0x41c000] is ADDRESS with its address as the scalar object.
@@ -0,0 +1,79 @@
1
+ // Reports direct x86 cdecl calls whose first argument is one requested constant.
2
+ // The first argument is the nearest PUSH before the call. Instructions between them are passed over
3
+ // only when they fall through, are not a flow target and write neither the stack pointer nor
4
+ // memory addressed through it or through a register copied from it after the PUSH (MOV [ESP],EAX;
5
+ // LEA EAX,[ESP] then MOV [EAX],ECX), as in "PUSH 5; MOV ECX,ESI; CALL".
6
+ // @category Restoration
7
+
8
+ import ghidra.app.script.GhidraScript;
9
+ import ghidra.program.model.address.Address;
10
+ import ghidra.program.model.lang.OperandType;
11
+ import ghidra.program.model.listing.Function;
12
+ import ghidra.program.model.listing.Instruction;
13
+ import ghidra.program.model.scalar.Scalar;
14
+ import ghidra.program.model.symbol.Reference;
15
+ import ghidra.program.model.symbol.ReferenceIterator;
16
+
17
+ import scientificmethod.FirstArgumentLookBack;
18
+
19
+ public class ReportConstantFirstArgumentCalls extends GhidraScript {
20
+ private static final int MAX_CALLS = 300;
21
+
22
+ @Override
23
+ protected void run() throws Exception {
24
+ String[] arguments = getScriptArgs();
25
+ if (arguments.length != 2) {
26
+ printerr("Supply a callee virtual address and constant first argument.");
27
+ return;
28
+ }
29
+
30
+ Address callee = toAddr(arguments[0]);
31
+ long requested = Long.decode(arguments[1]);
32
+ FirstArgumentLookBack lookBack = new FirstArgumentLookBack(currentProgram);
33
+ ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(callee);
34
+ int matches = 0;
35
+ int calls = 0;
36
+ int unknown = 0;
37
+ boolean capped = false;
38
+ while (references.hasNext()) {
39
+ monitor.checkCancelled();
40
+ Reference reference = references.next();
41
+ Instruction call = currentProgram.getListing().getInstructionAt(reference.getFromAddress());
42
+ if (call == null || !call.getFlowType().isCall()) continue;
43
+ calls++;
44
+ Instruction firstPush = lookBack.firstArgumentPush(call);
45
+ if (firstPush == null) unknown++;
46
+ if (!isPushOf(firstPush, requested)) continue;
47
+ if (matches >= MAX_CALLS) {
48
+ capped = true;
49
+ break;
50
+ }
51
+
52
+ Function function = currentProgram.getFunctionManager().getFunctionContaining(call.getAddress());
53
+ Instruction secondPush = firstPush.getPrevious();
54
+ println(call.getAddress()
55
+ + (function == null ? "" : " in " + function.getEntryPoint() + " " + function.getName())
56
+ + " first=" + firstPush
57
+ + (secondPush == null ? "" : " preceding=" + secondPush));
58
+ matches++;
59
+ }
60
+
61
+ println("Matched calls: " + matches);
62
+ if (capped) println("Output capped at " + MAX_CALLS + " calls; the scan did not finish.");
63
+ else println("Calls read: " + calls + ", of which " + unknown + " have no PUSH known to supply the "
64
+ + "first argument (see ReportFirstArgumentCallSummary).");
65
+ }
66
+
67
+ // Only an immediate operand is a literal; PUSH [EBP+8] carries the scalar 8 as a displacement.
68
+ // Ghidra types an immediate operand SCALAR, adding ADDRESS when it points into the program
69
+ // (PUSH 0x41c000). A memory operand is never SCALAR: an absolute one such as PUSH [0x41c000] is
70
+ // ADDRESS with its address as the scalar object.
71
+ private static boolean isPushOf(Instruction instruction, long requested) {
72
+ if (instruction == null || !OperandType.isScalar(instruction.getOperandType(0))) return false;
73
+ for (Object object : instruction.getOpObjects(0)) {
74
+ if (object instanceof Scalar scalar
75
+ && scalar.getUnsignedValue() == requested) return true;
76
+ }
77
+ return false;
78
+ }
79
+ }
@@ -0,0 +1,78 @@
1
+ // Summarizes immediate x86 cdecl first arguments at every direct call to one function.
2
+ // The first argument is the nearest PUSH before the call. Instructions between them are passed over
3
+ // only when they fall through, are not a flow target and write neither the stack pointer nor
4
+ // memory addressed through it or through a register copied from it after the PUSH (MOV [ESP],EAX;
5
+ // LEA EAX,[ESP] then MOV [EAX],ECX), as in "PUSH 5; MOV ECX,ESI; CALL". Calls without such a
6
+ // literal PUSH are listed with the reason.
7
+ // @category Restoration
8
+
9
+ import java.util.Map;
10
+ import java.util.TreeMap;
11
+
12
+ import ghidra.app.script.GhidraScript;
13
+ import ghidra.program.model.address.Address;
14
+ import ghidra.program.model.lang.OperandType;
15
+ import ghidra.program.model.listing.Function;
16
+ import ghidra.program.model.listing.Instruction;
17
+ import ghidra.program.model.scalar.Scalar;
18
+ import ghidra.program.model.symbol.Reference;
19
+ import ghidra.program.model.symbol.ReferenceIterator;
20
+
21
+ import scientificmethod.FirstArgumentLookBack;
22
+
23
+ public class ReportFirstArgumentCallSummary extends GhidraScript {
24
+ @Override
25
+ protected void run() throws Exception {
26
+ String[] arguments = getScriptArgs();
27
+ if (arguments.length != 1) {
28
+ printerr("Supply one callee virtual address.");
29
+ return;
30
+ }
31
+
32
+ Address callee = toAddr(arguments[0]);
33
+ FirstArgumentLookBack lookBack = new FirstArgumentLookBack(currentProgram);
34
+ ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(callee);
35
+ Map<Long, Integer> literals = new TreeMap<>();
36
+ int calls = 0;
37
+ int nonLiteral = 0;
38
+ while (references.hasNext()) {
39
+ monitor.checkCancelled();
40
+ Reference reference = references.next();
41
+ Instruction call = currentProgram.getListing().getInstructionAt(reference.getFromAddress());
42
+ if (call == null || !call.getFlowType().isCall()) continue;
43
+ calls++;
44
+
45
+ StringBuilder reason = new StringBuilder();
46
+ Instruction push = lookBack.firstArgumentPush(call, reason);
47
+ Long literal = pushedLiteral(push);
48
+ if (literal != null) {
49
+ literals.merge(literal, 1, Integer::sum);
50
+ continue;
51
+ }
52
+
53
+ nonLiteral++;
54
+ Function function = currentProgram.getFunctionManager().getFunctionContaining(call.getAddress());
55
+ println("Non-literal at " + call.getAddress()
56
+ + (function == null ? "" : " in " + function.getEntryPoint() + " " + function.getName())
57
+ + " first=" + (push == null ? "<none> (" + reason + ")" : push.toString())
58
+ + " preceding=" + (call.getPrevious() == null ? "<none>" : call.getPrevious()));
59
+ }
60
+
61
+ println("Direct calls: " + calls);
62
+ for (Map.Entry<Long, Integer> entry : literals.entrySet())
63
+ println("Literal " + entry.getKey() + ": " + entry.getValue());
64
+ println("Non-literal: " + nonLiteral);
65
+ }
66
+
67
+ // Only an immediate operand is a literal; PUSH [EBP+8] carries the scalar 8 as a displacement.
68
+ // Ghidra types an immediate operand SCALAR, adding ADDRESS when it points into the program
69
+ // (PUSH 0x41c000). A memory operand is never SCALAR: an absolute one such as PUSH [0x41c000] is
70
+ // ADDRESS with its address as the scalar object.
71
+ private static Long pushedLiteral(Instruction instruction) {
72
+ if (instruction == null || !OperandType.isScalar(instruction.getOperandType(0))) return null;
73
+ for (Object object : instruction.getOpObjects(0)) {
74
+ if (object instanceof Scalar scalar) return scalar.getUnsignedValue();
75
+ }
76
+ return null;
77
+ }
78
+ }
@@ -0,0 +1,130 @@
1
+ package scientificmethod;
2
+
3
+ import java.util.ArrayList;
4
+ import java.util.HashSet;
5
+ import java.util.List;
6
+ import java.util.Set;
7
+
8
+ import ghidra.program.model.lang.Register;
9
+ import ghidra.program.model.listing.Instruction;
10
+ import ghidra.program.model.listing.Program;
11
+ import ghidra.program.model.pcode.PcodeOp;
12
+ import ghidra.program.model.pcode.Varnode;
13
+ import ghidra.program.model.symbol.ReferenceIterator;
14
+
15
+ /**
16
+ * The x86 cdecl first-argument look-back that ReportConstantFirstArgumentCalls and
17
+ * ReportFirstArgumentCallSummary share, so both apply one rule. ReportCallSitesWithScalars uses its
18
+ * isFlowTarget to end the argument setup it prints. It lives in a package directory
19
+ * beside the scripts, as Ghidra's own classrecovery helpers do, so Ghidra compiles it with them and
20
+ * the Script Manager does not list it as a script.
21
+ */
22
+ public final class FirstArgumentLookBack {
23
+ /** The most instructions passed over between the first argument's PUSH and the call. */
24
+ public static final int MAX_PASSED_OVER = 8;
25
+
26
+ private final Program program;
27
+ private final Register stackPointer;
28
+
29
+ /** A look-back over one program, using its compiler's stack pointer. */
30
+ public FirstArgumentLookBack(Program program) {
31
+ this.program = program;
32
+ this.stackPointer = program.getCompilerSpec().getStackPointer().getBaseRegister();
33
+ }
34
+
35
+ /** The nearest PUSH before the call, or null when none is known to supply the first argument. */
36
+ public Instruction firstArgumentPush(Instruction call) {
37
+ return firstArgumentPush(call, new StringBuilder());
38
+ }
39
+
40
+ /**
41
+ * The nearest PUSH before the call, or null with the reason appended to {@code reason} when none
42
+ * is known to supply the first argument. Instructions between them are passed over only when they
43
+ * fall through, are not a flow target and write neither the stack pointer nor memory addressed
44
+ * through it or through a register copied from it after the PUSH.
45
+ */
46
+ public Instruction firstArgumentPush(Instruction call, StringBuilder reason) {
47
+ List<Instruction> passedOver = new ArrayList<>();
48
+ Instruction later = call;
49
+ for (int passed = 0; passed <= MAX_PASSED_OVER; passed++) {
50
+ if (isFlowTarget(program, later)) {
51
+ reason.append(later.getAddress()).append(" is a function entry or a jump or call target");
52
+ return null;
53
+ }
54
+ Instruction cursor = later.getPrevious();
55
+ if (cursor == null || !later.getAddress().equals(cursor.getFallThrough())) {
56
+ reason.append("no instruction falls through to ").append(later.getAddress());
57
+ return null;
58
+ }
59
+ if ("PUSH".equals(cursor.getMnemonicString())) {
60
+ Instruction store = storeThroughStack(passedOver);
61
+ if (store == null) return cursor;
62
+ reason.append(store.getAddress()).append(" ").append(store).append(" writes stack memory");
63
+ return null;
64
+ }
65
+ if (cursor.getFlowType().isCall() || writes(cursor, stackPointer)) {
66
+ reason.append(cursor.getAddress()).append(" ").append(cursor).append(" changes the stack");
67
+ return null;
68
+ }
69
+ passedOver.add(cursor);
70
+ later = cursor;
71
+ }
72
+ reason.append("no PUSH among the ").append(MAX_PASSED_OVER + 1).append(" instructions before the call");
73
+ return null;
74
+ }
75
+
76
+ /**
77
+ * Whether a jump or call reaches the instruction. A function entry counts too: a callback or table
78
+ * entry reaches it without a reference Ghidra recorded.
79
+ */
80
+ public static boolean isFlowTarget(Program program, Instruction instruction) {
81
+ if (program.getFunctionManager().getFunctionAt(instruction.getAddress()) != null) return true;
82
+ ReferenceIterator references = program.getReferenceManager().getReferencesTo(instruction.getAddress());
83
+ while (references.hasNext()) {
84
+ if (references.next().getReferenceType().isFlow()) return true;
85
+ }
86
+ return false;
87
+ }
88
+
89
+ private static boolean writes(Instruction instruction, Register register) {
90
+ for (Object object : instruction.getResultObjects()) {
91
+ if (object instanceof Register written && written.getBaseRegister().equals(register)) return true;
92
+ }
93
+ return false;
94
+ }
95
+
96
+ // The first of the passed-over instructions (listed nearest the call first) that stores to an address
97
+ // computed from the stack pointer, such as MOV [ESP],EAX, or through a register an earlier one copied
98
+ // it into (LEA EAX,[ESP]; MOV [EAX],ECX). Either can overwrite the pushed argument. Ghidra lists no
99
+ // result object for a memory destination, so the p-code is read instead, in execution order.
100
+ private Instruction storeThroughStack(List<Instruction> passedOver) {
101
+ Set<Varnode> fromStack = new HashSet<>();
102
+ for (int index = passedOver.size() - 1; index >= 0; index--) {
103
+ Instruction instruction = passedOver.get(index);
104
+ for (PcodeOp op : instruction.getPcode()) {
105
+ if (op.getOpcode() == PcodeOp.STORE) {
106
+ if (isFromStack(op.getInput(1), fromStack)) return instruction;
107
+ continue;
108
+ }
109
+ Varnode output = op.getOutput();
110
+ if (output == null) continue;
111
+ // A LOAD's address may come from the stack pointer, but the value it reads does not.
112
+ boolean derived = false;
113
+ if (op.getOpcode() != PcodeOp.LOAD) {
114
+ for (Varnode input : op.getInputs()) derived |= isFromStack(input, fromStack);
115
+ }
116
+ if (derived) fromStack.add(output);
117
+ else fromStack.remove(output);
118
+ }
119
+ fromStack.removeIf(Varnode::isUnique); // p-code temporaries do not outlive their instruction
120
+ }
121
+ return null;
122
+ }
123
+
124
+ private boolean isFromStack(Varnode varnode, Set<Varnode> fromStack) {
125
+ if (fromStack.contains(varnode)) return true;
126
+ if (!varnode.isRegister()) return false;
127
+ Register register = program.getRegister(varnode.getAddress(), varnode.getSize());
128
+ return register != null && register.getBaseRegister().equals(stackPointer);
129
+ }
130
+ }
@@ -8,6 +8,7 @@ amount never join or split slots. Whatever a read did not settle on the path sta
8
8
  from capstone.x86 import X86_OP_IMM, X86_OP_REG
9
9
 
10
10
  from .machine import may_alias, written_domain
11
+ from .memory_scopes import model_scopes
11
12
 
12
13
  # The argument bytes one frame maps; a wider frame is mapped up to here and stays open.
13
14
  WINDOW_BYTES = 256
@@ -33,7 +34,7 @@ def _covered(event, segment, base, start, width, modulus):
33
34
  return [at for at in offsets if 0 <= at < width]
34
35
 
35
36
 
36
- def _writers(events, before, segment, base, start, width, modulus, image):
37
+ def _writers(events, before, segment, base, start, width, modulus, image, models):
37
38
  """The last write before index `before` that covered each frame byte, and why each byte without one has none.
38
39
 
39
40
  A modeled call drops every byte outside its `preservesMemory` scopes. Scopes name linear bytes,
@@ -56,7 +57,7 @@ def _writers(events, before, segment, base, start, width, modulus, image):
56
57
  if event["kind"] == "call-return" and event.get("unknownMemoryEffects"):
57
58
  kept = set()
58
59
  if segment == ("linear",):
59
- kept = {at for scope in event.get("preservedMemoryScopes") or ()
60
+ kept = {at for scope in model_scopes(models, event)
60
61
  for at in range(scope["linearStart"], scope["linearEnd"])}
61
62
  for at in range(width):
62
63
  if at not in writers and at not in invalidated and start + at not in kept:
@@ -69,7 +70,7 @@ def _writers(events, before, segment, base, start, width, modulus, image):
69
70
  return writers, {at: invalidated.get(at, "no write on this path") for at in range(width) if at not in writers}
70
71
 
71
72
 
72
- def _frame(image, events, index):
73
+ def _frame(image, events, index, models):
73
74
  call = events[index]
74
75
  depth = call["depth"]
75
76
  pushes = [e for e in events[index + 1:index + 3] if e["kind"] == "write" and e.get("role") == "push" and e["site"] == call["site"]]
@@ -105,7 +106,7 @@ def _frame(image, events, index):
105
106
 
106
107
  # Slots: runs of argument bytes that one write event last covered.
107
108
  slots, by_byte = [], {}
108
- writers, reasons = _writers(events, index, segment, base, start, width, modulus, image)
109
+ writers, reasons = _writers(events, index, segment, base, start, width, modulus, image, models)
109
110
  for at in range(width):
110
111
  writer = writers.get(at)
111
112
  key = writer["order"] if writer else reasons[at]
@@ -193,7 +194,7 @@ def argument_frames(report, image):
193
194
  sites = {}
194
195
  for path_index, path in enumerate(report["paths"]):
195
196
  events = path["events"]
196
- frames = [_frame(image, events, i) for i, e in enumerate(events) if e["kind"] == "call" and "returnFrameBytes" in e]
197
+ frames = [_frame(image, events, i, path["conditionalModels"]) for i, e in enumerate(events) if e["kind"] == "call" and "returnFrameBytes" in e]
197
198
  path["argumentFrames"] = [f for f in frames if f is not None]
198
199
  for frame in path["argumentFrames"]:
199
200
  sites.setdefault(frame["callSite"], []).append((path_index, frame))
@@ -1,6 +1,8 @@
1
1
  """Ordered, path-local effect evidence; no transactional or native-execution claims."""
2
2
  from bisect import bisect_right
3
3
 
4
+ from .memory_scopes import model_scopes, without_scopes
5
+
4
6
 
5
7
  KINDS = {"read", "write", "call", "call-return", "return", "branch", "compare", "flag-assumption",
6
8
  "arithmetic", "value-transfer", "conversion", "flag-write", "flags-save", "flags-restore", "local-iret", "string-operation", "declared-jump-continuation",
@@ -63,7 +65,7 @@ def effect_ordering(report):
63
65
  call = {"order": event["order"], "site": event["site"], "entry": event["entry"],
64
66
  "depth": event["depth"], "target": event.get("target"),
65
67
  "writesBeforeCount": len(writes), "status": "unresolved-or-stopped",
66
- "unknownEffects": True, "continuation": None, "preservedMemoryScopes": [],
68
+ "unknownEffects": True, "continuation": None, "conditionalModel": None,
67
69
  "_unknownStart": len(unknown_orders)}
68
70
  calls.append(call)
69
71
  pending.setdefault((event["site"], event["depth"]), []).append(call)
@@ -72,10 +74,10 @@ def effect_ordering(report):
72
74
  if stack:
73
75
  call = stack.pop()
74
76
  modeled = event.get("modeled", False)
75
- scopes = event.get("preservedMemoryScopes", []) if modeled else []
77
+ scopes = model_scopes(path.get("conditionalModels", []), event) if modeled else []
76
78
  call.update(status="modeled-return" if modeled else "traced-return",
77
79
  unknownEffects=bool(modeled or event.get("unknownMemoryEffects") or len(unknown_orders) > call.pop("_unknownStart")),
78
- returnOrder=event["order"], writesAfterCount=len(writes), preservedMemoryScopes=scopes,
80
+ returnOrder=event["order"], writesAfterCount=len(writes), conditionalModel=event.get("conditionalModel") if modeled else None,
79
81
  continuation="local callee return reached within the instruction model" if not modeled
80
82
  else "assumes balanced returning service; memory outside its preservedMemoryScopes "
81
83
  "hypotheses and its flag effects are unknown" if scopes
@@ -91,7 +93,8 @@ def effect_ordering(report):
91
93
  destination = conditional_summaries if conditional else summaries
92
94
  destination.append({"path": index, "declaredJumpAssumptions": path.get("declaredJumpAssumptions", []), "returned": path["returned"], "stop": boundary,
93
95
  "guards": path["guards"], "timeline": timeline,
94
- "conditionalModels": path.get("conditionalModels", []),
96
+ # Same entries and order as the path's conditionalModels; the scopes stay there.
97
+ "conditionalModels": without_scopes(path.get("conditionalModels", [])),
95
98
  "writeOrders": [w["order"] for w in writes], "calls": calls,
96
99
  "localRestorationWitnesses": witnesses,
97
100
  # Port and interrupt effects stay out of writeOrders: RAM writes never stand for device state.
@@ -18,6 +18,10 @@ class StopPath(Exception):
18
18
  pass
19
19
 
20
20
 
21
+ # Why a port access ends what the flat model can follow: trace stops after its event, and walk records a gap.
22
+ FLAT_PORT_REASON = "port access in the flat model depends on I/O privilege, which is not modeled"
23
+
24
+
21
25
  # The write-log key that marks a point where the model forgot all memory.
22
26
  MEMORY_CLEARED = ("memory-cleared",)
23
27
 
@@ -113,3 +113,18 @@ def retain_scopes(state, values, unread, history):
113
113
  state.lost_memory.update(history[1])
114
114
  if values or unread:
115
115
  state.memory_groups.setdefault((("linear",), ("absolute",)), set()).update(values, unread)
116
+
117
+
118
+ def model_scopes(models, event):
119
+ """The ``preservedMemoryScopes`` of the conditional model that a modeled ``call-return`` event cites.
120
+
121
+ ``models`` is the path's ``conditionalModels`` list. The event's ``conditionalModel`` is an
122
+ index into that list; an event without one (a traced return, or any other kind) yields ``[]``.
123
+ """
124
+ index = event.get("conditionalModel")
125
+ return [] if index is None else models[index].get("preservedMemoryScopes", [])
126
+
127
+
128
+ def without_scopes(models):
129
+ """Copies of a path's ``conditionalModels`` entries without ``preservedMemoryScopes``, in the same order."""
130
+ return [{k: v for k, v in m.items() if k != "preservedMemoryScopes"} if isinstance(m, dict) else m for m in models]
@@ -21,7 +21,7 @@ object, so a value this module stores must live on the ``State`` to be copied wi
21
21
  """
22
22
  from capstone.x86 import X86_OP_REG, X86_OP_IMM, X86_OP_MEM
23
23
 
24
- from .machine import ALIASES, StopPath
24
+ from .machine import ALIASES, StopPath, FLAT_PORT_REASON
25
25
  from .pcode import LIFTER, Address, Run, FLAGS, SEGMENT_BASES, segment_base
26
26
  from .values import Value, const, unknown, op, extract, join, resize, sources
27
27
 
@@ -945,7 +945,7 @@ def port_access(state, ins, direction, port, value, size):
945
945
  state.conditional.append(assumption)
946
946
  state.event("hardware-boundary", **fields, value=result.report(), interpretation=INPUT_MEANING)
947
947
  if state.flat:
948
- raise StopPath("port access in the flat model depends on I/O privilege, which is not modeled")
948
+ raise StopPath(FLAT_PORT_REASON)
949
949
  return result
950
950
 
951
951