scientific-method-engine 12.0.0__tar.gz → 13.1.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-12.0.0 → scientific_method_engine-13.1.0}/PKG-INFO +5 -5
  2. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/README.md +4 -4
  3. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/pyproject.toml +1 -1
  4. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportFunctionScalarConstants.java +13 -8
  5. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportReferences.java +7 -1
  6. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportScalarConstants.java +14 -11
  7. scientific_method_engine-13.1.0/src/scientific_method_engine/ghidra/scientificmethod/OperandConstants.java +29 -0
  8. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/relational.py +9 -6
  9. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/trace.py +10 -6
  10. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/values.py +20 -2
  11. scientific_method_engine-13.1.0/tests/test_term_limit.py +120 -0
  12. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_x86.py +4 -2
  13. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/.gitignore +0 -0
  14. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/LICENSE +0 -0
  15. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/__init__.py +0 -0
  16. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/__main__.py +0 -0
  17. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/cli.py +0 -0
  18. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ClearNoReturnFunctions.java +0 -0
  19. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/CreateFunctions.java +0 -0
  20. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ExportBoundedFlow.java +0 -0
  21. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ExportCallEdges.java +0 -0
  22. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ExportFunctionFingerprints.java +0 -0
  23. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ExportFunctionInventory.java +0 -0
  24. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/MergeFallThroughFragment.java +0 -0
  25. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/RecoverCitedFunctions.java +0 -0
  26. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/RepairReturningCallers.java +0 -0
  27. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportCallArguments.java +0 -0
  28. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportCallPaths.java +0 -0
  29. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportCallSitesWithScalars.java +0 -0
  30. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportCallsToRange.java +0 -0
  31. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportConstantFirstArgumentCalls.java +0 -0
  32. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportDataBytes.java +0 -0
  33. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportDecompileMatches.java +0 -0
  34. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportDecompileWindow.java +0 -0
  35. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportFilePatternInMemory.java +0 -0
  36. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportFirstArgumentCallSummary.java +0 -0
  37. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportFunctionSummary.java +0 -0
  38. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportInstructionContext.java +0 -0
  39. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportInstructionWindow.java +0 -0
  40. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlockForFileOffset.java +0 -0
  41. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportMemoryBlocks.java +0 -0
  42. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportRandomnessCandidates.java +0 -0
  43. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportStringReferences.java +0 -0
  44. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/ReportSymbolReferences.java +0 -0
  45. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/scientificmethod/FirstArgumentLookBack.java +0 -0
  46. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/ghidra/scientificmethod/InstructionStart.java +0 -0
  47. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/__init__.py +0 -0
  48. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/argument_frames.py +0 -0
  49. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/dispatch.py +0 -0
  50. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/effect_order.py +0 -0
  51. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/image.py +0 -0
  52. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/loops.py +0 -0
  53. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/machine.py +0 -0
  54. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/memory_scopes.py +0 -0
  55. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/pcode.py +0 -0
  56. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/pcode_backend.py +0 -0
  57. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/pe.py +0 -0
  58. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/reports.py +0 -0
  59. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/src/scientific_method_engine/x86/result_flow.py +0 -0
  60. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/oracle.py +0 -0
  61. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_continuation_budget.py +0 -0
  62. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_dispatch.py +0 -0
  63. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_effect_order.py +0 -0
  64. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_enter_frames.py +0 -0
  65. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_entry_frame.py +0 -0
  66. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_indirect_far_transfers.py +0 -0
  67. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_interrupt_models.py +0 -0
  68. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_loops.py +0 -0
  69. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_memory_scopes.py +0 -0
  70. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_nested_frame_request.py +0 -0
  71. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_oracle.py +0 -0
  72. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_pe.py +0 -0
  73. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_relational_controls.py +0 -0
  74. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_return_checks.py +0 -0
  75. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_successor_rule.py +0 -0
  76. {scientific_method_engine-12.0.0 → scientific_method_engine-13.1.0}/tests/test_table_continuations.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: scientific-method-engine
3
- Version: 12.0.0
3
+ Version: 13.1.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 |
@@ -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 |
@@ -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 = "12.0.0"
8
+ version = "13.1.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
+ }
@@ -9,7 +9,7 @@ from math import inf
9
9
  from .image import integer
10
10
  from .machine import ALIASES, NO_WRITE, State, StopPath
11
11
  from .memory_scopes import SEGMENTS
12
- from .values import const, op
12
+ from .values import const, op, TermLimit
13
13
 
14
14
  KINDS = ("reach", "order", "lastWriter", "containment", "relation", "origin")
15
15
  OPERATORS = ("eq", "ne", "lt", "le", "gt", "ge")
@@ -144,14 +144,17 @@ def probe_memory(state, name, address):
144
144
  The row carries ``byteProducers`` as a read of those bytes would report them, or ``unresolved``
145
145
  when the address cannot be inspected.
146
146
  """
147
- offset = const(address.get("displacement", 0), state.bits)
148
- if "base" in address:
149
- offset = op("add", state.reg(address["base"]), offset)
150
147
  segment = state.segment(address["segment"])
151
- row = {"control": name, "segment": segment.report(), "offset": offset.report(), "width": address["width"]}
148
+ row = {"control": name, "segment": segment.report(), "offset": None, "width": address["width"]}
149
+ # A probe only observes the path, so an address it cannot form (``offset`` stays None) or
150
+ # inspect leaves the row unresolved and the path running.
152
151
  try:
152
+ offset = const(address.get("displacement", 0), state.bits)
153
+ if "base" in address:
154
+ offset = op("add", state.reg(address["base"]), offset)
155
+ row["offset"] = offset.report()
153
156
  keys = state.keys(segment, offset, address["width"])[3]
154
- except StopPath as error:
157
+ except (StopPath, TermLimit) as error:
155
158
  return {**row, "unresolved": str(error)}
156
159
  return {**row, "byteProducers": [state.byte_writer(i, key) for i, key in enumerate(keys)]}
157
160
 
@@ -6,13 +6,17 @@ from .image import integer
6
6
  from .machine import (State, StopPath, REGISTERS, ALIASES, BRANCH_CONDITIONS, string_instruction,
7
7
  string_count, string_effect, check_string_form, compare_string, repeated, string_width,
8
8
  FLAT_PORT_REASON)
9
- from .values import const, unknown, sources, op, join
9
+ from .values import const, unknown, sources, op, join, TermLimit
10
10
  from .result_flow import validate_contracts, result_contracts
11
11
  from .loops import LoopTracker
12
12
  from .memory_scopes import validate_scopes, capture_scopes, retain_scopes, scope_history
13
13
  from .pcode_backend import interrupt_vector
14
14
  from .relational import checkpoint_anchors, memory_probes, probe_memory
15
15
 
16
+ # What stops one path and leaves the others: the model cannot follow it, or a value it built
17
+ # would pass the term limit. Errors in the query still fail the run.
18
+ PATH_STOPS = (StopPath, TermLimit)
19
+
16
20
  def call_target(image, site, ins):
17
21
  if ins.mnemonic in ("lcall", "ljmp"):
18
22
  return image.far_target(site, ins)
@@ -740,7 +744,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
740
744
  try:
741
745
  value = s.get(ins, ins.operands[0], image)
742
746
  address = s.address(ins, ins.operands[0]) if ins.operands[0].type == X86_OP_MEM else None
743
- except StopPath as error:
747
+ except PATH_STOPS as error:
744
748
  global_gaps.append({"site": s.at, "reason": "conditional table operand unresolved: " + str(error)})
745
749
  return
746
750
  groups = {}
@@ -902,7 +906,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
902
906
  string_step(child, ins, count)
903
907
  child.at = following
904
908
  pending.append(child)
905
- except StopPath as error:
909
+ except PATH_STOPS as error:
906
910
  finish(child, str(error))
907
911
  string_step(state, ins, count)
908
912
  state.at = following
@@ -916,7 +920,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
916
920
  # Scopes resolve first, so a path that stops on them reports the boundary unmodeled.
917
921
  try:
918
922
  captured = capture_model_scopes(state, interrupt_model, 6)
919
- except StopPath:
923
+ except PATH_STOPS:
920
924
  state.event("hardware-boundary", boundary="interrupt", mnemonic=m, vector=vector,
921
925
  interpretation="the interrupt handler and its effects are not modeled")
922
926
  raise
@@ -989,7 +993,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
989
993
  try:
990
994
  flags_word = state.peek(state.segment("ss"), op("add", state.reg(state.sp), const(4, 16), at), 2)
991
995
  flags_frame = (16, flags_word.term) in state.saved_flags
992
- except StopPath:
996
+ except PATH_STOPS:
993
997
  flags_frame = False
994
998
  # A traced call records its return-frame width; argumentFrames maps the slots above it.
995
999
  call_event["returnFrameBytes"] = 4 if m == "lcall" or push_cs else image.bits // 8
@@ -1125,7 +1129,7 @@ def trace(image, config, continue_declared_jumps=True, track_loops=True, arrive=
1125
1129
  continue
1126
1130
  state.semantics.ordinary(state, ins, image)
1127
1131
  state.at = following
1128
- except StopPath as error:
1132
+ except PATH_STOPS as error:
1129
1133
  finish(state, str(error))
1130
1134
  if continuing:
1131
1135
  # Only continuation states are traced after the switch: deferred states are popped only when
@@ -1,6 +1,24 @@
1
1
  """Small bit-vector expressions; unknown values retain their producers."""
2
2
  from dataclasses import dataclass
3
3
 
4
+ # The most terms one value's expression may hold, counting every tuple node at any depth.
5
+ TERM_LIMIT = 1024
6
+
7
+
8
+ class TermLimit(ValueError):
9
+ """A value's expression would hold more than ``TERM_LIMIT`` terms.
10
+
11
+ A trace stops the path whose instruction built the value, with this message as the stop
12
+ reason. Raised anywhere else, it fails the run like any other ``ValueError``.
13
+ """
14
+
15
+ MESSAGE = f"expression term limit: a value's expression would hold more than {TERM_LIMIT} terms; narrow the query"
16
+
17
+ def __init__(self, message=MESSAGE):
18
+ # The message is an argument so that copying or pickling the error can rebuild it.
19
+ super().__init__(message)
20
+
21
+
4
22
  @dataclass(frozen=True)
5
23
  class Value:
6
24
  bits: int
@@ -12,8 +30,8 @@ class Value:
12
30
  while pending:
13
31
  term = pending.pop()
14
32
  count += 1
15
- if count > 1024:
16
- raise ValueError("Symbolic expression complexity limit reached; narrow the query")
33
+ if count > TERM_LIMIT:
34
+ raise TermLimit()
17
35
  if isinstance(term, tuple):
18
36
  pending.extend(item for item in term if isinstance(item, tuple))
19
37
 
@@ -0,0 +1,120 @@
1
+ """A value past the term limit stops its own path; the other paths and their controls stay."""
2
+ import copy
3
+ import pickle
4
+ import unittest
5
+ from test_x86 import Code, report
6
+ from scientific_method_engine.x86.relational import probe_memory
7
+ from scientific_method_engine.x86.values import TERM_LIMIT, TermLimit, Value, const, op
8
+
9
+ FRAME = {"ds": 0x3000, "ss": 0x9000, "sp": 0xE000}
10
+ STOP = f"expression term limit: a value's expression would hold more than {TERM_LIMIT} terms; narrow the query"
11
+
12
+
13
+ def additions(count):
14
+ """AX and BX load unknown words; a zero AX skips ``count`` additions of BX into AX."""
15
+ c = Code().emit("a1 00 01 8b 1e 02 01").label("test").emit("85 c0 0f 84")
16
+ c.fixups.append((len(c.data), 2, "done"))
17
+ c.data.extend(bytes(2))
18
+ c.label("adds")
19
+ for _ in range(count):
20
+ c.emit("01 d8")
21
+ return c.label("done").emit("cb")
22
+
23
+
24
+ def run(count, **extra):
25
+ return report(additions(count), "trace", **{"returnBytes": 4, "registers": FRAME, "maxPaths": 2, "maxSteps": count + 16, **extra})
26
+
27
+
28
+ class TermLimitTests(unittest.TestCase):
29
+ def test_a_short_sum_returns_on_both_paths(self):
30
+ r = run(8)
31
+ self.assertEqual([p["returned"] for p in r["paths"]], [True, True])
32
+ self.assertTrue(r["completeWithinModel"])
33
+
34
+ def test_a_value_past_the_limit_stops_its_path_and_keeps_the_other(self):
35
+ c = additions(600)
36
+ r = run(600)
37
+ returned, stopped = r["paths"]
38
+ self.assertTrue(returned["returned"])
39
+ self.assertIsNone(returned["stop"])
40
+ self.assertEqual(returned["events"][-1]["kind"], "return")
41
+ self.assertFalse(stopped["returned"])
42
+ self.assertEqual(stopped["stop"], STOP)
43
+ # The stop names the addition that would have built the value, and every earlier addition keeps its event.
44
+ site = stopped["stopSite"]
45
+ self.assertGreater(site, c.labels["adds"])
46
+ self.assertEqual((site - c.labels["adds"]) % 2, 0)
47
+ sums = [e for e in stopped["events"] if e["kind"] == "arithmetic"]
48
+ self.assertEqual(len(sums), (site - c.labels["adds"]) // 2)
49
+ self.assertEqual(sums[-1]["site"], site - 2)
50
+ self.assertNotIn(site, [e["site"] for e in stopped["events"]])
51
+ # The steps were not spent, so the stop is not a step limit, and no path limit is recorded.
52
+ self.assertLess(stopped["steps"], 600 + 16)
53
+ self.assertEqual(r["gaps"], [])
54
+ self.assertFalse(r["completeWithinModel"])
55
+
56
+ def test_controls_reached_before_the_stop_are_kept(self):
57
+ c = additions(600)
58
+ tested = {"name": "tested", "kind": "reach", "at": {"site": c.labels["test"]}, "expect": "always"}
59
+ result = run(600, relationalControls=[tested])["relationalControls"]["controls"][0]
60
+ self.assertEqual(result["verdict"], "held")
61
+ self.assertEqual(result["occurrences"], 2)
62
+ self.assertEqual([p["stop"] for p in result["paths"]], [None, STOP])
63
+
64
+ def test_a_control_past_the_stop_stays_undecided(self):
65
+ c = additions(600)
66
+ done = {"name": "done", "kind": "reach", "at": {"site": c.labels["done"]}, "expect": "always"}
67
+ result = run(600, relationalControls=[done])["relationalControls"]["controls"][0]
68
+ self.assertEqual(result["verdict"], "undecided")
69
+ self.assertEqual(sorted(p["verdict"] for p in result["paths"]), ["held", "undecided"])
70
+
71
+ def test_a_query_error_inside_a_path_still_fails_the_run(self):
72
+ # A four-byte model on a near call without an encoded PUSH CS is an error in the query.
73
+ c = Code().branch("e8", "next").label("next").emit("cb")
74
+ model = [{"site": 0, "evidence": "synthetic model", "returnBytes": 4, "cases": [{}]}]
75
+ with self.assertRaisesRegex(ValueError, "Modeled return width differs"):
76
+ report(c, "trace", returnBytes=4, registers=FRAME, callModels=model)
77
+
78
+ def test_a_memory_probe_past_the_limit_is_unresolved(self):
79
+ # A probe observes the path, so a base too large to offset leaves its row unresolved.
80
+ # Two terms, then two per addition: a base of TERM_LIMIT terms, which the displacement's
81
+ # offset term takes past the limit.
82
+ term = ("neg", ("unknown", "x"))
83
+ for _ in range((TERM_LIMIT - 2) // 2):
84
+ term = ("add", term, ("unknown", "y"))
85
+ Value(16, term)
86
+
87
+ class Probed:
88
+ bits = 16
89
+
90
+ def segment(self, name):
91
+ return const(0x3000, 16)
92
+
93
+ def reg(self, name):
94
+ return Value(16, term)
95
+
96
+ def keys(self, segment, offset, width):
97
+ raise AssertionError("the offset cannot be formed")
98
+
99
+ address = {"segment": "ds", "base": "bx", "displacement": 2, "width": 2}
100
+ row = probe_memory(Probed(), "probe", address)
101
+ self.assertEqual(row["unresolved"], STOP)
102
+ self.assertIsNone(row["offset"])
103
+ self.assertNotIn("byteProducers", row)
104
+
105
+ def test_the_error_survives_copy_and_pickle(self):
106
+ for rebuilt in (copy.copy(TermLimit()), pickle.loads(pickle.dumps(TermLimit()))):
107
+ self.assertIsInstance(rebuilt, TermLimit)
108
+ self.assertEqual(str(rebuilt), STOP)
109
+
110
+ def test_the_limit_outside_a_path_raises(self):
111
+ # Outside a traced path nothing can stop, so the limit fails the run as a ValueError.
112
+ value = const(1, 16)
113
+ with self.assertRaisesRegex(TermLimit, "term limit"):
114
+ for _ in range(TERM_LIMIT):
115
+ value = op("add", value, Value(16, ("unknown", "x")))
116
+ self.assertTrue(issubclass(TermLimit, ValueError))
117
+
118
+
119
+ if __name__ == "__main__":
120
+ unittest.main()
@@ -2523,8 +2523,10 @@ class ReporterTests(unittest.TestCase):
2523
2523
  self.assertEqual(b["paths"][0]["registers"]["eax"]["value"], 0xffff8080)
2524
2524
 
2525
2525
  def test_symbolic_growth_is_bounded(self):
2526
- with self.assertRaisesRegex(ValueError, "complexity"):
2527
- report("01 d8 " * 200 + "c3")
2526
+ # test_term_limit.py covers the stop beside other paths.
2527
+ path = report("01 d8 " * 200 + "c3")["paths"][0]
2528
+ self.assertFalse(path["returned"])
2529
+ self.assertTrue(path["stop"].startswith("expression term limit"))
2528
2530
 
2529
2531
 
2530
2532
  def test_dispatch_rejects_wrong_layout_and_reports_index_overrun(self):