SPF Ghidra Pattern Helper
用于生成和搜索字节签名（byte signatures）的 Ghidra pattern helper，支持可选的 SPF 风格模板。
## 这个工具是什么
`SPF Ghidra Pattern Helper` 是一个用于创建和测试字节模式的 Ghidra 脚本。
创建此脚本的目的是让 pattern 工作变得更快、更整洁、减少手动操作：
- 直接从选中的指令生成 pattern
- 使用 Ghidra 默认查找器无法很好支持的灵活字节语法进行搜索
- 在生成的输出和搜索结果之间快速切换
- 避免在不同的标签页和工具之间手工复制 pattern
## 为 [SPF Framework](https://github.com/TrackAndTruckDevs/SPF-Framework) 而创建
创建此脚本是为了让 **SPF-Framework** 的插件开发变得更快捷、更自动化。
对于 **SPF-Framework**，它还支持类似以下的紧凑型模板风格签名：
```
[MOV [r64+off8], r32] [XOR r32, r32] [CALL rel32] [MOVSS [r64+off8], xmm] [LEA r64, [r64+off8]] ...
```
这使得处理基于 SPF 插件使用的简化签名风格变得更加容易。
## 它可以生成什么
生成器可以生成相同 pattern 的多种形式：
- SPF 风格的模板输出
- 带掩码的原始十六进制 pattern（raw masked hex pattern）
- 纯原始字节
- 可供在其他工具或笔记中复用的注释文本
生成形式的示例：
```
[MOV [r64+off8], r32] [XOR r32, r32]
```
```
C7 44 24 58 ? ? ? ? 89 44 24 5C 45 33 E4 33 ED 4D
```
当你想要为 SPF 提供可读模板，或是为了手动检查而需要更明确的字节 pattern 时，这非常有用。
## 搜索语法
与标准的 Ghidra pattern 搜索相比，查找器支持更丰富的字节 pattern 语法。
支持的示例：
```
48 8B CF
; Exact bytes
; Match only these exact byte values in this order.
; Example: 48 8B CF = exact sequence.
```
```
?
??
; Wildcard bytes
; Match any single byte.
; Example: ? = one byte, ?? = same meaning, also one byte.
```
```
[1-5?]
; Length wildcard
; Match from 1 to 5 bytes of any value.
; Example: [1-5?] can cover 1, 2, 3, 4, or 5 unknown bytes.
```
```
45?
; Optional exact byte
; Byte `45` may be present or omitted.
; Examples:
; 40 45? 50 -> matches 40 50
; 40 45? 50 -> matches 40 45 50
; Useful when a byte is optional, not when only part of the byte is fixed.
```
```
[40-4C]
; Byte range
; Match any byte between 0x40 and 0x4C inclusive.
; Match one of the listed byte values or ranges.
; Example: [80|BF] matches 80 or BF.
; Example: [80|BF|C0] matches 80, BF, or C0.
; Example: [80|BF|C0-C5] matches 80, BF, or any value from C0 to C5.
[4-7]8
[4-7][8-B]
; Nibble ranges
; Example: [4-7]8 matches 48, 58, 68, 78.
; Example: [4-7][8-B] matches 48..4B, 58..5B, 68..6B, 78..7B.
```
这些 pattern 让你可以匹配确切的字节、通配符、长度范围、字节范围、OR 分组以及基于半字节（nibble）的寄存器编码。
## 主要标签页
### Pattern Generator
- 从当前选择中生成签名
- 当匹配选定的指令序列时支持 SPF 模板
- 显示带掩码的原始十六进制和原始字节
- 可选择在生成后自动检查生成的签名
- 当需要进一步检查结果时，提供快速跳转到查找器标签页的功能
### Pattern Finder
- 在加载的程序中搜索 pattern
- 支持在所有可执行段（executable sections）中搜索
- 支持在选定的内存块（memory block）中搜索
- 支持从当前光标位置进行有限范围的搜索
- 直接在 Ghidra 中显示匹配结果
## 在 Ghidra 中安装
### 脚本目录
1. 将 `GhidraPatternHelper.java` 复制到 Ghidra 脚本文件夹中。
2. 打开 Ghidra。
3. 转到 `Window -> Script Manager`。
4. 打开 `Script Directories`。
5. 添加包含 `GhidraPatternHelper.java` 的文件夹。
6. 刷新脚本列表。
7. 运行 `GhidraPatternHelper`。
### 从 Script Manager 中一次性运行
如果脚本已经存在于配置好的 Ghidra 脚本目录中：
1. 打开 `Window -> Script Manager`。
2. 找到 `GhidraPatternHelper`。
3. 直接从列表中运行它。
## 启动方式
可以通过两种方式启动该脚本：
### 菜单
- `Tools -> SPF Pattern Helper`
### 快捷键
- `Ctrl + Alt + P`
## 如何使用
### 生成 pattern
1. 在 Ghidra 中打开一个程序。
2. 在 Listing 视图中选择一个或多个指令。
3. 打开 `SPF Pattern Helper`。
4. 转到 `Pattern Generator` 标签页。
5. 点击 `Generate from Selection`。
### 搜索 pattern
1. 转到 `Pattern Finder` 标签页。
2. 粘贴或输入 pattern。
3. 选择搜索范围。
4. 点击 `Find Pattern`。
### 可选的自动检查
1. 启用 `Automatically verify signature`。
2. 从所选内容中生成 pattern。
3. 脚本将自动搜索程序。
4. 按钮下方的结果行将显示结果。
5. 如有需要，使用 `More info` 跳转到 `Pattern Finder`。
## 注意事项
- 选择稳定的指令序列通常能获得最佳结果，而不是选择极小或高度重复的片段。
- 该脚本旨在利用 [SPF Framework](https://github.com/TrackAndTruckDevs/SPF-Framework) 简化游戏《American Truck Simulator》/《Euro Truck Simulator 2》中 pattern 的开发和测试。它是在模组（mod）开发过程中用于签名搜索快速原型设计的基本工具。
- 后续更新和附加功能可能会也可能不会推出。
- 如果您对改进此功能有任何建议，请将其留在仓库中或加入我们的 Discord 聊天频道。
## 支持本项目
如果您喜欢这个插件并希望支持我们未来的项目开发，请考虑在 Patreon 上支持我们。
► **[在 Patreon 上支持](https://www.patreon.com/TrackAndTruckDevs)**