scientific-method-engine 2.3.0__tar.gz → 3.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 (66) hide show
  1. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/PKG-INFO +17 -12
  2. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/README.md +16 -11
  3. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +20 -10
  5. scientific_method_engine-3.0.0/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +122 -0
  6. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +35 -19
  7. scientific_method_engine-3.0.0/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +156 -0
  8. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +12 -2
  9. scientific_method_engine-3.0.0/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +168 -0
  10. scientific_method_engine-3.0.0/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +119 -0
  11. scientific_method_engine-3.0.0/src/scientific_method_engine/ghidra/ReportScalarConstants.java +78 -0
  12. scientific_method_engine-2.3.0/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -95
  13. scientific_method_engine-2.3.0/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -55
  14. scientific_method_engine-2.3.0/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -63
  15. scientific_method_engine-2.3.0/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -64
  16. scientific_method_engine-2.3.0/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -55
  17. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/.gitignore +0 -0
  18. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/LICENSE +0 -0
  19. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/__init__.py +0 -0
  20. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/__main__.py +0 -0
  21. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/cli.py +0 -0
  22. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  23. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  24. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  25. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  26. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  27. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  28. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  29. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  30. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  31. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  32. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  33. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  34. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  35. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  36. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  37. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  38. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  39. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  40. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  41. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  42. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  43. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  44. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  45. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  46. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  47. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  48. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/image.py +0 -0
  49. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/machine.py +0 -0
  50. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  51. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  52. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  53. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/pe.py +0 -0
  54. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/reports.py +0 -0
  55. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  56. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/trace.py +0 -0
  57. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/src/scientific_method_engine/x86/values.py +0 -0
  58. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/tests/oracle.py +0 -0
  59. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/tests/test_dispatch.py +0 -0
  60. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/tests/test_effect_order.py +0 -0
  61. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/tests/test_memory_scopes.py +0 -0
  62. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/tests/test_nested_frame_request.py +0 -0
  63. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/tests/test_oracle.py +0 -0
  64. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/tests/test_pe.py +0 -0
  65. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/tests/test_table_continuations.py +0 -0
  66. {scientific_method_engine-2.3.0 → scientific_method_engine-3.0.0}/tests/test_x86.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 2.3.0
3
+ Version: 3.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
@@ -45,7 +45,12 @@ ghidra-scripts` prints their directory, for Ghidra's `-scriptPath`:
45
45
  ```
46
46
 
47
47
  Addresses are Ghidra addresses (`0x00401000`, or `1028:d820` for segmented programs). Report scripts
48
- print to the analyzer log and cap their output. The scripts compile against Ghidra 12.1.
48
+ print to the analyzer log and cap their output. `ReportScalarConstants`, `ReportCallsToRange`,
49
+ `ReportConstantFirstArgumentCalls` and `ReportCallSitesWithScalars` say when a cap stopped their scan;
50
+ for the other report scripts, a result count equal to the cap means the same.
51
+ `analyzeHeadless` can exit with code 0 after a script failed to load, so check the log for the
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.
49
54
 
50
55
  Reading code and data:
51
56
 
@@ -54,8 +59,8 @@ Reading code and data:
54
59
  | `ReportInstructionContext` | one or more instruction addresses | a bounded instruction window around each |
55
60
  | `ReportInstructionWindow` | address, instruction count | instructions from the address onward |
56
61
  | `ReportDataBytes` | address, byte count (1..256) | the bytes at the address |
57
- | `ReportFunctionSummary` | one or more addresses | focused decompiler output of each containing function |
58
- | `ReportDecompileWindow` | address, first line (1-based), line count | a window of one function's decompilation |
62
+ | `ReportFunctionSummary` | one or more addresses | focused decompiler output of each containing function, its body ranges and each call without a fall-through (a sign of a wrong no-return flag), then the addresses with no function or a failed decompile |
63
+ | `ReportDecompileWindow` | address, first line (1-based), line count (a count above 160 is cut to 160) | a window of one function's decompilation, its total line count and where the next window starts |
59
64
  | `ReportDecompileMatches` | address, one or more literal text patterns | decompilation lines around each match |
60
65
  | `ReportMemoryBlocks` | nothing, `page <start> <count>`, or `name <exact-name>` | memory block indexes, names, ranges and sizes, never bytes |
61
66
  | `ReportFilePatternInMemory` | file offset (hex), optional pattern length (default 8) | where the bytes at that file offset occur in loaded memory |
@@ -67,14 +72,14 @@ Finding references and calls:
67
72
  |---|---|---|
68
73
  | `ReportReferences` | one or more addresses | references to each, with the referring instruction and function |
69
74
  | `ReportStringReferences` | one or more literal string fragments | strings containing a fragment and their references |
70
- | `ReportSymbolReferences` | one or more symbol-name fragments | matching symbols and their references |
71
- | `ReportScalarConstants` | one or more scalar values | instructions using any of them, unsigned or signed |
75
+ | `ReportSymbolReferences` | one or more symbol-name fragments, matched as case-insensitive substrings of the full name | matching symbols, default labels included, and their references. Default labels end in their address, so an address fragment such as `0089d4a4` finds the `PTR_<name>_0089d4a4` import slot there |
76
+ | `ReportScalarConstants` | optional operand kind (`immediate` or `memory`), one or more scalar values | instructions using any of them, unsigned or signed, as an immediate or inside a memory operand (a displacement such as `[ECX + 0x44]`, an absolute address such as `[0x41c000]`, or an index scale), with the kind on each line |
72
77
  | `ReportFunctionScalarConstants` | function address, one or more scalar values | instructions inside one function using any of them, compared unsigned |
73
- | `ReportCallArguments` | callee address | the three nearest pushed arguments at every direct call |
74
- | `ReportCallSitesWithScalars` | callee address, one or more scalar values | calls whose argument setup contains a requested value |
75
- | `ReportConstantFirstArgumentCalls` | callee address, constant | cdecl calls whose first argument is the constant |
76
- | `ReportFirstArgumentCallSummary` | callee address | the literal first argument of every call, and calls without one |
77
- | `ReportCallsToRange` | start address, end address (inclusive) | calls and jumps whose target lies in the range |
78
+ | `ReportCallArguments` | callee address | the three nearest pushed arguments at every call Ghidra references to the callee |
79
+ | `ReportCallSitesWithScalars` | callee address, one or more scalar values | calls whose argument setup contains a requested value as an immediate, never as a memory-operand displacement or address. The setup is up to 12 instructions that fall through to the call, ending after a function entry or a jump or call target, and before an earlier call. Then the counts or the cap |
80
+ | `ReportConstantFirstArgumentCalls` | callee address, constant | cdecl calls whose first argument is the constant: the nearest `PUSH` before the call, past instructions that fall through, are no function entry or jump or call target, and write neither the stack pointer nor memory addressed through it. Only calls Ghidra references to the callee are read |
81
+ | `ReportFirstArgumentCallSummary` | callee address | the literal first argument of every call, read as in `ReportConstantFirstArgumentCalls`, and each call without one with the reason |
82
+ | `ReportCallsToRange` | start address, end address (inclusive), optional kind (`all`, `calls` or `jumps`; default `all`) | calls and jumps whose target lies in the range, each labelled `[call]` or `[jump]`, then the counts or the cap |
78
83
  | `ReportCallPaths` | start function, target function, maximum depth | direct-call paths between the two |
79
84
  | `ReportRandomnessCandidates` | none | references to C runtime and Windows random and timing functions |
80
85
 
@@ -85,7 +90,7 @@ Exporting for comparison (each writes one file and refuses to overwrite where no
85
90
  | `ExportBoundedFlow` | entry, instruction limit (1..10000), output path under `analysis/original/` | instruction metadata of one bounded flow as JSON |
86
91
  | `ExportFunctionInventory` | output TSV path (must not exist) | every function's start and body size |
87
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` |
88
- | `ExportFunctionFingerprints` | output TSV path | per-function and per-instruction fingerprints with addresses normalized, for matching functions across versions |
93
+ | `ExportFunctionFingerprints` | output TSV path (replaced only when the export completes) | per-function and per-instruction fingerprints with addresses normalized, for matching functions across versions |
89
94
 
90
95
  Repairing the analysis (these change the Ghidra program, so run them before reports and keep the
91
96
  argument lists with the evidence that justifies them):
@@ -29,7 +29,12 @@ ghidra-scripts` prints their directory, for Ghidra's `-scriptPath`:
29
29
  ```
30
30
 
31
31
  Addresses are Ghidra addresses (`0x00401000`, or `1028:d820` for segmented programs). Report scripts
32
- print to the analyzer log and cap their output. The scripts compile against Ghidra 12.1.
32
+ print to the analyzer log and cap their output. `ReportScalarConstants`, `ReportCallsToRange`,
33
+ `ReportConstantFirstArgumentCalls` and `ReportCallSitesWithScalars` say when a cap stopped their scan;
34
+ for the other report scripts, a result count equal to the cap means the same.
35
+ `analyzeHeadless` can exit with code 0 after a script failed to load, so check the log for the
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.
33
38
 
34
39
  Reading code and data:
35
40
 
@@ -38,8 +43,8 @@ Reading code and data:
38
43
  | `ReportInstructionContext` | one or more instruction addresses | a bounded instruction window around each |
39
44
  | `ReportInstructionWindow` | address, instruction count | instructions from the address onward |
40
45
  | `ReportDataBytes` | address, byte count (1..256) | the bytes at the address |
41
- | `ReportFunctionSummary` | one or more addresses | focused decompiler output of each containing function |
42
- | `ReportDecompileWindow` | address, first line (1-based), line count | a window of one function's decompilation |
46
+ | `ReportFunctionSummary` | one or more addresses | focused decompiler output of each containing function, its body ranges and each call without a fall-through (a sign of a wrong no-return flag), then the addresses with no function or a failed decompile |
47
+ | `ReportDecompileWindow` | address, first line (1-based), line count (a count above 160 is cut to 160) | a window of one function's decompilation, its total line count and where the next window starts |
43
48
  | `ReportDecompileMatches` | address, one or more literal text patterns | decompilation lines around each match |
44
49
  | `ReportMemoryBlocks` | nothing, `page <start> <count>`, or `name <exact-name>` | memory block indexes, names, ranges and sizes, never bytes |
45
50
  | `ReportFilePatternInMemory` | file offset (hex), optional pattern length (default 8) | where the bytes at that file offset occur in loaded memory |
@@ -51,14 +56,14 @@ Finding references and calls:
51
56
  |---|---|---|
52
57
  | `ReportReferences` | one or more addresses | references to each, with the referring instruction and function |
53
58
  | `ReportStringReferences` | one or more literal string fragments | strings containing a fragment and their references |
54
- | `ReportSymbolReferences` | one or more symbol-name fragments | matching symbols and their references |
55
- | `ReportScalarConstants` | one or more scalar values | instructions using any of them, unsigned or signed |
59
+ | `ReportSymbolReferences` | one or more symbol-name fragments, matched as case-insensitive substrings of the full name | matching symbols, default labels included, and their references. Default labels end in their address, so an address fragment such as `0089d4a4` finds the `PTR_<name>_0089d4a4` import slot there |
60
+ | `ReportScalarConstants` | optional operand kind (`immediate` or `memory`), one or more scalar values | instructions using any of them, unsigned or signed, as an immediate or inside a memory operand (a displacement such as `[ECX + 0x44]`, an absolute address such as `[0x41c000]`, or an index scale), with the kind on each line |
56
61
  | `ReportFunctionScalarConstants` | function address, one or more scalar values | instructions inside one function using any of them, compared unsigned |
57
- | `ReportCallArguments` | callee address | the three nearest pushed arguments at every direct call |
58
- | `ReportCallSitesWithScalars` | callee address, one or more scalar values | calls whose argument setup contains a requested value |
59
- | `ReportConstantFirstArgumentCalls` | callee address, constant | cdecl calls whose first argument is the constant |
60
- | `ReportFirstArgumentCallSummary` | callee address | the literal first argument of every call, and calls without one |
61
- | `ReportCallsToRange` | start address, end address (inclusive) | calls and jumps whose target lies in the range |
62
+ | `ReportCallArguments` | callee address | the three nearest pushed arguments at every call Ghidra references to the callee |
63
+ | `ReportCallSitesWithScalars` | callee address, one or more scalar values | calls whose argument setup contains a requested value as an immediate, never as a memory-operand displacement or address. The setup is up to 12 instructions that fall through to the call, ending after a function entry or a jump or call target, and before an earlier call. Then the counts or the cap |
64
+ | `ReportConstantFirstArgumentCalls` | callee address, constant | cdecl calls whose first argument is the constant: the nearest `PUSH` before the call, past instructions that fall through, are no function entry or jump or call target, and write neither the stack pointer nor memory addressed through it. Only calls Ghidra references to the callee are read |
65
+ | `ReportFirstArgumentCallSummary` | callee address | the literal first argument of every call, read as in `ReportConstantFirstArgumentCalls`, and each call without one with the reason |
66
+ | `ReportCallsToRange` | start address, end address (inclusive), optional kind (`all`, `calls` or `jumps`; default `all`) | calls and jumps whose target lies in the range, each labelled `[call]` or `[jump]`, then the counts or the cap |
62
67
  | `ReportCallPaths` | start function, target function, maximum depth | direct-call paths between the two |
63
68
  | `ReportRandomnessCandidates` | none | references to C runtime and Windows random and timing functions |
64
69
 
@@ -69,7 +74,7 @@ Exporting for comparison (each writes one file and refuses to overwrite where no
69
74
  | `ExportBoundedFlow` | entry, instruction limit (1..10000), output path under `analysis/original/` | instruction metadata of one bounded flow as JSON |
70
75
  | `ExportFunctionInventory` | output TSV path (must not exist) | every function's start and body size |
71
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` |
72
- | `ExportFunctionFingerprints` | output TSV path | per-function and per-instruction fingerprints with addresses normalized, for matching functions across versions |
77
+ | `ExportFunctionFingerprints` | output TSV path (replaced only when the export completes) | per-function and per-instruction fingerprints with addresses normalized, for matching functions across versions |
73
78
 
74
79
  Repairing the analysis (these change the Ghidra program, so run them before reports and keep the
75
80
  argument lists with the evidence that justifies them):
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  name = "scientific-method-engine"
7
7
  # The release workflow writes the published version from the package's release tag.
8
- version = "2.3.0"
8
+ version = "3.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"
@@ -2,9 +2,10 @@
2
2
  // @category Restoration
3
3
 
4
4
  import java.io.BufferedWriter;
5
- import java.io.File;
6
- import java.io.FileWriter;
7
5
  import java.nio.charset.StandardCharsets;
6
+ import java.nio.file.Files;
7
+ import java.nio.file.Path;
8
+ import java.nio.file.StandardCopyOption;
8
9
  import java.security.MessageDigest;
9
10
  import java.util.ArrayList;
10
11
  import java.util.List;
@@ -26,16 +27,25 @@ public class ExportFunctionFingerprints extends GhidraScript {
26
27
  throw new IllegalArgumentException("Expected output TSV path.");
27
28
  }
28
29
 
29
- File output = new File(args[0]);
30
- File parent = output.getParentFile();
31
- if (parent != null) {
32
- parent.mkdirs();
30
+ Path output = Path.of(args[0]).toAbsolutePath().normalize();
31
+ Files.createDirectories(output.getParent());
32
+ // The rows go to a temporary file that replaces the output only once every function and
33
+ // instruction is written, so a failed or cancelled run leaves no partial TSV behind.
34
+ Path temporary = Files.createTempFile(output.getParent(), "fingerprints-", ".partial");
35
+ try {
36
+ write(temporary);
37
+ Files.move(temporary, output, StandardCopyOption.REPLACE_EXISTING);
33
38
  }
39
+ finally { Files.deleteIfExists(temporary); }
40
+ println("Wrote " + output);
41
+ }
34
42
 
35
- try (BufferedWriter writer = new BufferedWriter(new FileWriter(output, StandardCharsets.UTF_8))) {
43
+ private void write(Path temporary) throws Exception {
44
+ try (BufferedWriter writer = Files.newBufferedWriter(temporary, StandardCharsets.UTF_8)) {
36
45
  writer.write("kind\tfunction\taddress\tend\tsize\tinstructionCount\tfingerprint\tsignature\n");
37
46
  FunctionIterator functions = currentProgram.getFunctionManager().getFunctions(true);
38
- while (functions.hasNext() && !monitor.isCancelled()) {
47
+ while (functions.hasNext()) {
48
+ monitor.checkCancelled();
39
49
  Function function = functions.next();
40
50
  List<Instruction> instructions = new ArrayList<>();
41
51
  InstructionIterator iterator = currentProgram.getListing()
@@ -66,7 +76,8 @@ public class ExportFunctionFingerprints extends GhidraScript {
66
76
  }
67
77
 
68
78
  InstructionIterator allInstructions = currentProgram.getListing().getInstructions(true);
69
- while (allInstructions.hasNext() && !monitor.isCancelled()) {
79
+ while (allInstructions.hasNext()) {
80
+ monitor.checkCancelled();
70
81
  Instruction instruction = allInstructions.next();
71
82
  Function function = currentProgram.getFunctionManager()
72
83
  .getFunctionContaining(instruction.getAddress());
@@ -79,7 +90,6 @@ public class ExportFunctionFingerprints extends GhidraScript {
79
90
  writer.newLine();
80
91
  }
81
92
  }
82
- println("Wrote " + output.getAbsolutePath());
83
93
  }
84
94
 
85
95
  // A scalar that names an address in the program is relocatable between versions, so it is
@@ -0,0 +1,122 @@
1
+ // Reports bounded call sites whose preceding argument setup contains requested immediates.
2
+ // The setup is the run of instructions that falls through to the call, up to 12 instructions. It
3
+ // ends after a function entry or an instruction a jump or call reaches, before one that does not
4
+ // fall through, and before an earlier call. Only immediate operands match; a memory operand's displacement, such as the 8 in
5
+ // PUSH [EBP+8], is no argument value.
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 java.util.ArrayList;
18
+ import java.util.HashSet;
19
+ import java.util.List;
20
+ import java.util.Set;
21
+
22
+ public class ReportCallSitesWithScalars extends GhidraScript {
23
+ private static final int PRECEDING_INSTRUCTIONS = 12;
24
+ private static final int MAX_MATCHES = 100;
25
+
26
+ @Override
27
+ protected void run() throws Exception {
28
+ String[] arguments = getScriptArgs();
29
+ if (arguments.length < 2) {
30
+ printerr("Supply a callee address followed by one or more scalar values.");
31
+ return;
32
+ }
33
+
34
+ Address callee = toAddr(arguments[0]);
35
+ Set<Long> requested = new HashSet<>();
36
+ for (int index = 1; index < arguments.length; index++) {
37
+ requested.add(Long.decode(arguments[index]));
38
+ }
39
+
40
+ int matches = 0;
41
+ int calls = 0;
42
+ ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(callee);
43
+ while (references.hasNext()) {
44
+ monitor.checkCancelled();
45
+ Reference reference = references.next();
46
+ Instruction call = currentProgram.getListing()
47
+ .getInstructionAt(reference.getFromAddress());
48
+ if (call == null || !call.getFlowType().isCall()) continue;
49
+ calls++;
50
+
51
+ List<Instruction> setup = argumentSetup(call);
52
+ boolean matched = false;
53
+ for (Instruction instruction : setup) matched |= containsRequestedImmediate(instruction, requested);
54
+ if (!matched) continue;
55
+ if (matches == MAX_MATCHES) {
56
+ println("Output capped at " + MAX_MATCHES + " calls; the scan did not finish.");
57
+ return;
58
+ }
59
+
60
+ matches++;
61
+ Function function = currentProgram.getFunctionManager()
62
+ .getFunctionContaining(call.getAddress());
63
+ println("===== call " + call.getAddress()
64
+ + (function == null ? "" : " in " + function.getEntryPoint()
65
+ + " " + function.getName()) + " =====");
66
+ for (int index = setup.size() - 1; index >= 0; index--) {
67
+ println(" " + setup.get(index).getAddress() + " " + setup.get(index));
68
+ }
69
+ println("> " + call.getAddress() + " " + call);
70
+ }
71
+
72
+ if (matches == 0) println("No matching call sites among " + calls + " calls.");
73
+ else println("Matched " + matches + " of " + calls + " calls; the scan covered every call Ghidra "
74
+ + "references to the callee.");
75
+ }
76
+
77
+ // The instructions before the call, nearest first, that run on every path reaching the call.
78
+ private List<Instruction> argumentSetup(Instruction call) {
79
+ List<Instruction> setup = new ArrayList<>();
80
+ Instruction later = call;
81
+ while (setup.size() < PRECEDING_INSTRUCTIONS && !isFlowTarget(later)) {
82
+ Instruction cursor = later.getPrevious();
83
+ if (cursor == null || !later.getAddress().equals(cursor.getFallThrough())
84
+ || cursor.getFlowType().isCall()) break;
85
+ setup.add(cursor);
86
+ later = cursor;
87
+ }
88
+ return setup;
89
+ }
90
+
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
+ // Ghidra types an immediate operand SCALAR, adding ADDRESS when it points into the program
102
+ // (PUSH 0x41c000). A memory operand is never SCALAR: a displacement makes it DYNAMIC, and an
103
+ // absolute one such as PUSH [0x41c000] is ADDRESS with its address as the scalar object.
104
+ private static boolean containsRequestedImmediate(Instruction instruction, Set<Long> requested) {
105
+ for (int operand = 0; operand < instruction.getNumOperands(); operand++) {
106
+ if (!OperandType.isScalar(instruction.getOperandType(operand))) continue;
107
+ for (Object object : instruction.getOpObjects(operand)) {
108
+ if (object instanceof Scalar scalar && matchesRequested(scalar, requested)) {
109
+ return true;
110
+ }
111
+ }
112
+ }
113
+ return false;
114
+ }
115
+
116
+ // Arguments are decoded as signed longs while operands are reported unsigned, so a request
117
+ // such as -1 must also be compared against the operand's signed value to match at all.
118
+ private static boolean matchesRequested(Scalar scalar, Set<Long> requested) {
119
+ return requested.contains(scalar.getUnsignedValue())
120
+ || requested.contains(scalar.getSignedValue());
121
+ }
122
+ }
@@ -7,6 +7,7 @@ import ghidra.program.model.listing.Function;
7
7
  import ghidra.program.model.listing.Instruction;
8
8
  import ghidra.program.model.listing.InstructionIterator;
9
9
  import ghidra.program.model.listing.Listing;
10
+ import ghidra.program.model.symbol.FlowType;
10
11
 
11
12
  public class ReportCallsToRange extends GhidraScript {
12
13
  private static final int MAX_MATCHES = 50;
@@ -14,8 +15,11 @@ public class ReportCallsToRange extends GhidraScript {
14
15
  @Override
15
16
  protected void run() throws Exception {
16
17
  String[] arguments = getScriptArgs();
17
- if (arguments.length < 2) {
18
- printerr("Supply start address and end address (inclusive), e.g. 1028:d820 1028:dab7");
18
+ String mode = arguments.length == 3 ? arguments[2] : "all";
19
+ if (arguments.length < 2 || arguments.length > 3
20
+ || !(mode.equals("all") || mode.equals("calls") || mode.equals("jumps"))) {
21
+ printerr("Supply start address, end address (inclusive) and an optional kind (all, calls or jumps), "
22
+ + "e.g. 1028:d820 1028:dab7 calls");
19
23
  return;
20
24
  }
21
25
 
@@ -26,24 +30,28 @@ public class ReportCallsToRange extends GhidraScript {
26
30
  return;
27
31
  }
28
32
 
29
- println("===== flow targets in " + start + ".." + end + " =====");
33
+ println("===== flow targets in " + start + ".." + end + " (" + mode + ") =====");
30
34
  Listing listing = currentProgram.getListing();
31
35
  InstructionIterator instructions = listing.getInstructions(true);
32
- int matches = 0;
33
- while (instructions.hasNext() && matches < MAX_MATCHES && !monitor.isCancelled()) {
36
+ int calls = 0;
37
+ int jumps = 0;
38
+ boolean capped = false;
39
+ while (instructions.hasNext()) {
40
+ monitor.checkCancelled();
34
41
  Instruction instruction = instructions.next();
35
- if (!instruction.getFlowType().isCall() && !instruction.getFlowType().isJump()) {
36
- continue;
37
- }
42
+ FlowType flow = instruction.getFlowType();
43
+ boolean call = flow.isCall();
44
+ if (!call && !flow.isJump()) continue;
45
+ if (call ? mode.equals("jumps") : mode.equals("calls")) continue;
38
46
 
39
47
  Address[] flows = instruction.getFlows();
40
- if (flows == null) {
41
- continue;
42
- }
48
+ if (flows == null) continue;
43
49
 
44
50
  for (Address target : flows) {
45
- if (target.compareTo(start) < 0 || target.compareTo(end) > 0) {
46
- continue;
51
+ if (target.compareTo(start) < 0 || target.compareTo(end) > 0) continue;
52
+ if (calls + jumps >= MAX_MATCHES) {
53
+ capped = true;
54
+ break;
47
55
  }
48
56
 
49
57
  Function fromFunction = listing.getFunctionContaining(instruction.getAddress());
@@ -52,16 +60,24 @@ public class ReportCallsToRange extends GhidraScript {
52
60
  + (fromFunction == null ? "" : " in " + fromFunction.getEntryPoint() + " " + fromFunction.getName())
53
61
  + " -> " + target
54
62
  + (toFunction == null ? "" : " (" + toFunction.getEntryPoint() + " " + toFunction.getName() + ")")
55
- + " :: " + instruction);
56
- matches++;
63
+ + " :: " + instruction + (call ? " [call]" : " [jump]"));
64
+ if (call) calls++;
65
+ else jumps++;
57
66
  break;
58
67
  }
68
+ if (capped) break;
59
69
  }
60
70
 
61
- if (matches == 0) {
62
- println("No resolved call/jump targets in range.");
63
- } else if (matches == MAX_MATCHES && instructions.hasNext()) {
64
- println("Output capped at " + MAX_MATCHES + " matches.");
71
+ if (capped) {
72
+ println("Output capped at " + MAX_MATCHES + " sites (" + calls + " calls, " + jumps
73
+ + " jumps); the scan did not finish. Narrow the range"
74
+ + (mode.equals("all") ? " or pass calls or jumps." : "."));
75
+ } else if (calls + jumps == 0) {
76
+ println("No resolved " + (mode.equals("all") ? "call/jump" : mode.substring(0, mode.length() - 1))
77
+ + " targets in range.");
78
+ } else {
79
+ println("Matched " + calls + " calls and " + jumps + " jumps; the scan covered the resolved targets of "
80
+ + "every disassembled instruction.");
65
81
  }
66
82
  }
67
83
  }
@@ -0,0 +1,156 @@
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.lang.Register;
12
+ import ghidra.program.model.listing.Function;
13
+ import ghidra.program.model.listing.Instruction;
14
+ import ghidra.program.model.pcode.PcodeOp;
15
+ import ghidra.program.model.pcode.Varnode;
16
+ import ghidra.program.model.scalar.Scalar;
17
+ import ghidra.program.model.symbol.Reference;
18
+ import ghidra.program.model.symbol.ReferenceIterator;
19
+
20
+ import java.util.ArrayList;
21
+ import java.util.HashSet;
22
+ import java.util.List;
23
+ import java.util.Set;
24
+
25
+ public class ReportConstantFirstArgumentCalls extends GhidraScript {
26
+ private static final int MAX_CALLS = 300;
27
+ private static final int MAX_PASSED_OVER = 8;
28
+
29
+ @Override
30
+ protected void run() throws Exception {
31
+ String[] arguments = getScriptArgs();
32
+ if (arguments.length != 2) {
33
+ printerr("Supply a callee virtual address and constant first argument.");
34
+ return;
35
+ }
36
+
37
+ Address callee = toAddr(arguments[0]);
38
+ long requested = Long.decode(arguments[1]);
39
+ Register stackPointer = currentProgram.getCompilerSpec().getStackPointer().getBaseRegister();
40
+ ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(callee);
41
+ int matches = 0;
42
+ int calls = 0;
43
+ int unknown = 0;
44
+ boolean capped = false;
45
+ while (references.hasNext()) {
46
+ monitor.checkCancelled();
47
+ Reference reference = references.next();
48
+ Instruction call = currentProgram.getListing().getInstructionAt(reference.getFromAddress());
49
+ if (call == null || !call.getFlowType().isCall()) continue;
50
+ calls++;
51
+ Instruction firstPush = firstArgumentPush(call, stackPointer);
52
+ if (firstPush == null) unknown++;
53
+ if (!isPushOf(firstPush, requested)) continue;
54
+ if (matches >= MAX_CALLS) {
55
+ capped = true;
56
+ break;
57
+ }
58
+
59
+ Function function = currentProgram.getFunctionManager().getFunctionContaining(call.getAddress());
60
+ Instruction secondPush = firstPush.getPrevious();
61
+ println(call.getAddress()
62
+ + (function == null ? "" : " in " + function.getEntryPoint() + " " + function.getName())
63
+ + " first=" + firstPush
64
+ + (secondPush == null ? "" : " preceding=" + secondPush));
65
+ matches++;
66
+ }
67
+
68
+ println("Matched calls: " + matches);
69
+ if (capped) println("Output capped at " + MAX_CALLS + " calls; the scan did not finish.");
70
+ else println("Calls read: " + calls + ", of which " + unknown + " have no PUSH known to supply the "
71
+ + "first argument (see ReportFirstArgumentCallSummary).");
72
+ }
73
+
74
+ // The nearest PUSH before the call, or null when none is known to supply the first argument.
75
+ private Instruction firstArgumentPush(Instruction call, Register stackPointer) {
76
+ List<Instruction> passedOver = new ArrayList<>();
77
+ Instruction later = call;
78
+ for (int passed = 0; passed <= MAX_PASSED_OVER; passed++) {
79
+ if (isFlowTarget(later)) return null;
80
+ Instruction cursor = later.getPrevious();
81
+ if (cursor == null || !later.getAddress().equals(cursor.getFallThrough())) return null;
82
+ if ("PUSH".equals(cursor.getMnemonicString())) {
83
+ return storeThroughStack(passedOver, stackPointer) == null ? cursor : null;
84
+ }
85
+ if (cursor.getFlowType().isCall() || writes(cursor, stackPointer)) return null;
86
+ passedOver.add(cursor);
87
+ later = cursor;
88
+ }
89
+ return null;
90
+ }
91
+
92
+ // A function entry counts too: a callback or table entry reaches it without a reference Ghidra recorded.
93
+ private boolean isFlowTarget(Instruction instruction) {
94
+ if (currentProgram.getFunctionManager().getFunctionAt(instruction.getAddress()) != null) return true;
95
+ ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(instruction.getAddress());
96
+ while (references.hasNext()) {
97
+ if (references.next().getReferenceType().isFlow()) return true;
98
+ }
99
+ return false;
100
+ }
101
+
102
+ private static boolean writes(Instruction instruction, Register register) {
103
+ for (Object object : instruction.getResultObjects()) {
104
+ if (object instanceof Register written && written.getBaseRegister().equals(register)) return true;
105
+ }
106
+ return false;
107
+ }
108
+
109
+ // The first of the passed-over instructions (listed nearest the call first) that stores to an address
110
+ // computed from the stack pointer, such as MOV [ESP],EAX, or through a register an earlier one copied
111
+ // it into (LEA EAX,[ESP]; MOV [EAX],ECX). Either can overwrite the pushed argument. Ghidra lists no
112
+ // result object for a memory destination, so the p-code is read instead, in execution order.
113
+ private Instruction storeThroughStack(List<Instruction> passedOver, Register stackPointer) {
114
+ Set<Varnode> fromStack = new HashSet<>();
115
+ for (int index = passedOver.size() - 1; index >= 0; index--) {
116
+ Instruction instruction = passedOver.get(index);
117
+ for (PcodeOp op : instruction.getPcode()) {
118
+ if (op.getOpcode() == PcodeOp.STORE) {
119
+ if (isFromStack(op.getInput(1), fromStack, stackPointer)) return instruction;
120
+ continue;
121
+ }
122
+ Varnode output = op.getOutput();
123
+ if (output == null) continue;
124
+ // A LOAD's address may come from the stack pointer, but the value it reads does not.
125
+ boolean derived = false;
126
+ if (op.getOpcode() != PcodeOp.LOAD) {
127
+ for (Varnode input : op.getInputs()) derived |= isFromStack(input, fromStack, stackPointer);
128
+ }
129
+ if (derived) fromStack.add(output);
130
+ else fromStack.remove(output);
131
+ }
132
+ fromStack.removeIf(Varnode::isUnique); // p-code temporaries do not outlive their instruction
133
+ }
134
+ return null;
135
+ }
136
+
137
+ private boolean isFromStack(Varnode varnode, Set<Varnode> fromStack, Register stackPointer) {
138
+ if (fromStack.contains(varnode)) return true;
139
+ if (!varnode.isRegister()) return false;
140
+ Register register = currentProgram.getRegister(varnode.getAddress(), varnode.getSize());
141
+ return register != null && register.getBaseRegister().equals(stackPointer);
142
+ }
143
+
144
+ // Only an immediate operand is a literal; PUSH [EBP+8] carries the scalar 8 as a displacement.
145
+ // Ghidra types an immediate operand SCALAR, adding ADDRESS when it points into the program
146
+ // (PUSH 0x41c000). A memory operand is never SCALAR: an absolute one such as PUSH [0x41c000] is
147
+ // ADDRESS with its address as the scalar object.
148
+ private static boolean isPushOf(Instruction instruction, long requested) {
149
+ if (instruction == null || !OperandType.isScalar(instruction.getOperandType(0))) return false;
150
+ for (Object object : instruction.getOpObjects(0)) {
151
+ if (object instanceof Scalar scalar
152
+ && scalar.getUnsignedValue() == requested) return true;
153
+ }
154
+ return false;
155
+ }
156
+ }
@@ -21,10 +21,16 @@ public class ReportDecompileWindow extends GhidraScript {
21
21
  Address address = toAddr(arguments[0]);
22
22
  int requestedStart = Integer.parseInt(arguments[1]);
23
23
  int requestedCount = Integer.parseInt(arguments[2]);
24
- if (requestedStart < 1 || requestedCount < 1 || requestedCount > MAX_LINES) {
25
- printerr("Start must be positive and count must be between 1 and " + MAX_LINES + ".");
24
+ if (requestedStart < 1 || requestedCount < 1) {
25
+ printerr("Start and count must be positive.");
26
26
  return;
27
27
  }
28
+ // A function's decompiled length is unknown before the run, so a larger count is cut to the cap
29
+ // and the output says where the next window starts.
30
+ if (requestedCount > MAX_LINES) {
31
+ println("Line count " + requestedCount + " cut to the cap of " + MAX_LINES + ".");
32
+ requestedCount = MAX_LINES;
33
+ }
28
34
 
29
35
  Function function = currentProgram.getFunctionManager().getFunctionContaining(address);
30
36
  if (function == null) {
@@ -53,6 +59,10 @@ public class ReportDecompileWindow extends GhidraScript {
53
59
  for (int index = start; index < end; index++) {
54
60
  println((index + 1) + ": " + lines[index]);
55
61
  }
62
+ if (end < lines.length) {
63
+ println("===== " + (lines.length - end) + " more lines; the next window starts at line " + (end + 1)
64
+ + " =====");
65
+ }
56
66
  }
57
67
  finally {
58
68
  decompiler.dispose();