scientific-method-engine 13.5.0__tar.gz → 13.7.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 (82) hide show
  1. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/PKG-INFO +5 -3
  2. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/README.md +4 -2
  3. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/pyproject.toml +1 -1
  4. scientific_method_engine-13.7.0/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +122 -0
  5. scientific_method_engine-13.7.0/src/scientific_method_engine/ghidra/ReportRangeBoundaries.java +334 -0
  6. scientific_method_engine-13.5.0/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -71
  7. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/.gitignore +0 -0
  8. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/LICENSE +0 -0
  9. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/__init__.py +0 -0
  10. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/__main__.py +0 -0
  11. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/cli.py +0 -0
  12. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  13. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  14. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  15. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  16. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  17. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  18. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  19. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  20. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  21. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  22. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  23. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  24. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  25. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  26. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  27. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  28. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  29. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  30. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  31. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +0 -0
  32. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  33. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  34. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  35. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  36. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  37. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportReferences.java +0 -0
  38. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +0 -0
  39. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  40. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  41. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  42. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  43. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +0 -0
  44. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  45. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  46. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  47. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  48. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/image.py +0 -0
  49. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/inventory.py +0 -0
  50. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/loops.py +0 -0
  51. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/machine.py +0 -0
  52. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  53. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  54. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  55. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/pe.py +0 -0
  56. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/reach.py +0 -0
  57. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/relational.py +0 -0
  58. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/reports.py +0 -0
  59. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  60. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/trace.py +0 -0
  61. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/src/scientific_method_engine/x86/values.py +0 -0
  62. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/oracle.py +0 -0
  63. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_continuation_budget.py +0 -0
  64. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_dispatch.py +0 -0
  65. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_effect_order.py +0 -0
  66. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_enter_frames.py +0 -0
  67. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_entry_frame.py +0 -0
  68. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_indirect_far_transfers.py +0 -0
  69. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_interrupt_models.py +0 -0
  70. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_inventory_check.py +0 -0
  71. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_loops.py +0 -0
  72. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_memory_scopes.py +0 -0
  73. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_nested_frame_request.py +0 -0
  74. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_oracle.py +0 -0
  75. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_pe.py +0 -0
  76. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_reach.py +0 -0
  77. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_relational_controls.py +0 -0
  78. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_return_checks.py +0 -0
  79. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_successor_rule.py +0 -0
  80. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_table_continuations.py +0 -0
  81. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.0}/tests/test_term_limit.py +0 -0
  82. {scientific_method_engine-13.5.0 → scientific_method_engine-13.7.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: 13.5.0
3
+ Version: 13.7.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
@@ -46,7 +46,8 @@ ghidra-scripts` prints their directory, for Ghidra's `-scriptPath`:
46
46
 
47
47
  Addresses are Ghidra addresses (`0x00401000`, or `1028:d820` for segmented programs). Report scripts
48
48
  print to the analyzer log and cap their output. `ReportScalarConstants`, `ReportCallsToRange`,
49
- `ReportConstantFirstArgumentCalls` and `ReportCallSitesWithScalars` say when a cap stopped their scan;
49
+ `ReportConstantFirstArgumentCalls` and `ReportCallSitesWithScalars` say when a cap stopped their scan,
50
+ and `ReportRangeBoundaries` says when it stopped printing, with counts that still cover every range it read;
50
51
  for the other report scripts, a result count equal to the cap means the same.
51
52
  `analyzeHeadless` can exit with code 0 after a script failed to load, so check the log for the
52
53
  script's own result lines ([the Ghidra workflow](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/ghidra-workflow.md)
@@ -60,7 +61,8 @@ Reading code and data:
60
61
  | Script | Arguments | Prints |
61
62
  |---|---|---|
62
63
  | `ReportInstructionContext` | one or more instruction addresses | a bounded instruction window around the instruction containing each address; the header names the requested address when it is inside that instruction |
63
- | `ReportInstructionWindow` | address where an instruction starts, instruction count (1..200) | a header, the instructions from the address onward with a `gap:` line wherever the listing skips bytes, then the count printed or where the listing ended. An address inside an instruction, in data, in undisassembled bytes or outside memory prints an error naming what is there and the next instruction start, and no window |
64
+ | `ReportInstructionWindow` | address where an instruction starts, instruction count (1..200) | a header, the instructions from the address onward with a `gap:` line wherever the listing skips bytes, a `span:` line for each run of instructions with no gap (its half-open range ending after the last instruction's final byte, byte count, last byte and instruction count, or that it reaches the end of its address space and has no exclusive end; the next instruction's start when the count closed the span and the run goes on; each instruction whose length the listing overrides, with the bytes it decodes), then the count printed or where the listing ended. An address inside an instruction, in data, in undisassembled bytes or outside memory prints an error naming what is there and the next instruction start, and no window |
65
+ | `ReportRangeBoundaries` | path of a file with one half-open range per line (`start..end`, optionally followed by whitespace and a label; blank lines and `#` lines skipped) | a line for each range whose start or end falls inside an instruction or defined data, naming that unit, its instruction text and the boundaries on either side of it; a line for each end it could not place, with the reason; a line for each line it could not read; then the counts. An end is on a boundary where an instruction or defined data starts or where the byte before it is the last byte of one, so an end in the padding after a `RET` passes. An end in undisassembled bytes is placed by decoding from the range's start in fall-through order in memory, which changes nothing in the program. Decoding that stops at an instruction without a fall-through, at data, at bytes that do not decode, at a decoded instruction whose bytes run into a listed instruction or defined data, at 10000 instructions or past the end leaves the end unplaced, never passed. A start in undisassembled bytes is not judged, and the counts say how many there were; an end placed by decoding from such a start holds only if an instruction starts there, so its line and the counts say so. A file with a UTF-8 byte order mark is read. Output stops at 1000 lines; a cancelled run says which line it stopped before |
64
66
  | `ReportDataBytes` | address, byte count (1..256) | the bytes at the address |
65
67
  | `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 |
66
68
  | `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 |
@@ -30,7 +30,8 @@ ghidra-scripts` prints their directory, for Ghidra's `-scriptPath`:
30
30
 
31
31
  Addresses are Ghidra addresses (`0x00401000`, or `1028:d820` for segmented programs). Report scripts
32
32
  print to the analyzer log and cap their output. `ReportScalarConstants`, `ReportCallsToRange`,
33
- `ReportConstantFirstArgumentCalls` and `ReportCallSitesWithScalars` say when a cap stopped their scan;
33
+ `ReportConstantFirstArgumentCalls` and `ReportCallSitesWithScalars` say when a cap stopped their scan,
34
+ and `ReportRangeBoundaries` says when it stopped printing, with counts that still cover every range it read;
34
35
  for the other report scripts, a result count equal to the cap means the same.
35
36
  `analyzeHeadless` can exit with code 0 after a script failed to load, so check the log for the
36
37
  script's own result lines ([the Ghidra workflow](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/ghidra-workflow.md)
@@ -44,7 +45,8 @@ Reading code and data:
44
45
  | Script | Arguments | Prints |
45
46
  |---|---|---|
46
47
  | `ReportInstructionContext` | one or more instruction addresses | a bounded instruction window around the instruction containing each address; the header names the requested address when it is inside that instruction |
47
- | `ReportInstructionWindow` | address where an instruction starts, instruction count (1..200) | a header, the instructions from the address onward with a `gap:` line wherever the listing skips bytes, then the count printed or where the listing ended. An address inside an instruction, in data, in undisassembled bytes or outside memory prints an error naming what is there and the next instruction start, and no window |
48
+ | `ReportInstructionWindow` | address where an instruction starts, instruction count (1..200) | a header, the instructions from the address onward with a `gap:` line wherever the listing skips bytes, a `span:` line for each run of instructions with no gap (its half-open range ending after the last instruction's final byte, byte count, last byte and instruction count, or that it reaches the end of its address space and has no exclusive end; the next instruction's start when the count closed the span and the run goes on; each instruction whose length the listing overrides, with the bytes it decodes), then the count printed or where the listing ended. An address inside an instruction, in data, in undisassembled bytes or outside memory prints an error naming what is there and the next instruction start, and no window |
49
+ | `ReportRangeBoundaries` | path of a file with one half-open range per line (`start..end`, optionally followed by whitespace and a label; blank lines and `#` lines skipped) | a line for each range whose start or end falls inside an instruction or defined data, naming that unit, its instruction text and the boundaries on either side of it; a line for each end it could not place, with the reason; a line for each line it could not read; then the counts. An end is on a boundary where an instruction or defined data starts or where the byte before it is the last byte of one, so an end in the padding after a `RET` passes. An end in undisassembled bytes is placed by decoding from the range's start in fall-through order in memory, which changes nothing in the program. Decoding that stops at an instruction without a fall-through, at data, at bytes that do not decode, at a decoded instruction whose bytes run into a listed instruction or defined data, at 10000 instructions or past the end leaves the end unplaced, never passed. A start in undisassembled bytes is not judged, and the counts say how many there were; an end placed by decoding from such a start holds only if an instruction starts there, so its line and the counts say so. A file with a UTF-8 byte order mark is read. Output stops at 1000 lines; a cancelled run says which line it stopped before |
48
50
  | `ReportDataBytes` | address, byte count (1..256) | the bytes at the address |
49
51
  | `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 |
50
52
  | `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 |
@@ -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 = "13.5.0"
8
+ version = "13.7.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"
@@ -0,0 +1,122 @@
1
+ // Prints a bounded instruction window that begins at an instruction start.
2
+ // @category Restoration
3
+
4
+ import java.util.ArrayList;
5
+ import java.util.List;
6
+
7
+ import ghidra.app.script.GhidraScript;
8
+ import ghidra.program.model.address.Address;
9
+ import ghidra.program.model.listing.Instruction;
10
+
11
+ import scientificmethod.InstructionStart;
12
+
13
+ public class ReportInstructionWindow extends GhidraScript {
14
+ private static final int MAX_INSTRUCTIONS = 200;
15
+
16
+ @Override
17
+ protected void run() throws Exception {
18
+ String[] arguments = getScriptArgs();
19
+ if (arguments.length != 2) {
20
+ printerr("Supply a virtual address and instruction count.");
21
+ return;
22
+ }
23
+
24
+ Address address = toAddr(arguments[0]);
25
+ if (address == null) {
26
+ printerr(arguments[0] + ": not an address in this program");
27
+ return;
28
+ }
29
+ int count;
30
+ try {
31
+ count = Integer.parseInt(arguments[1]);
32
+ } catch (NumberFormatException exception) {
33
+ count = 0;
34
+ }
35
+ if (count < 1 || count > MAX_INSTRUCTIONS) {
36
+ printerr("Instruction count must be between 1 and " + MAX_INSTRUCTIONS + ".");
37
+ return;
38
+ }
39
+
40
+ // The window starts only where an instruction starts. Starting at the next instruction
41
+ // instead would print a window that looks like the requested one but is not.
42
+ String missing = InstructionStart.missingStart(currentProgram, address);
43
+ if (missing != null) {
44
+ printerr(missing + " No window printed.");
45
+ return;
46
+ }
47
+
48
+ println("===== up to " + count + " instructions from " + address + " =====");
49
+ Instruction instruction = currentProgram.getListing().getInstructionAt(address);
50
+ int printed = 0;
51
+ // Each run of printed instructions with no gap between them, closed at a gap and at the
52
+ // window's last instruction.
53
+ List<String> spans = new ArrayList<>();
54
+ Address spanStart = null;
55
+ int spanInstructions = 0;
56
+ // The instructions in the current span whose listed length the listing overrides.
57
+ List<String> overrides = new ArrayList<>();
58
+ while (instruction != null && printed < count) {
59
+ if (spanStart == null) {
60
+ spanStart = instruction.getAddress();
61
+ }
62
+ println(instruction.getAddress() + ": " + instruction);
63
+ printed++;
64
+ spanInstructions++;
65
+ if (instruction.isLengthOverridden()) {
66
+ overrides.add(instruction.getAddress() + " (listed as " + instruction.getLength() + " of the "
67
+ + instruction.getParsedLength() + " bytes it decodes)");
68
+ }
69
+ Instruction next = instruction.getNext();
70
+ // Address.next() is null when the instruction ends its address space, so a gap is
71
+ // measured from the instruction's last byte, and such a span has no exclusive end.
72
+ Address last = instruction.getMaxAddress();
73
+ Address end = last.next();
74
+ boolean adjacent = end != null && next != null && next.getAddress().equals(end);
75
+ if (printed == count || !adjacent) {
76
+ spans.add(span(spanStart, last, end, spanInstructions, overrides, adjacent));
77
+ spanStart = null;
78
+ spanInstructions = 0;
79
+ overrides.clear();
80
+ if (printed < count && next != null) {
81
+ if (end == null) {
82
+ println("gap: no instruction after " + last + " up to " + next.getAddress());
83
+ } else {
84
+ println("gap: no instruction from " + end + " up to " + next.getAddress());
85
+ }
86
+ }
87
+ }
88
+ instruction = next;
89
+ }
90
+ for (String line : spans) {
91
+ println(line);
92
+ }
93
+ if (printed < count) {
94
+ println("The listing ends after " + printed + " of " + count + " instructions.");
95
+ } else {
96
+ println("Printed " + printed + " instructions.");
97
+ }
98
+ }
99
+
100
+ // A span as a half-open range with its last byte, so a range copied from it ends after the
101
+ // final byte of its last instruction. Past the end of an address space no address can end it.
102
+ // A span the window's count closed says when the next instruction starts at its end, since
103
+ // the run goes on past the window. An instruction whose length the listing overrides decodes
104
+ // bytes past where the next instruction or the span ends, so the span names it.
105
+ private static String span(Address first, Address last, Address end, int instructions,
106
+ List<String> overrides, boolean continues) {
107
+ long bytes = last.subtract(first) + 1;
108
+ String range = end == null ? first + " to the end of its address space" : first + ".." + end;
109
+ StringBuilder line = new StringBuilder("span: " + range + " (" + bytes + (bytes == 1 ? " byte" : " bytes") + ", last byte " + last
110
+ + ", " + instructions + (instructions == 1 ? " instruction)" : " instructions)"));
111
+ if (end == null) {
112
+ line.append("; no address follows its last byte, so it has no exclusive end");
113
+ }
114
+ if (continues) {
115
+ line.append("; the window stops here and the next instruction starts at ").append(end);
116
+ }
117
+ for (String override : overrides) {
118
+ line.append("; the listing overrides the length of the instruction at ").append(override);
119
+ }
120
+ return line.toString();
121
+ }
122
+ }
@@ -0,0 +1,334 @@
1
+ // Reports half-open ranges from a file whose start or end falls inside an instruction or defined data.
2
+ // Arguments: a file with one range per line, `start..end` with the end exclusive, optionally followed
3
+ // by whitespace and a label that is printed with the range. Blank lines and lines starting with #
4
+ // are skipped.
5
+ // @category Restoration
6
+
7
+ import java.io.IOException;
8
+ import java.nio.file.Files;
9
+ import java.nio.file.Path;
10
+ import java.util.List;
11
+ import java.util.regex.Matcher;
12
+ import java.util.regex.Pattern;
13
+
14
+ import ghidra.app.script.GhidraScript;
15
+ import ghidra.app.util.PseudoDisassembler;
16
+ import ghidra.program.model.address.Address;
17
+ import ghidra.program.model.listing.CodeUnit;
18
+ import ghidra.program.model.listing.Data;
19
+ import ghidra.program.model.listing.Instruction;
20
+ import ghidra.program.model.listing.Listing;
21
+ import ghidra.program.model.mem.MemoryBlock;
22
+
23
+ public class ReportRangeBoundaries extends GhidraScript {
24
+ private static final int MAX_PRINTED = 1000;
25
+ // The most instructions decoded in memory from one range's start while placing its end.
26
+ private static final int MAX_DECODED = 10000;
27
+ private static final Pattern RANGE = Pattern.compile("(\\S+?)\\.\\.(\\S+)(?:\\s+(.*))?");
28
+
29
+ // Where a range's start falls: where an instruction or defined data starts, inside one, or in
30
+ // undisassembled bytes or outside memory, where it is not judged.
31
+ private enum Start { ON_BOUNDARY, CUT, UNJUDGED }
32
+
33
+ private Listing listing;
34
+ private PseudoDisassembler decoder;
35
+ private int printed;
36
+
37
+ private int ends;
38
+ private int endsDecoded;
39
+ private int endsDecodedFromUnjudged;
40
+ private int endsInInstruction;
41
+ private int endsInData;
42
+ private int endsUnplaced;
43
+ private int startsInInstruction;
44
+ private int startsInData;
45
+ private int startsUnjudged;
46
+ private int unread;
47
+
48
+ @Override
49
+ protected void run() throws Exception {
50
+ String[] arguments = getScriptArgs();
51
+ if (arguments.length != 1) {
52
+ printerr("Supply the path of a file with one start..end range per line.");
53
+ return;
54
+ }
55
+ List<String> lines;
56
+ try {
57
+ lines = Files.readAllLines(Path.of(arguments[0]));
58
+ } catch (IOException exception) {
59
+ printerr(arguments[0] + ": could not read the file: " + exception.getMessage());
60
+ return;
61
+ }
62
+ listing = currentProgram.getListing();
63
+ decoder = new PseudoDisassembler(currentProgram);
64
+
65
+ int ranges = 0;
66
+ int number = 1;
67
+ for (; number <= lines.size(); number++) {
68
+ if (monitor.isCancelled()) {
69
+ break;
70
+ }
71
+ String line = lines.get(number - 1);
72
+ // A file saved with a UTF-8 byte order mark keeps it on its first line.
73
+ if (number == 1 && line.startsWith("\uFEFF")) {
74
+ line = line.substring(1);
75
+ }
76
+ line = line.strip();
77
+ if (line.isEmpty() || line.startsWith("#")) {
78
+ continue;
79
+ }
80
+ Matcher matcher = RANGE.matcher(line);
81
+ if (!matcher.matches()) {
82
+ notRead(number, "expected start..end, optionally followed by a label");
83
+ continue;
84
+ }
85
+ Address start = address(matcher.group(1));
86
+ Address end = address(matcher.group(2));
87
+ if (start == null || end == null) {
88
+ notRead(number, (start == null ? matcher.group(1) : matcher.group(2))
89
+ + " is not an address in this program");
90
+ continue;
91
+ }
92
+ if (!start.getAddressSpace().equals(end.getAddressSpace()) || start.compareTo(end) >= 0) {
93
+ notRead(number, "the end must follow the start in the same address space");
94
+ continue;
95
+ }
96
+ ranges++;
97
+ String label = matcher.group(3) == null ? "" : " " + matcher.group(3).strip();
98
+ String range = start + ".." + end + label;
99
+ Start judged = checkStart(range, start);
100
+ checkEnd(range, start, end, judged);
101
+ }
102
+
103
+ if (number <= lines.size()) {
104
+ println("Cancelled before line " + number + " of " + lines.size()
105
+ + "; the counts below cover only the lines before it.");
106
+ }
107
+ if (printed > MAX_PRINTED) {
108
+ println("Printed the first " + MAX_PRINTED + " lines; the counts below cover every range read.");
109
+ }
110
+ println("Checked " + ranges + (ranges == 1 ? " range: " : " ranges: ") + ends
111
+ + " ends on an instruction or data boundary (" + endsDecoded + " of them placed by decoding in memory, "
112
+ + endsDecodedFromUnjudged + " of those from a start that was not judged), "
113
+ + endsInInstruction + " inside an instruction, " + endsInData + " inside defined data, "
114
+ + endsUnplaced + " unplaced; " + startsInInstruction + " starts inside an instruction, "
115
+ + startsInData + " inside defined data, " + startsUnjudged
116
+ + " in undisassembled bytes or outside memory and not judged; "
117
+ + unread + (unread == 1 ? " line" : " lines") + " not read.");
118
+ }
119
+
120
+ // A start where no instruction or defined data starts, but inside one, cuts it. A start in
121
+ // undisassembled bytes is not judged: nothing in the listing says where an instruction there starts.
122
+ private Start checkStart(String range, Address start) {
123
+ CodeUnit cut = containingUnit(start);
124
+ if (cut == null) {
125
+ if (listing.getInstructionAt(start) != null || isDataStart(start)) {
126
+ return Start.ON_BOUNDARY;
127
+ }
128
+ startsUnjudged++;
129
+ return Start.UNJUDGED;
130
+ }
131
+ if (cut instanceof Instruction) {
132
+ startsInInstruction++;
133
+ report("start inside instruction: " + range + ": the start is " + into(start, cut));
134
+ } else {
135
+ startsInData++;
136
+ report("start inside data: " + range + ": the start is " + into(start, cut));
137
+ }
138
+ return Start.CUT;
139
+ }
140
+
141
+ private void checkEnd(String range, Address start, Address end, Start judged) {
142
+ // An end is a boundary where an instruction or defined data starts, or where the byte
143
+ // before it is the last byte of one. Padding after a RET is undisassembled, so an end there
144
+ // is placed by the RET.
145
+ if (listing.getInstructionAt(end) != null || isDataStart(end) || endsUnitBefore(end)) {
146
+ ends++;
147
+ return;
148
+ }
149
+ CodeUnit cut = containingUnit(end);
150
+ if (cut instanceof Instruction) {
151
+ endsInInstruction++;
152
+ report("end inside instruction: " + range + ": the end is " + into(end, cut));
153
+ return;
154
+ }
155
+ if (cut != null) {
156
+ endsInData++;
157
+ report("end inside data: " + range + ": the end is " + into(end, cut));
158
+ return;
159
+ }
160
+ if (judged == Start.CUT) {
161
+ unplaced(range, "the end is in undisassembled bytes, and the start is inside a code unit, so "
162
+ + "decoding from it would not follow the program's instructions");
163
+ return;
164
+ }
165
+ decodeTo(range, start, end, judged == Start.UNJUDGED);
166
+ }
167
+
168
+ // The end is in undisassembled bytes. Decode from the range's start in fall-through order,
169
+ // taking each instruction from the listing where it has one and decoding the bytes in memory
170
+ // otherwise. PseudoDisassembler writes nothing to the program, so the database is unchanged.
171
+ // From a start that was not judged, the result holds only if an instruction starts there, so
172
+ // the report and the counts say which ends were placed that way.
173
+ private void decodeTo(String range, Address start, Address end, boolean fromUnjudged) {
174
+ String unjudgedNote = fromUnjudged ? ", a start that was not judged" : "";
175
+ Address at = start;
176
+ for (int decoded = 0; ; decoded++) {
177
+ if (decoded == MAX_DECODED) {
178
+ unplaced(range, "decoding from " + start + " stopped at the limit of " + MAX_DECODED
179
+ + " instructions, at " + at);
180
+ return;
181
+ }
182
+ Instruction instruction = listing.getInstructionAt(at);
183
+ boolean listed = instruction != null;
184
+ if (!listed) {
185
+ CodeUnit unit = listing.getInstructionContaining(at);
186
+ if (unit == null) {
187
+ unit = listing.getDefinedDataContaining(at);
188
+ }
189
+ if (unit != null) {
190
+ unplaced(range, "decoding from " + start + " reaches " + at + ", inside the "
191
+ + describe(unit) + " at " + unit.getAddress());
192
+ return;
193
+ }
194
+ MemoryBlock block = currentProgram.getMemory().getBlock(at);
195
+ if (block == null || !block.isInitialized()) {
196
+ unplaced(range, "decoding from " + start + " reaches " + at + ", which holds no bytes");
197
+ return;
198
+ }
199
+ try {
200
+ instruction = decoder.disassemble(at);
201
+ } catch (Exception exception) {
202
+ instruction = null;
203
+ }
204
+ if (instruction == null) {
205
+ unplaced(range, "decoding from " + start + " reaches " + at + ", where the bytes do not decode");
206
+ return;
207
+ }
208
+ CodeUnit overlapped = listedUnitWithin(at.next(), instruction.getMaxAddress());
209
+ if (overlapped != null) {
210
+ unplaced(range, "decoding from " + start + " decodes the instruction at " + at + ", " + instruction
211
+ + ", whose bytes run into the " + describe(overlapped) + " at " + overlapped.getAddress());
212
+ return;
213
+ }
214
+ }
215
+ Address last = instruction.getMaxAddress();
216
+ if (end.compareTo(instruction.getAddress()) > 0 && end.compareTo(last) <= 0) {
217
+ endsInInstruction++;
218
+ report("end inside instruction: " + range + ": the end is " + into(end, instruction)
219
+ + (listed ? "" : ", decoded in memory from " + start + unjudgedNote));
220
+ return;
221
+ }
222
+ Address next = last.next();
223
+ if (end.equals(next)) {
224
+ ends++;
225
+ endsDecoded++;
226
+ if (fromUnjudged) {
227
+ endsDecodedFromUnjudged++;
228
+ }
229
+ return;
230
+ }
231
+ Address fallThrough = instruction.getFallThrough();
232
+ if (fallThrough == null) {
233
+ unplaced(range, "decoding from " + start + " stops at the instruction at " + instruction.getAddress()
234
+ + ", " + instruction + ", which does not fall through");
235
+ return;
236
+ }
237
+ if (!fallThrough.getAddressSpace().equals(end.getAddressSpace()) || fallThrough.compareTo(end) >= 0
238
+ || fallThrough.compareTo(at) <= 0) {
239
+ unplaced(range, "decoding from " + start + " continues from the instruction at "
240
+ + instruction.getAddress() + " to " + fallThrough + ", past the end");
241
+ return;
242
+ }
243
+ at = fallThrough;
244
+ }
245
+ }
246
+
247
+ // The instruction or defined data that holds the address without starting at it.
248
+ private CodeUnit containingUnit(Address address) {
249
+ Instruction instruction = listing.getInstructionContaining(address);
250
+ if (instruction != null) {
251
+ return instruction.getAddress().equals(address) ? null : instruction;
252
+ }
253
+ Data data = listing.getDefinedDataContaining(address);
254
+ return data == null || data.getAddress().equals(address) ? null : data;
255
+ }
256
+
257
+ // The first listed instruction or defined data that starts from the first address through the
258
+ // last, or null. A decoded instruction over such a unit contradicts the listing.
259
+ private CodeUnit listedUnitWithin(Address first, Address last) {
260
+ if (first == null || first.compareTo(last) > 0) {
261
+ return null;
262
+ }
263
+ Instruction instruction = listing.getInstructionAt(first);
264
+ if (instruction == null) {
265
+ instruction = listing.getInstructionAfter(first);
266
+ }
267
+ Data data = listing.getDefinedDataAt(first);
268
+ if (data == null) {
269
+ data = listing.getDefinedDataAfter(first);
270
+ }
271
+ CodeUnit unit = instruction;
272
+ if (data != null && (unit == null || data.getAddress().compareTo(unit.getAddress()) < 0)) {
273
+ unit = data;
274
+ }
275
+ return unit == null || !unit.getAddress().getAddressSpace().equals(last.getAddressSpace())
276
+ || unit.getAddress().compareTo(last) > 0 ? null : unit;
277
+ }
278
+
279
+ private boolean isDataStart(Address address) {
280
+ return listing.getDefinedDataAt(address) != null;
281
+ }
282
+
283
+ // Whether the byte before the address is the last byte of an instruction or defined data.
284
+ private boolean endsUnitBefore(Address address) {
285
+ Address before = address.previous();
286
+ if (before == null || !before.getAddressSpace().equals(address.getAddressSpace())) {
287
+ return false;
288
+ }
289
+ Instruction instruction = listing.getInstructionContaining(before);
290
+ if (instruction != null) {
291
+ return instruction.getMaxAddress().equals(before);
292
+ }
293
+ Data data = listing.getDefinedDataContaining(before);
294
+ return data != null && data.getMaxAddress().equals(before);
295
+ }
296
+
297
+ // Where the address falls in the unit, and the two boundaries a range could end at instead.
298
+ private static String into(Address address, CodeUnit unit) {
299
+ long offset = address.subtract(unit.getAddress());
300
+ Address after = unit.getMaxAddress().next();
301
+ return offset + " of " + unit.getLength() + " bytes into the " + describe(unit) + " at " + unit.getAddress()
302
+ + (unit instanceof Instruction ? ", " + unit : "") + "; the nearest boundaries are " + unit.getAddress()
303
+ + (after == null ? " and the end of its address space" : " and " + after);
304
+ }
305
+
306
+ private static String describe(CodeUnit unit) {
307
+ return unit instanceof Data data ? "defined data (" + data.getDataType().getName() + ")" : "instruction";
308
+ }
309
+
310
+ private Address address(String text) {
311
+ try {
312
+ return toAddr(text);
313
+ } catch (RuntimeException exception) {
314
+ return null;
315
+ }
316
+ }
317
+
318
+ private void unplaced(String range, String reason) {
319
+ endsUnplaced++;
320
+ report("end unplaced: " + range + ": " + reason + "; the end is not checked");
321
+ }
322
+
323
+ private void notRead(int number, String reason) {
324
+ unread++;
325
+ report("line " + number + " not read: " + reason);
326
+ }
327
+
328
+ private void report(String line) {
329
+ printed++;
330
+ if (printed <= MAX_PRINTED) {
331
+ println(line);
332
+ }
333
+ }
334
+ }
@@ -1,71 +0,0 @@
1
- // Prints a bounded instruction window that begins at an instruction start.
2
- // @category Restoration
3
-
4
- import ghidra.app.script.GhidraScript;
5
- import ghidra.program.model.address.Address;
6
- import ghidra.program.model.listing.Instruction;
7
-
8
- import scientificmethod.InstructionStart;
9
-
10
- public class ReportInstructionWindow extends GhidraScript {
11
- private static final int MAX_INSTRUCTIONS = 200;
12
-
13
- @Override
14
- protected void run() throws Exception {
15
- String[] arguments = getScriptArgs();
16
- if (arguments.length != 2) {
17
- printerr("Supply a virtual address and instruction count.");
18
- return;
19
- }
20
-
21
- Address address = toAddr(arguments[0]);
22
- if (address == null) {
23
- printerr(arguments[0] + ": not an address in this program");
24
- return;
25
- }
26
- int count;
27
- try {
28
- count = Integer.parseInt(arguments[1]);
29
- } catch (NumberFormatException exception) {
30
- count = 0;
31
- }
32
- if (count < 1 || count > MAX_INSTRUCTIONS) {
33
- printerr("Instruction count must be between 1 and " + MAX_INSTRUCTIONS + ".");
34
- return;
35
- }
36
-
37
- // The window starts only where an instruction starts. Starting at the next instruction
38
- // instead would print a window that looks like the requested one but is not.
39
- String missing = InstructionStart.missingStart(currentProgram, address);
40
- if (missing != null) {
41
- printerr(missing + " No window printed.");
42
- return;
43
- }
44
-
45
- println("===== up to " + count + " instructions from " + address + " =====");
46
- Instruction instruction = currentProgram.getListing().getInstructionAt(address);
47
- int printed = 0;
48
- while (instruction != null && printed < count) {
49
- println(instruction.getAddress() + ": " + instruction);
50
- printed++;
51
- Instruction next = instruction.getNext();
52
- if (printed < count && next != null) {
53
- // next() is null when the instruction ends its address space, so the gap is
54
- // measured from the instruction's last byte.
55
- Address last = instruction.getMaxAddress();
56
- Address end = last.next();
57
- if (end == null) {
58
- println("gap: no instruction after " + last + " up to " + next.getAddress());
59
- } else if (!next.getAddress().equals(end)) {
60
- println("gap: no instruction from " + end + " up to " + next.getAddress());
61
- }
62
- }
63
- instruction = next;
64
- }
65
- if (printed < count) {
66
- println("The listing ends after " + printed + " of " + count + " instructions.");
67
- } else {
68
- println("Printed " + printed + " instructions.");
69
- }
70
- }
71
- }