scientific-method-engine 11.0.0__tar.gz → 13.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 (76) hide show
  1. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/PKG-INFO +12 -5
  2. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/README.md +11 -4
  3. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +13 -8
  5. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportReferences.java +7 -1
  6. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +14 -11
  7. scientific_method_engine-13.0.0/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +29 -0
  8. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/trace.py +50 -20
  9. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_oracle.py +6 -0
  10. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_pe.py +8 -0
  11. scientific_method_engine-13.0.0/tests/test_return_checks.py +247 -0
  12. scientific_method_engine-11.0.0/tests/test_return_checks.py +0 -134
  13. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/.gitignore +0 -0
  14. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/LICENSE +0 -0
  15. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/__init__.py +0 -0
  16. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/__main__.py +0 -0
  17. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/cli.py +0 -0
  18. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  19. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  20. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  21. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  22. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  23. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  24. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  25. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  26. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  27. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  28. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  29. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  30. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  31. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  32. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  33. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  34. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  35. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  36. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  37. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  38. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  39. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  40. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  41. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  42. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  43. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  44. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  45. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  46. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  47. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  48. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  49. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  50. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  51. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/image.py +0 -0
  52. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/loops.py +0 -0
  53. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/machine.py +0 -0
  54. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  55. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  56. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  57. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/pe.py +0 -0
  58. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/relational.py +0 -0
  59. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/reports.py +0 -0
  60. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  61. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/src/scientific_method_engine/x86/values.py +0 -0
  62. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/oracle.py +0 -0
  63. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_continuation_budget.py +0 -0
  64. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_dispatch.py +0 -0
  65. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_effect_order.py +0 -0
  66. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_enter_frames.py +0 -0
  67. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_entry_frame.py +0 -0
  68. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_indirect_far_transfers.py +0 -0
  69. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_interrupt_models.py +0 -0
  70. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_loops.py +0 -0
  71. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_memory_scopes.py +0 -0
  72. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_nested_frame_request.py +0 -0
  73. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_relational_controls.py +0 -0
  74. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_successor_rule.py +0 -0
  75. {scientific_method_engine-11.0.0 → scientific_method_engine-13.0.0}/tests/test_table_continuations.py +0 -0
  76. {scientific_method_engine-11.0.0 → scientific_method_engine-13.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: 11.0.0
3
+ Version: 13.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
@@ -51,8 +51,8 @@ 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
53
  says what a run must show). The scripts compile against Ghidra 12.1. `ReportConstantFirstArgumentCalls`,
54
- `ReportFirstArgumentCallSummary`, `ReportCallSitesWithScalars`, `ReportInstructionWindow` and
55
- `ExportBoundedFlow` load shared helpers from the `scientificmethod/` directory beside them, so pass the directory the command prints as `-scriptPath`,
54
+ `ReportFirstArgumentCallSummary`, `ReportCallSitesWithScalars`, `ReportScalarConstants`,
55
+ `ReportFunctionScalarConstants`, `ReportInstructionWindow` and `ExportBoundedFlow` load shared helpers from the `scientificmethod/` directory beside them, so pass the directory the command prints as `-scriptPath`,
56
56
  or copy that subdirectory along with the scripts.
57
57
 
58
58
  Reading code and data:
@@ -73,11 +73,11 @@ Finding references and calls:
73
73
 
74
74
  | Script | Arguments | Prints |
75
75
  |---|---|---|
76
- | `ReportReferences` | one or more addresses | references to each, with the referring instruction and function |
76
+ | `ReportReferences` | one or more addresses | references to each, with the referring instruction, function and Ghidra reference type. The type is not the access: `DATA` covers indexed reads and writes and address formation, and a memory operand Ghidra gave no reference is not listed |
77
77
  | `ReportStringReferences` | one or more literal string fragments | strings containing a fragment and their references |
78
78
  | `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 |
79
79
  | `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 |
80
- | `ReportFunctionScalarConstants` | function address, one or more scalar values | instructions inside one function using any of them, compared unsigned |
80
+ | `ReportFunctionScalarConstants` | function address, one or more scalar values | instructions inside one function using any of them, compared unsigned, as an immediate or inside a memory operand (a displacement, an absolute address or an index scale) |
81
81
  | `ReportCallArguments` | callee address | the three nearest pushed arguments at every call Ghidra references to the callee |
82
82
  | `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 |
83
83
  | `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 |
@@ -194,3 +194,10 @@ offset from the frame's entry SP, and whether the return words were read and com
194
194
  call. A width mismatch and an unbalanced stack stop the path with separate reasons. A root return
195
195
  never reads its return words, so `returned: true` on a root path says nothing about them. See the
196
196
  [command overview](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#commands).
197
+
198
+ A traced callee that rebuilds its return frame at the other width (`pop ax; push cs; push ax;
199
+ retf` over a near call, or a near return over a far frame it shortened) returns to its caller when
200
+ the return's words end where the call's frame ended (`returnCheck.endsAtFrameEnd`), the offset word
201
+ is the call's return IP, and the segment, popped or kept in CS, is the call's CS. Any other
202
+ conversion stops with the reason of the check it failed. See
203
+ [converted call frames](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#converted-call-frames).
@@ -35,8 +35,8 @@ 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
37
  says what a run must show). The scripts compile against Ghidra 12.1. `ReportConstantFirstArgumentCalls`,
38
- `ReportFirstArgumentCallSummary`, `ReportCallSitesWithScalars`, `ReportInstructionWindow` and
39
- `ExportBoundedFlow` load shared helpers from the `scientificmethod/` directory beside them, so pass the directory the command prints as `-scriptPath`,
38
+ `ReportFirstArgumentCallSummary`, `ReportCallSitesWithScalars`, `ReportScalarConstants`,
39
+ `ReportFunctionScalarConstants`, `ReportInstructionWindow` and `ExportBoundedFlow` load shared helpers from the `scientificmethod/` directory beside them, so pass the directory the command prints as `-scriptPath`,
40
40
  or copy that subdirectory along with the scripts.
41
41
 
42
42
  Reading code and data:
@@ -57,11 +57,11 @@ Finding references and calls:
57
57
 
58
58
  | Script | Arguments | Prints |
59
59
  |---|---|---|
60
- | `ReportReferences` | one or more addresses | references to each, with the referring instruction and function |
60
+ | `ReportReferences` | one or more addresses | references to each, with the referring instruction, function and Ghidra reference type. The type is not the access: `DATA` covers indexed reads and writes and address formation, and a memory operand Ghidra gave no reference is not listed |
61
61
  | `ReportStringReferences` | one or more literal string fragments | strings containing a fragment and their references |
62
62
  | `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 |
63
63
  | `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 |
64
- | `ReportFunctionScalarConstants` | function address, one or more scalar values | instructions inside one function using any of them, compared unsigned |
64
+ | `ReportFunctionScalarConstants` | function address, one or more scalar values | instructions inside one function using any of them, compared unsigned, as an immediate or inside a memory operand (a displacement, an absolute address or an index scale) |
65
65
  | `ReportCallArguments` | callee address | the three nearest pushed arguments at every call Ghidra references to the callee |
66
66
  | `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 |
67
67
  | `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 |
@@ -178,3 +178,10 @@ offset from the frame's entry SP, and whether the return words were read and com
178
178
  call. A width mismatch and an unbalanced stack stop the path with separate reasons. A root return
179
179
  never reads its return words, so `returned: true` on a root path says nothing about them. See the
180
180
  [command overview](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#commands).
181
+
182
+ A traced callee that rebuilds its return frame at the other width (`pop ax; push cs; push ax;
183
+ retf` over a near call, or a near return over a far frame it shortened) returns to its caller when
184
+ the return's words end where the call's frame ended (`returnCheck.endsAtFrameEnd`), the offset word
185
+ is the call's return IP, and the segment, popped or kept in CS, is the call's CS. Any other
186
+ conversion stops with the reason of the check it failed. See
187
+ [converted call frames](https://github.com/kibertoad/refurbished-dinosaurs-toolkit/blob/main/docs/bounded-evidence-reporters.md#converted-call-frames).
@@ -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 = "11.0.0"
8
+ version = "13.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"
@@ -1,15 +1,19 @@
1
- // Reports instruction references to selected scalar values within one function.
1
+ // Reports instruction references to selected scalar values within one function: immediates and
2
+ // memory-operand displacements, absolute addresses such as [0x41c000] and index scales.
2
3
  // @category Restoration
3
4
 
4
5
  import ghidra.app.script.GhidraScript;
5
6
  import ghidra.program.model.address.Address;
6
7
  import ghidra.program.model.listing.Function;
7
8
  import ghidra.program.model.listing.Instruction;
9
+ import ghidra.program.model.listing.InstructionIterator;
8
10
  import ghidra.program.model.scalar.Scalar;
9
11
 
10
12
  import java.util.HashSet;
11
13
  import java.util.Set;
12
14
 
15
+ import scientificmethod.OperandConstants;
16
+
13
17
  public class ReportFunctionScalarConstants extends GhidraScript {
14
18
  private static final int MAX_MATCHES = 200;
15
19
 
@@ -33,14 +37,16 @@ public class ReportFunctionScalarConstants extends GhidraScript {
33
37
  requested.add(Long.decode(arguments[index]));
34
38
 
35
39
  int matches = 0;
36
- Instruction instruction = currentProgram.getListing()
37
- .getInstructionAt(function.getEntryPoint());
38
- while (instruction != null && function.getBody().contains(instruction.getAddress())
39
- && !monitor.isCancelled()) {
40
+ // The whole body, so a chunk before the entry or past another function's code is read too.
41
+ InstructionIterator instructions = currentProgram.getListing().getInstructions(function.getBody(), true);
42
+ while (instructions.hasNext()) {
43
+ monitor.checkCancelled();
44
+ Instruction instruction = instructions.next();
40
45
  for (int operand = 0; operand < instruction.getNumOperands(); operand++) {
46
+ int operandType = instruction.getOperandType(operand);
41
47
  for (Object object : instruction.getOpObjects(operand)) {
42
- if (!(object instanceof Scalar scalar)
43
- || !requested.contains(scalar.getUnsignedValue())) continue;
48
+ Scalar scalar = OperandConstants.value(object, operandType);
49
+ if (scalar == null || !requested.contains(scalar.getUnsignedValue())) continue;
44
50
  println(scalar.getUnsignedValue() + " at " + instruction.getAddress()
45
51
  + ": " + instruction);
46
52
  if (++matches >= MAX_MATCHES) {
@@ -49,7 +55,6 @@ public class ReportFunctionScalarConstants extends GhidraScript {
49
55
  }
50
56
  }
51
57
  }
52
- instruction = instruction.getNext();
53
58
  }
54
59
  if (matches == 0) println("No requested scalar constants matched.");
55
60
  }
@@ -24,7 +24,8 @@ public class ReportReferences extends GhidraScript {
24
24
  println("===== references to " + target + " =====");
25
25
  ReferenceIterator references = currentProgram.getReferenceManager().getReferencesTo(target);
26
26
  int count = 0;
27
- while (references.hasNext() && count < MAX_REFERENCES && !monitor.isCancelled()) {
27
+ while (references.hasNext() && count < MAX_REFERENCES) {
28
+ monitor.checkCancelled();
28
29
  Reference reference = references.next();
29
30
  Instruction instruction = currentProgram.getListing().getInstructionContaining(reference.getFromAddress());
30
31
  Function function = currentProgram.getFunctionManager().getFunctionContaining(reference.getFromAddress());
@@ -38,5 +39,10 @@ public class ReportReferences extends GhidraScript {
38
39
  if (count == 0) println("No references found.");
39
40
  else if (count == MAX_REFERENCES && references.hasNext()) println("Output capped at " + MAX_REFERENCES + " references.");
40
41
  }
42
+
43
+ // Ghidra types an indexed store such as MOV [EAX*4+table],ECX as DATA, and gives an indexed
44
+ // read-modify-write no reference at all, so the type column cannot answer "who writes this".
45
+ println("Types are Ghidra's reference types, not the access an instruction makes: DATA covers"
46
+ + " indexed reads and writes and address formation. An operand Ghidra gave no reference is not listed.");
41
47
  }
42
48
  }
@@ -1,9 +1,9 @@
1
1
  // Reports bounded instruction references to explicitly supplied scalar values, as immediates or
2
- // inside memory operands (a displacement, or the scale of an index such as the 4 in [EBX + ECX*4]).
2
+ // inside memory operands (a displacement, an absolute address such as [0x41c000], or the scale of an
3
+ // index such as the 4 in [EBX + ECX*4]).
3
4
  // @category Restoration
4
5
 
5
6
  import ghidra.app.script.GhidraScript;
6
- import ghidra.program.model.lang.OperandType;
7
7
  import ghidra.program.model.listing.Function;
8
8
  import ghidra.program.model.listing.Instruction;
9
9
  import ghidra.program.model.listing.InstructionIterator;
@@ -12,6 +12,8 @@ import ghidra.program.model.scalar.Scalar;
12
12
  import java.util.HashSet;
13
13
  import java.util.Set;
14
14
 
15
+ import scientificmethod.OperandConstants;
16
+
15
17
  public class ReportScalarConstants extends GhidraScript {
16
18
  private static final int MAX_MATCHES = 300;
17
19
 
@@ -36,11 +38,12 @@ public class ReportScalarConstants extends GhidraScript {
36
38
  monitor.checkCancelled();
37
39
  Instruction instruction = instructions.next();
38
40
  for (int operand = 0; operand < instruction.getNumOperands(); operand++) {
41
+ int operandType = instruction.getOperandType(operand);
39
42
  String operandKind = null;
40
43
  for (Object object : instruction.getOpObjects(operand)) {
41
- if (!(object instanceof Scalar scalar)
42
- || !matchesRequested(scalar, requested)) continue;
43
- if (operandKind == null) operandKind = operandKind(instruction.getOperandType(operand));
44
+ Scalar scalar = OperandConstants.value(object, operandType);
45
+ if (scalar == null || !matchesRequested(scalar, requested)) continue;
46
+ if (operandKind == null) operandKind = operandKind(instruction, operand);
44
47
  if (kind != null && !kind.equals(operandKind)) break;
45
48
  if (matches == MAX_MATCHES) {
46
49
  println("Output capped at " + MAX_MATCHES + " matches; the search did not finish. "
@@ -61,12 +64,12 @@ public class ReportScalarConstants extends GhidraScript {
61
64
  else println("Matched " + matches + " operands; the search covered every disassembled instruction.");
62
65
  }
63
66
 
64
- // Ghidra types an immediate operand SCALAR, adding ADDRESS when it points into the program
65
- // (PUSH 0x41c000 to a string). A memory operand is never SCALAR: a displacement such as the one in
66
- // [ECX + 0x44] or the scale in [EBX + ECX*4] makes it DYNAMIC, and an absolute one such as
67
- // [0x41c000] is ADDRESS with its address as the scalar object.
68
- private static String operandKind(int type) {
69
- return OperandType.isScalar(type) ? "immediate" : "memory";
67
+ // Ghidra's operand types do not tell the two kinds apart: LEA EAX,[0x41c000] and the 16-bit
68
+ // CALLF [0x1234] are SCALAR like an immediate, and the far direct target in CALLF 0x12:0x12345678
69
+ // is ADDRESS and CODE like an absolute memory operand. Ghidra writes every memory operand in
70
+ // brackets ([0x41c000], [ECX + 0x44], FS:[0x0]) and no immediate.
71
+ private static String operandKind(Instruction instruction, int operand) {
72
+ return instruction.getDefaultOperandRepresentation(operand).contains("[") ? "memory" : "immediate";
70
73
  }
71
74
 
72
75
  // Arguments are decoded as signed longs while operands are reported unsigned, so a request
@@ -0,0 +1,29 @@
1
+ package scientificmethod;
2
+
3
+ import ghidra.program.model.address.Address;
4
+ import ghidra.program.model.lang.OperandType;
5
+ import ghidra.program.model.scalar.Scalar;
6
+
7
+ /**
8
+ * The operand constant reading that ReportScalarConstants and ReportFunctionScalarConstants share, so
9
+ * both match the same operands. It lives in a package directory beside the scripts so that Ghidra
10
+ * compiles it with them and the Script Manager does not list it as a script.
11
+ */
12
+ public final class OperandConstants {
13
+ private OperandConstants() {
14
+ }
15
+
16
+ /**
17
+ * The constant that one of an operand's objects encodes, or null when it encodes none. A
18
+ * displacement, scale or immediate is a Scalar, and so is each part of a far direct target such
19
+ * as CALLF 0x12:0x12345678. An absolute memory operand such as [0x41c000] holds its address as an
20
+ * Address. A near direct branch target is an Address too, but in a CODE operand: Ghidra computes
21
+ * it from a relative displacement, so it never matches.
22
+ */
23
+ public static Scalar value(Object object, int operandType) {
24
+ if (object instanceof Scalar scalar) return scalar;
25
+ if (object instanceof Address address && !OperandType.isCodeReference(operandType))
26
+ return new Scalar(address.getSize(), address.getOffset(), false);
27
+ return null;
28
+ }
29
+ }
@@ -407,6 +407,12 @@ CHECK_FAILED_UNREAD = "not read: the width or stack balance check failed"
407
407
  WORD_READ_STOPPED = "not compared: reading the return words stopped the path"
408
408
  TARGET_CHECK_FAILED_UNREAD = "not read: the return target check failed"
409
409
  WORD_VALUE_UNKNOWN = "not compared: the word read and the call's word are not both known values"
410
+ # The stop for a segment that is not the call's CS, by return kind and by whether both values are known.
411
+ # A near return over a far call frame the callee converted leaves CS as it is; it must be the call's.
412
+ SEGMENT_STOPS = {("retf", True): "far return segment changed",
413
+ ("retf", False): "far return segment is not known to be the call's",
414
+ ("ret", True): "CS after a near return over a far call frame is not the call's segment",
415
+ ("ret", False): "CS after a near return over a far call frame is not known to be the call's segment"}
410
416
 
411
417
 
412
418
  def return_word_check(matches, known):
@@ -416,26 +422,46 @@ def return_word_check(matches, known):
416
422
  return "matches the call" if matches else "does not match the call" if known else WORD_VALUE_UNKNOWN
417
423
 
418
424
 
425
+ def return_followed(check):
426
+ """Whether a return passed its frame checks: the width and balance match, or the frame is a traced
427
+ call frame its callee converted to the other width so that the popped words end at its end."""
428
+ if check["widthMatches"]:
429
+ return check["stackBalanced"]
430
+ return check["frame"] == "call" and check["endsAtFrameEnd"]
431
+
432
+
419
433
  def return_check(state, frame, instruction_bytes, far):
420
434
  """The checks a return makes against its frame, before any return word is read.
421
435
 
422
- ``target`` (and ``segment`` for a far return) records whether the return words were read and
423
- compared with the call. An entry frame's are never read, so a returned root path says nothing
424
- about what its return words hold.
436
+ ``endsAtFrameEnd`` says whether the words the instruction pops end where the frame's return
437
+ words ended. With equal widths that is the balance check. With different widths it is the
438
+ condition for a converted frame: a traced callee that rebuilt its near frame as a far one, or
439
+ its far frame as a near one, so that its return leaves SP where the call's own return would.
440
+ A traced call's frame that meets it has its return words read and compared with the call as
441
+ for a matching return. The root frame has no traced caller, so its conversion is not followed.
442
+
443
+ ``target`` (and ``segment`` for a far return, or a near return over a traced far call frame)
444
+ records whether the return words were read and compared with the call. An entry frame's are
445
+ never read, so a returned root path says nothing about what its return words hold.
425
446
  """
426
447
  sp, entry_sp = state.reg(state.sp), frame["sp"]
427
448
  offset = state.frame_offset(sp, absolute=True)
428
- check = {"frame": "entry" if len(state.frames) == 1 else "call",
449
+ root = len(state.frames) == 1
450
+ width_matches = frame["returnBytes"] == instruction_bytes
451
+ balanced = sp.term == entry_sp.term
452
+ ends = balanced if width_matches else offset is not None and offset + instruction_bytes == frame["returnBytes"]
453
+ check = {"frame": "entry" if root else "call",
429
454
  "frameBytes": frame["returnBytes"], "instructionBytes": instruction_bytes,
430
- "widthMatches": frame["returnBytes"] == instruction_bytes,
431
- "spOffset": offset, "stackBalanced": sp.term == entry_sp.term}
455
+ "widthMatches": width_matches, "spOffset": offset, "stackBalanced": balanced,
456
+ "endsAtFrameEnd": ends}
432
457
  if "frameSource" in frame:
433
458
  check["frameSource"] = frame["frameSource"]
434
- unread = (ENTRY_TARGET_UNREAD if len(state.frames) == 1 else
435
- WORD_READ_STOPPED if check["widthMatches"] and check["stackBalanced"] else CHECK_FAILED_UNREAD)
436
- check["target"] = unread
437
- if far:
438
- check["segment"] = unread
459
+ check["target"] = (ENTRY_TARGET_UNREAD if root else WORD_READ_STOPPED if return_followed(check)
460
+ else CHECK_FAILED_UNREAD)
461
+ # A near return narrower than a traced call's frame is one over a far frame, whose CS it compares.
462
+ # A near return over a frame of its own width (a PE32 near call's four bytes) has no segment.
463
+ if far or not (root or width_matches):
464
+ check["segment"] = check["target"]
439
465
  return check
440
466
 
441
467
 
@@ -970,7 +996,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
970
996
  if state.argument_window:
971
997
  call_event["argumentSlots"] = state.argument_slots(call_event["returnFrameBytes"], state.argument_window)
972
998
  state.frames.append({"entry": target, "sp": state.reg(state.sp), "returnBytes": call_event["returnFrameBytes"],
973
- "frameSource": "push-CS/near-call; matching far return required" if push_cs else m,
999
+ "frameSource": "push-CS/near-call" if push_cs else m,
974
1000
  "continuation": following, "returnIP": return_ip, "callSite": at,
975
1001
  "callerCS": state.reg("cs"), "localFlagsFrame": flags_frame})
976
1002
  if m == "lcall":
@@ -1003,12 +1029,12 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
1003
1029
  frame = state.frames[-1]
1004
1030
  roles = result_contracts(state, contracts, frame["entry"])
1005
1031
  # The entry frame gets the same width and balance checks as a traced call. The return
1006
- # words are read only for a traced call, after both checks pass.
1032
+ # words are read only for a traced call, after both checks pass or over a converted frame.
1007
1033
  check = return_check(state, frame, 4 if m == "retf" else image.bits // 8, m == "retf")
1008
1034
  state.event("return", registers=snapshot(state), cleanupBytes=ins.operands[0].imm if ins.operands else 0,
1009
1035
  resultContracts=roles, callSite=frame.get("callSite"),
1010
1036
  callerEntry=state.frames[-2]["entry"] if len(state.frames) > 1 else None, returnCheck=check)
1011
- if not check["widthMatches"] or not check["stackBalanced"]:
1037
+ if not return_followed(check):
1012
1038
  raise StopPath(RETURN_CHECK_STOPS[check["widthMatches"], check["stackBalanced"]])
1013
1039
  if len(state.frames) == 1:
1014
1040
  finish(state, returned=True)
@@ -1016,15 +1042,19 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
1016
1042
  actual_ip = state.pop(image.bits // 8)
1017
1043
  check["target"] = return_word_check(actual_ip.number == frame["returnIP"], actual_ip.number is not None)
1018
1044
  if actual_ip.number != frame["returnIP"]:
1019
- if m == "retf":
1045
+ if "segment" in check:
1020
1046
  check["segment"] = TARGET_CHECK_FAILED_UNREAD
1021
1047
  raise StopPath("return target was overwritten or has unknown provenance")
1022
- if m == "retf":
1023
- actual_cs = state.pop(2)
1024
- check["segment"] = return_word_check(actual_cs.term == frame["callerCS"].term,
1025
- actual_cs.number is not None and frame["callerCS"].number is not None)
1048
+ # A far return reads the segment word; a near return over a converted far frame keeps CS.
1049
+ actual_cs = state.pop(2) if m == "retf" else state.reg("cs") if "segment" in check else None
1050
+ if actual_cs is not None:
1051
+ # The same term is the same value, known or not. A different term is a different
1052
+ # segment only when both values are known.
1053
+ known = actual_cs.number is not None and frame["callerCS"].number is not None
1054
+ check["segment"] = return_word_check(actual_cs.term == frame["callerCS"].term, known)
1026
1055
  if actual_cs.term != frame["callerCS"].term:
1027
- raise StopPath("far return segment changed")
1056
+ raise StopPath(SEGMENT_STOPS["retf" if m == "retf" else "ret", known])
1057
+ if m == "retf":
1028
1058
  state.setreg("cs", actual_cs, at)
1029
1059
  if ins.operands:
1030
1060
  state.setreg(state.sp, op("add", state.reg(state.sp), const(ins.operands[0].imm, image.bits), at), at)
@@ -62,6 +62,12 @@ class Stack(unittest.TestCase):
62
62
  def test_push_pop_and_leave(self):
63
63
  check(self, "b81100 50 6a22 5b 59 55 89e5 6a33 c9 c3", resolved=("bx", "cx", "sp"))
64
64
 
65
+ def test_converted_return_frames(self):
66
+ # call near; mov cx,sp; ret | pop ax; push cs; push ax; retf: the callee returns far over its near frame.
67
+ check(self, "e80300 89e1 c3 58 0e 50 cb", resolved=("ax", "cx", "sp"))
68
+ # push cs; call near; mov cx,sp; ret | pop ax; pop dx; push ax; ret 0: near over the push-CS far frame.
69
+ check(self, "0e e80300 89e1 c3 58 5a 50 c20000", resolved=("ax", "cx", "dx", "sp"))
70
+
65
71
  def test_enter_frames(self):
66
72
  # mov bp, 1111h; ENTER size,level; mov ax, bp; mov cx, sp; [mov bx,[bp-2]]; mov dx,[bp]; leave; ret
67
73
  for enter in ("c8040000", "c8000000", "c8ffff00", "c8040020"):
@@ -392,6 +392,14 @@ class PEReporterTests(unittest.TestCase):
392
392
  self.assertEqual(arg['argument']['offsetFromEntrySP'], 4)
393
393
  self.assertEqual(arg['width'], 4)
394
394
 
395
+ def test_a_nested_near_return_over_a_four_byte_frame_has_no_segment_check(self):
396
+ # A PE32 near call's frame is four bytes, the width of its near return. Nothing reads a segment.
397
+ r = report('e8 01 00 00 00 c3 c3')
398
+ self.assertTrue(r['completeWithinModel'], r)
399
+ check = next(e for e in events(r, 'return') if e['depth'] == 1)['returnCheck']
400
+ self.assertEqual((check['frameBytes'], check['instructionBytes'], check['target']), (4, 4, 'matches the call'))
401
+ self.assertNotIn('segment', check)
402
+
395
403
  def test_arguments_follow_an_enter_frame(self):
396
404
  c = Code().emit('68 78 56 34 12').branch('e8', 'callee').emit('83 c4 04 c3')
397
405
  c.label('callee').emit('c8 08 00 00 8b 45 08 c9 c3')
@@ -0,0 +1,247 @@
1
+ """Which checks a return made against its frame (returnCheck), and the stop each failure gives. Synthetic code only."""
2
+ import unittest
3
+ from test_x86 import events, report, run_report
4
+
5
+ ENTRY_UNREAD = "not read: the entry frame has no traced caller"
6
+ CHECK_FAILED = "not read: the width or stack balance check failed"
7
+ UNKNOWN_WORD = "not compared: the word read and the call's word are not both known values"
8
+
9
+
10
+ def only(result, kind="return", depth=None):
11
+ found = [e for e in events(result, kind) if depth is None or e["depth"] == depth]
12
+ assert len(found) == 1, found
13
+ return found[0]
14
+
15
+
16
+ def stops(result):
17
+ return {p["stop"] for p in result["paths"]}
18
+
19
+
20
+ class RootReturnChecks(unittest.TestCase):
21
+ def test_a_far_return_from_a_near_entry_fails_the_width_check_alone(self):
22
+ r = report("cb")
23
+ self.assertEqual(stops(r), {"return width differs from the call frame"})
24
+ self.assertFalse(r["completeWithinModel"])
25
+ self.assertEqual(only(r)["returnCheck"], {
26
+ "frame": "entry", "frameBytes": 2, "instructionBytes": 4, "widthMatches": False,
27
+ "spOffset": 0, "stackBalanced": True, "endsAtFrameEnd": False, "target": ENTRY_UNREAD,
28
+ "segment": ENTRY_UNREAD})
29
+
30
+ def test_a_near_return_from_a_far_entry_fails_the_width_check_alone(self):
31
+ r = report("c3", returnBytes=4)
32
+ self.assertEqual(stops(r), {"return width differs from the call frame"})
33
+ check = only(r)["returnCheck"]
34
+ self.assertEqual((check["frameBytes"], check["instructionBytes"], check["stackBalanced"]), (4, 2, True))
35
+ self.assertNotIn("segment", check)
36
+
37
+ def test_an_extra_push_fails_the_balance_check_alone(self):
38
+ r = report("50 c3")
39
+ self.assertEqual(stops(r), {"stack balance differs from the call"})
40
+ check = only(r)["returnCheck"]
41
+ self.assertEqual((check["widthMatches"], check["stackBalanced"], check["spOffset"]), (True, False, -2))
42
+
43
+ def test_both_failures_are_named_together(self):
44
+ r = report("50 cb")
45
+ self.assertEqual(stops(r), {"return width and stack balance differ from the call frame"})
46
+ check = only(r)["returnCheck"]
47
+ self.assertEqual((check["widthMatches"], check["stackBalanced"], check["spOffset"]), (False, False, -2))
48
+
49
+ def test_the_offset_counts_from_a_concrete_entry_sp(self):
50
+ check = only(report("50 c3", registers={"ss": 0x9000, "sp": 0x8000}))["returnCheck"]
51
+ self.assertEqual((check["spOffset"], check["stackBalanced"]), (-2, False))
52
+
53
+ def test_an_sp_at_no_offset_from_the_entry_reports_no_offset(self):
54
+ # mov sp, ax: SP takes an unknown value unrelated to the entry SP.
55
+ r = report("8b e0 c3")
56
+ self.assertEqual(stops(r), {"stack balance differs from the call"})
57
+ self.assertIsNone(only(r)["returnCheck"]["spOffset"])
58
+
59
+ def test_a_returned_root_path_says_its_return_words_were_not_read(self):
60
+ # Positive control: the declared far entry returns, but nothing checked the root frame's words.
61
+ r = report("cb", returnBytes=4)
62
+ self.assertTrue(r["completeWithinModel"])
63
+ self.assertTrue(r["paths"][0]["returned"])
64
+ self.assertEqual(only(r)["returnCheck"], {
65
+ "frame": "entry", "frameBytes": 4, "instructionBytes": 4, "widthMatches": True,
66
+ "spOffset": 0, "stackBalanced": True, "endsAtFrameEnd": True, "target": ENTRY_UNREAD,
67
+ "segment": ENTRY_UNREAD})
68
+
69
+ def test_a_root_frame_converted_by_its_own_body_is_not_followed(self):
70
+ # pop ax; push cs; push ax; retf from a near entry: the words end at the entry frame's end, but
71
+ # the root has no traced caller to compare them with, so the width and balance stop stays.
72
+ r = report("58 0e 50 cb")
73
+ self.assertEqual(stops(r), {"return width and stack balance differ from the call frame"})
74
+ check = only(r)["returnCheck"]
75
+ self.assertEqual((check["endsAtFrameEnd"], check["target"]), (True, ENTRY_UNREAD))
76
+
77
+
78
+ class TracedCallReturnChecks(unittest.TestCase):
79
+ def test_a_nested_near_return_compares_its_target(self):
80
+ r = report("e8 01 00 c3 c3")
81
+ self.assertTrue(r["completeWithinModel"])
82
+ self.assertEqual(only(r, depth=1)["returnCheck"], {
83
+ "frame": "call", "frameSource": "call", "frameBytes": 2, "instructionBytes": 2, "widthMatches": True,
84
+ "spOffset": 0, "stackBalanced": True, "endsAtFrameEnd": True, "target": "matches the call"})
85
+ self.assertEqual(only(r, depth=0)["returnCheck"]["target"], ENTRY_UNREAD)
86
+
87
+ def test_a_nested_far_return_compares_target_and_segment(self):
88
+ r = report("0e e8 01 00 cb cb", returnBytes=4)
89
+ self.assertTrue(r["completeWithinModel"])
90
+ check = only(r, depth=1)["returnCheck"]
91
+ self.assertEqual((check["frameBytes"], check["target"], check["segment"]), (4, "matches the call", "matches the call"))
92
+ self.assertEqual(check["frameSource"], "push-CS/near-call")
93
+
94
+ def test_an_overwritten_nested_target_is_compared_and_rejected(self):
95
+ # pop ax; push 5; ret
96
+ r = report("e8 01 00 c3 58 6a 05 c3")
97
+ self.assertEqual(stops(r), {"return target was overwritten or has unknown provenance"})
98
+ check = only(r, depth=1)["returnCheck"]
99
+ self.assertEqual((check["widthMatches"], check["stackBalanced"], check["target"]), (True, True, "does not match the call"))
100
+
101
+ def test_a_changed_nested_segment_is_compared_and_rejected(self):
102
+ # pop ax; pop bx; push 0; push ax; retf
103
+ r = report("0e e8 01 00 cb 58 5b 6a 00 50 cb", returnBytes=4)
104
+ self.assertEqual(stops(r), {"far return segment changed"})
105
+ check = only(r, depth=1)["returnCheck"]
106
+ self.assertEqual((check["target"], check["segment"]), ("matches the call", "does not match the call"))
107
+
108
+ def test_an_unknown_nested_target_is_not_reported_as_different(self):
109
+ # pop ax; push bx; ret: BX holds no known value, so the word is neither a match nor a difference.
110
+ r = report("e8 01 00 c3 58 53 c3")
111
+ self.assertEqual(stops(r), {"return target was overwritten or has unknown provenance"})
112
+ self.assertEqual(only(r, depth=1)["returnCheck"]["target"], UNKNOWN_WORD)
113
+
114
+ def test_an_unknown_far_target_leaves_the_segment_unread(self):
115
+ # pop ax; push bx; retf
116
+ r = report("0e e8 01 00 cb 58 53 cb", returnBytes=4)
117
+ check = only(r, depth=1)["returnCheck"]
118
+ self.assertEqual((check["target"], check["segment"]), (UNKNOWN_WORD, "not read: the return target check failed"))
119
+
120
+ def test_an_unknown_nested_segment_is_not_reported_as_different(self):
121
+ # pop ax; pop bx; push dx; push ax; retf
122
+ r = report("0e e8 01 00 cb 58 5b 52 50 cb", returnBytes=4)
123
+ self.assertEqual(stops(r), {"far return segment is not known to be the call's"})
124
+ check = only(r, depth=1)["returnCheck"]
125
+ self.assertEqual((check["target"], check["segment"]), ("matches the call", UNKNOWN_WORD))
126
+
127
+ def test_an_unbalanced_return_over_a_matching_frame_does_not_end_at_the_frame_end(self):
128
+ check = only(report("e8 01 00 c3 50 c3"), depth=1)["returnCheck"]
129
+ self.assertEqual((check["stackBalanced"], check["endsAtFrameEnd"], check["target"]), (False, False, CHECK_FAILED))
130
+
131
+
132
+ # The root calls near 4 and returns far at 3; the callee at 4 converts its near frame before its RETF.
133
+ NEAR_CALL_ROOT = "e8 01 00 cb "
134
+
135
+
136
+ def far_call(callee, segment):
137
+ """``lcall`` to ``callee`` (a hex string) in a region at ``segment``, from a root in segment 1000h."""
138
+ same = segment == 0x1000
139
+ data = bytes.fromhex("9a" + ("0600" if same else "0000") + segment.to_bytes(2, "little").hex() + "c3" + callee)
140
+ regions = [{"name": "caller", "start": 0, "end": 6, "ip": 0, "segment": 0x1000, "resident": True, "entries": [0],
141
+ "evidence": "synthetic declared code extent"},
142
+ {"name": "callee", "start": 6, "end": len(data), "ip": 6 if same else 0, "segment": segment,
143
+ "resident": True, "entries": [6], "evidence": "synthetic declared code extent"}]
144
+ config = {"regions": regions, "entry": 0, "relocations": [{"site": 3, "segment": segment, "evidence": "synthetic"}]}
145
+ return run_report(data, config, "trace")
146
+
147
+
148
+ class ConvertedCallFrames(unittest.TestCase):
149
+ """A traced callee that rebuilds its return frame at the other width before returning."""
150
+
151
+ def test_a_near_frame_converted_to_a_far_one_returns_through_the_caller(self):
152
+ # Positive control: pop ax; push cs; push ax; retf. The caller's far return then consumes the root frame.
153
+ r = report(NEAR_CALL_ROOT + "58 0e 50 cb", returnBytes=4)
154
+ path = r["paths"][0]
155
+ self.assertTrue(r["completeWithinModel"], path["stop"])
156
+ self.assertEqual(only(r, depth=1)["returnCheck"], {
157
+ "frame": "call", "frameSource": "call", "frameBytes": 2, "instructionBytes": 4, "widthMatches": False,
158
+ "spOffset": -2, "stackBalanced": False, "endsAtFrameEnd": True, "target": "matches the call",
159
+ "segment": "matches the call"})
160
+ self.assertEqual(path["registers"]["ax"]["value"], 3)
161
+ # The root return balances against the entry SP.
162
+ self.assertTrue(only(r, depth=0)["returnCheck"]["stackBalanced"])
163
+ self.assertEqual(only(r, "call-return")["callSite"], 0)
164
+
165
+ def test_the_ordinary_near_and_caller_built_far_controls_still_return(self):
166
+ self.assertTrue(report(NEAR_CALL_ROOT[:-3] + "c3 c3")["completeWithinModel"])
167
+ self.assertTrue(report("0e " + NEAR_CALL_ROOT + "cb", returnBytes=4)["completeWithinModel"])
168
+
169
+ def test_a_wrong_segment_word_stays_rejected(self):
170
+ # pop ax; push 0; push ax; retf: the stack ends where the call frame ended, but the segment is not CS.
171
+ r = report(NEAR_CALL_ROOT + "58 6a 00 50 cb", returnBytes=4)
172
+ self.assertEqual(stops(r), {"far return segment changed"})
173
+ self.assertFalse(r["completeWithinModel"])
174
+ check = only(r, depth=1)["returnCheck"]
175
+ self.assertEqual((check["endsAtFrameEnd"], check["target"], check["segment"]),
176
+ (True, "matches the call", "does not match the call"))
177
+
178
+ def test_an_unknown_segment_word_is_not_compared(self):
179
+ # pop ax; push dx; push ax; retf
180
+ r = report(NEAR_CALL_ROOT + "58 52 50 cb", returnBytes=4)
181
+ self.assertEqual(stops(r), {"far return segment is not known to be the call's"})
182
+ self.assertEqual(only(r, depth=1)["returnCheck"]["segment"], UNKNOWN_WORD)
183
+
184
+ def test_an_overwritten_or_unknown_offset_word_stays_rejected(self):
185
+ # pop ax; push cs; push 5; retf | push cs; retf (CS where the offset should be) | pop ax; push cs; push bx; retf
186
+ for code, target in (("58 0e 6a 05 cb", "does not match the call"), ("0e cb", "does not match the call"),
187
+ ("58 0e 53 cb", UNKNOWN_WORD)):
188
+ with self.subTest(code=code):
189
+ r = report(NEAR_CALL_ROOT + code, returnBytes=4)
190
+ self.assertEqual(stops(r), {"return target was overwritten or has unknown provenance"})
191
+ check = only(r, depth=1)["returnCheck"]
192
+ self.assertEqual((check["target"], check["segment"]), (target, "not read: the return target check failed"))
193
+
194
+ def test_an_incomplete_conversion_fails_the_width_check(self):
195
+ # pop ax; push cs; retf: the far return would pop a word of the caller's stack as its segment.
196
+ r = report(NEAR_CALL_ROOT + "58 0e cb", returnBytes=4)
197
+ self.assertEqual(stops(r), {"return width differs from the call frame"})
198
+ check = only(r, depth=1)["returnCheck"]
199
+ self.assertEqual((check["spOffset"], check["endsAtFrameEnd"], check["target"], check["segment"]),
200
+ (0, False, CHECK_FAILED, CHECK_FAILED))
201
+
202
+ def test_an_extra_word_left_on_a_converted_frame_fails_both_checks(self):
203
+ # pop ax; push cs; push ax; push ax; retf
204
+ r = report(NEAR_CALL_ROOT + "58 0e 50 50 cb", returnBytes=4)
205
+ self.assertEqual(stops(r), {"return width and stack balance differ from the call frame"})
206
+ self.assertFalse(only(r, depth=1)["returnCheck"]["endsAtFrameEnd"])
207
+
208
+ def test_a_converted_frame_releases_arguments_and_keeps_their_reads(self):
209
+ # push 7; call; retf | pop ax; push cs; push ax; push bp; mov bp,sp; mov bx,[bp+6]; pop bp; retf 2
210
+ r = report("6a 07 e8 01 00 cb 58 0e 50 55 89 e5 8b 5e 06 5d ca 02 00", returnBytes=4)
211
+ path = r["paths"][0]
212
+ self.assertTrue(r["completeWithinModel"], path["stop"])
213
+ self.assertEqual(path["registers"]["bx"]["value"], 7)
214
+ self.assertTrue(only(r, depth=0)["returnCheck"]["stackBalanced"])
215
+ argument = [e for e in events(r, "read") if e.get("argument")]
216
+ self.assertEqual([(a["argument"]["offsetFromEntrySP"], a["argument"]["width"], a["argument"]["returnFrameBytes"])
217
+ for a in argument], [(2, 2, 2)])
218
+
219
+ def test_a_far_frame_converted_to_a_near_one_returns_in_the_same_segment(self):
220
+ # push cs; call near; ret | pop ax; pop dx; push ax; ret: the near return leaves CS, which is the call's.
221
+ r = report("0e e8 01 00 c3 58 5a 50 c3")
222
+ self.assertTrue(r["completeWithinModel"], r["paths"][0]["stop"])
223
+ check = only(r, depth=1)["returnCheck"]
224
+ self.assertEqual((check["frameBytes"], check["instructionBytes"], check["spOffset"], check["endsAtFrameEnd"],
225
+ check["target"], check["segment"]), (4, 2, 2, True, "matches the call", "matches the call"))
226
+ self.assertTrue(far_call("58 5a 50 c3", 0x1000)["completeWithinModel"])
227
+
228
+ def test_a_near_return_over_a_far_call_into_another_segment_stays_rejected(self):
229
+ r = far_call("58 5a 50 c3", 0x2000)
230
+ self.assertEqual(stops(r), {"CS after a near return over a far call frame is not the call's segment"})
231
+ self.assertEqual(only(r, depth=1)["returnCheck"]["segment"], "does not match the call")
232
+
233
+ def test_a_near_return_over_an_unconverted_far_frame_fails_the_width_check(self):
234
+ # push cs; call near; ret | ret
235
+ r = report("0e e8 01 00 c3 c3")
236
+ self.assertEqual(stops(r), {"return width differs from the call frame"})
237
+ check = only(r, depth=1)["returnCheck"]
238
+ self.assertEqual((check["endsAtFrameEnd"], check["segment"]), (False, CHECK_FAILED))
239
+
240
+ def test_the_step_limit_at_the_converting_return_stops_before_it(self):
241
+ r = report(NEAR_CALL_ROOT + "58 0e 50 cb", returnBytes=4, maxSteps=4)
242
+ self.assertEqual(stops(r), {"step limit; loop progress unresolved"})
243
+ self.assertEqual(events(r, "return"), [])
244
+
245
+
246
+ if __name__ == "__main__":
247
+ unittest.main()
@@ -1,134 +0,0 @@
1
- """Which checks a return made against its frame (returnCheck), and the stop each failure gives. Synthetic code only."""
2
- import unittest
3
- from test_x86 import events, report
4
-
5
- ENTRY_UNREAD = "not read: the entry frame has no traced caller"
6
- CHECK_FAILED = "not read: the width or stack balance check failed"
7
- UNKNOWN_WORD = "not compared: the word read and the call's word are not both known values"
8
-
9
-
10
- def only(result, kind="return", depth=None):
11
- found = [e for e in events(result, kind) if depth is None or e["depth"] == depth]
12
- assert len(found) == 1, found
13
- return found[0]
14
-
15
-
16
- def stops(result):
17
- return {p["stop"] for p in result["paths"]}
18
-
19
-
20
- class RootReturnChecks(unittest.TestCase):
21
- def test_a_far_return_from_a_near_entry_fails_the_width_check_alone(self):
22
- r = report("cb")
23
- self.assertEqual(stops(r), {"return width differs from the call frame"})
24
- self.assertFalse(r["completeWithinModel"])
25
- self.assertEqual(only(r)["returnCheck"], {
26
- "frame": "entry", "frameBytes": 2, "instructionBytes": 4, "widthMatches": False,
27
- "spOffset": 0, "stackBalanced": True, "target": ENTRY_UNREAD, "segment": ENTRY_UNREAD})
28
-
29
- def test_a_near_return_from_a_far_entry_fails_the_width_check_alone(self):
30
- r = report("c3", returnBytes=4)
31
- self.assertEqual(stops(r), {"return width differs from the call frame"})
32
- check = only(r)["returnCheck"]
33
- self.assertEqual((check["frameBytes"], check["instructionBytes"], check["stackBalanced"]), (4, 2, True))
34
- self.assertNotIn("segment", check)
35
-
36
- def test_an_extra_push_fails_the_balance_check_alone(self):
37
- r = report("50 c3")
38
- self.assertEqual(stops(r), {"stack balance differs from the call"})
39
- check = only(r)["returnCheck"]
40
- self.assertEqual((check["widthMatches"], check["stackBalanced"], check["spOffset"]), (True, False, -2))
41
-
42
- def test_both_failures_are_named_together(self):
43
- r = report("50 cb")
44
- self.assertEqual(stops(r), {"return width and stack balance differ from the call frame"})
45
- check = only(r)["returnCheck"]
46
- self.assertEqual((check["widthMatches"], check["stackBalanced"], check["spOffset"]), (False, False, -2))
47
-
48
- def test_the_offset_counts_from_a_concrete_entry_sp(self):
49
- check = only(report("50 c3", registers={"ss": 0x9000, "sp": 0x8000}))["returnCheck"]
50
- self.assertEqual((check["spOffset"], check["stackBalanced"]), (-2, False))
51
-
52
- def test_an_sp_at_no_offset_from_the_entry_reports_no_offset(self):
53
- # mov sp, ax: SP takes an unknown value unrelated to the entry SP.
54
- r = report("8b e0 c3")
55
- self.assertEqual(stops(r), {"stack balance differs from the call"})
56
- self.assertIsNone(only(r)["returnCheck"]["spOffset"])
57
-
58
- def test_a_returned_root_path_says_its_return_words_were_not_read(self):
59
- # Positive control: the declared far entry returns, but nothing checked the root frame's words.
60
- r = report("cb", returnBytes=4)
61
- self.assertTrue(r["completeWithinModel"])
62
- self.assertTrue(r["paths"][0]["returned"])
63
- self.assertEqual(only(r)["returnCheck"], {
64
- "frame": "entry", "frameBytes": 4, "instructionBytes": 4, "widthMatches": True,
65
- "spOffset": 0, "stackBalanced": True, "target": ENTRY_UNREAD, "segment": ENTRY_UNREAD})
66
-
67
-
68
- class TracedCallReturnChecks(unittest.TestCase):
69
- def test_a_nested_near_return_compares_its_target(self):
70
- r = report("e8 01 00 c3 c3")
71
- self.assertTrue(r["completeWithinModel"])
72
- self.assertEqual(only(r, depth=1)["returnCheck"], {
73
- "frame": "call", "frameSource": "call", "frameBytes": 2, "instructionBytes": 2, "widthMatches": True,
74
- "spOffset": 0, "stackBalanced": True, "target": "matches the call"})
75
- self.assertEqual(only(r, depth=0)["returnCheck"]["target"], ENTRY_UNREAD)
76
-
77
- def test_a_nested_far_return_compares_target_and_segment(self):
78
- r = report("0e e8 01 00 cb cb", returnBytes=4)
79
- self.assertTrue(r["completeWithinModel"])
80
- check = only(r, depth=1)["returnCheck"]
81
- self.assertEqual((check["frameBytes"], check["target"], check["segment"]), (4, "matches the call", "matches the call"))
82
- self.assertIn("push-CS/near-call", check["frameSource"])
83
-
84
- def test_an_overwritten_nested_target_is_compared_and_rejected(self):
85
- # pop ax; push 5; ret
86
- r = report("e8 01 00 c3 58 6a 05 c3")
87
- self.assertEqual(stops(r), {"return target was overwritten or has unknown provenance"})
88
- check = only(r, depth=1)["returnCheck"]
89
- self.assertEqual((check["widthMatches"], check["stackBalanced"], check["target"]), (True, True, "does not match the call"))
90
-
91
- def test_a_changed_nested_segment_is_compared_and_rejected(self):
92
- # pop ax; pop bx; push 0; push ax; retf
93
- r = report("0e e8 01 00 cb 58 5b 6a 00 50 cb", returnBytes=4)
94
- self.assertEqual(stops(r), {"far return segment changed"})
95
- check = only(r, depth=1)["returnCheck"]
96
- self.assertEqual((check["target"], check["segment"]), ("matches the call", "does not match the call"))
97
-
98
- def test_an_unknown_nested_target_is_not_reported_as_different(self):
99
- # pop ax; push bx; ret: BX holds no known value, so the word is neither a match nor a difference.
100
- r = report("e8 01 00 c3 58 53 c3")
101
- self.assertEqual(stops(r), {"return target was overwritten or has unknown provenance"})
102
- self.assertEqual(only(r, depth=1)["returnCheck"]["target"], UNKNOWN_WORD)
103
-
104
- def test_an_unknown_far_target_leaves_the_segment_unread(self):
105
- # pop ax; push bx; retf
106
- r = report("0e e8 01 00 cb 58 53 cb", returnBytes=4)
107
- check = only(r, depth=1)["returnCheck"]
108
- self.assertEqual((check["target"], check["segment"]), (UNKNOWN_WORD, "not read: the return target check failed"))
109
-
110
- def test_an_unknown_nested_segment_is_not_reported_as_different(self):
111
- # pop ax; pop bx; push dx; push ax; retf
112
- r = report("0e e8 01 00 cb 58 5b 52 50 cb", returnBytes=4)
113
- self.assertEqual(stops(r), {"far return segment changed"})
114
- check = only(r, depth=1)["returnCheck"]
115
- self.assertEqual((check["target"], check["segment"]), ("matches the call", UNKNOWN_WORD))
116
-
117
- def test_a_far_return_over_a_near_call_frame_stays_rejected_with_both_failures(self):
118
- # The callee rebuilds its near frame as a far one (pop ax; push cs; push ax; retf). Width and
119
- # balance both fail against the near call, and the return words are left unread.
120
- r = report("e8 01 00 cb 58 0e 50 cb", returnBytes=4)
121
- self.assertEqual(stops(r), {"return width and stack balance differ from the call frame"})
122
- self.assertEqual(only(r, depth=1)["returnCheck"], {
123
- "frame": "call", "frameSource": "call", "frameBytes": 2, "instructionBytes": 4, "widthMatches": False,
124
- "spOffset": -2, "stackBalanced": False, "target": CHECK_FAILED, "segment": CHECK_FAILED})
125
-
126
- def test_a_wrong_segment_conversion_stays_rejected(self):
127
- # pop ax; push 0; push ax; retf
128
- r = report("e8 01 00 cb 58 6a 00 50 cb", returnBytes=4)
129
- self.assertEqual(stops(r), {"return width and stack balance differ from the call frame"})
130
- self.assertFalse(r["completeWithinModel"])
131
-
132
-
133
- if __name__ == "__main__":
134
- unittest.main()