# 打包 IDA Pro 插件此技能有助于打包 IDA Pro 插件，以便通过 IDA 插件管理器和 plugins.hex-rays.com 存储库进行分发。它涵盖了创建和更新“ida-plugin.json”清单、打包档案以及通过 GitHub Releases 进行发布。 ## 概述 IDA 插件管理器是一个用于发现、安装和共享 IDA 插件的自助服务生态系统： * **发现**：每日索引器扫描 GitHub 中包含“ida-plugin.json”的存储库 * **存储库** ：发布于 [plugins.hex-rays.com]() 和 [github.com/HexRaysSA/plugin-repository]() * **客户端** ：HCLI 命令行工具（`hcli 插件安装 `） * **兼容性**：IDA Pro 9.0+（完全支持） ## 关键：了解插件根目录 **`ida-plugin.json` 文件定义插件的根目录。** 安装插件时，仅包含 `ida-plugin.json` 的目录（及其子目录）被复制到 `$IDAUSR/plugins/`。不包括该目录之外的任何内容。 ### 评估目录结构兼容性打包之前，请验证您的插件的结构是独立的： # 好：所有插件代码都与 ida-plugin.json 位于同一目录中我的仓库/ ├── ida-plugin.json # 插件根目录 ├── my_plugin.py # 入口点 - 已包含 ├── my_plugin_lib/ # 支持代码 - 已包含 │ └── helpers.py ├── README.md # 插件自述文件 - 包含（在网络上显示） └── 资产/ └── logo.png # 徽标 - 包含 # 不好：插件代码位于 ida-plugin.json 目录之外我的仓库/ ├── 插件/ │ └── ida-plugin.json # 插件根目录在这里 ├── src/ # 不包括 - 外部插件根目录！ │ └── my_plugin.py # 这个文件不会被安装！ └── README.md # 不包括 - 错误的目录！ ### 兼容性检查表评估现有插件时，请验证： 1. **入口点位置** : `entryPoint` 是否与 `ida-plugin.json` 在同一目录中？ 2. **所有导入均可解析**：所有 Python 导入都在插件根目录中还是在 `pythonDependencies` 中？ 3. **无父目录引用**：代码是否使用`../`来访问插件根目录之外的文件？ 4. **包含的资产**：插件根目录中是否包含徽标、数据文件或资源？ 5. **README 放置** ：`README.md` 是否位于插件根目录（而不是 repo 根目录）中以供 Web 显示？ ### 常见的重组模式 **模式1：子目录中的插件** 如果您的插件代码位于“src/”或“plugin/”等子目录中，请将“ida-plugin.json”移动到该目录中： #之前#之后我的仓库/我的仓库/ ├── ida-plugin.json └── src/ └── src/ ├── ida-plugin.json # 移至此处 └── my_plugin.py ├── my_plugin.py └── README.md # 添加网页版 **模式 2：带有 IDA 插件的 Monorepo** 对于 IDA 插件是一个组件的项目（例如 capa），请将 `ida-plugin.json` 放在插件代码的位置：卡帕/ ├── 卡帕/ │ ├── 伊达/ │ │ └── 插件/ │ │ ├── ida-plugin.json # 插件根目录 │ │ ├── capa_explorer.py # 入口点 │ │ └── README.md # 插件专用文档 │ └── main.py # 不包含在IDA插件中 └── README.md # Repo README - 不是插件 README ### 插件根目录中的自述文件将 `README.md` 文件放在与 `ida-plugin.json` 相同的目录中，以使其显示在 [plugins.hex-rays.com]() Web 界面上。这与存储库的根自述文件是分开的：我的插件/ ├── ida-plugin.json ├── my_plugin.py └── README.md # 这个README出现在plugins.hex-rays.com上插件自述文件应重点关注： * 插件的作用 * 如何在IDA中使用它 * 配置选项（如果使用设置） * 屏幕截图或示例它**不需要**需要安装说明（插件管理器负责处理）。 ## ida-plugin.json 清单每个插件的根目录中都需要一个“ida-plugin.json”文件。这是除了插件代码本身之外**唯一需要的文件**。元数据文件中的路径是相对于元数据文件的，因为元数据文件定义了插件的根，即使它嵌套在 ZIP 存档中。 ### 完整架构 { “IDA元数据描述符版本”：1， “插件”：{ “名称”：“我的插件”， “版本”：“1.0.0”， "entryPoint": "my_plugin.py", "description": "该插件功能的一行描述", “许可证”：“麻省理工学院”， “网址”：{ “存储库”：“https://github.com/org/my-plugin”， “主页”：“https://example.com/my-plugin” }, “作者”：[ {“姓名”：“作者姓名”，“电子邮件”：“author@example.com”} ], “维护者”：[ {"name": "维护者姓名", "email": "maintainer@example.com"} ], “idaVersions”：[“9.0”，“9.1”，“9.2”]， “平台”：[“windows-x86_64”，“linux-x86_64”，“macos-x86_64”，“macos-aarch64”]， “类别”：[“恶意软件分析”]， "keywords": ["分析", "自动化"], “pythonDependency”：[“请求> = 2.0”，“pydantic> = 2”]， "logoPath": "资产/logo.png", “设置”：[] } } ### 必填字段领域 |类型 |描述 ---|---|--- `IDAMetadataDescriptorVersion` | `1` |始终设置为“1” `插件名称` |字符串|唯一标识符。仅 ASCII 字母、数字、下划线、连字符。没有前导/尾随“_”或“-”。用于派生IDA命名空间：`__plugins__my_plugin` `插件版本` |字符串|语义版本“x.y.z”格式。没有前导“v” `plugin.entryPoint` |字符串|入口点文件名（例如“my_plugin.py”）或本机插件的裸名称 `plugin.urls.repository` |字符串| GitHub URL：`https://github.com/org/project` `plugin.authors` 或 `plugin.maintainers` |数组|至少需要一个“电子邮件”字段的联系人 ### 可选字段领域 |类型 |默认 |描述 ---|---|---|--- `插件.描述` |字符串|无 |搜索结果中显示的一行描述 `插件.许可证` |字符串|无 |许可证标识符（例如“MIT”、“Apache-2.0”、“GPL-3.0”） `plugin.urls.homepage` |字符串|无 |主页 URL（如果与存储库不同） `plugin.idaVersions` |数组或字符串 |所有版本 |支持的 IDA 版本。可以是显式列表 `["9.0", "9.1"]` 或规范 `">=7.4"` `plugin.platforms` |数组|所有平台 |支持的平台：`windows-x86_64`、`linux-x86_64`、`macos-x86_64`、`macos-aarch64` `插件.类别` |数组| `[]` |请参阅下面的类别部分 `plugin.keywords` |数组| `[]` |可发现性的搜索词 `plugin.pythonDependency` |数组或“内联”| `[]` | PyPI 包。对 PEP 723 元数据使用“内联” `plugin.logoPath` |字符串|无 |徽标图像的相对路径（建议使用 16:9 宽高比） `插件.设置` |数组| `[]` |插件配置选项。请参阅设置部分 ### 有效类别拆卸和处理器模块文件解析器和加载器反编译调试和跟踪反混淆协作与生产力与第三方集成互操作性 api 脚本编写和自动化 ui-ux-和可视化恶意软件分析漏洞研究与利用开发其他 ### 有效的 IDA 版本当前/支持：`9.2`、`9.1`、`9.0sp1`、`9.0`、... 使用像 `">=9.0"` 这样的版本说明符来自动匹配多个版本。 ## 打包纯Python插件对于简单的 Python 插件，目录结构非常简单：我的插件/ ├── ida-plugin.json ├── README.md # 在plugins.hex-rays.com上显示 ├── my_plugin.py # 入口点 └── my_plugin_lib/ # 可选支持模块 ├── __init__.py └── helpers.py ### 最小示例 { “IDA元数据描述符版本”：1， “插件”：{ “名称”：“我的简单插件”， “版本”：“1.0.0”， "entryPoint": "my_plugin.py", “网址”：{ “存储库”：“https://github.com/username/my-simple-plugin” }, “作者”：[ {"name": "您的名字", "email": "you@example.com"} ] } } ### 具有依赖关系 { “IDA元数据描述符版本”：1， “插件”：{ “名称”：“卡帕”， “版本”：“9.3.1”， "entryPoint": "capa_explorer.py", "description": "使用 FLARE 的 capa 框架识别可执行文件中的功能", “许可证”：“Apache-2.0”， "idaVersions": ">=7.4", “类别”：[“恶意软件分析”，“api脚本和自动化”，“ui-ux和可视化”]， "pythonDependency": ["flare-capa==9.3.1"], “网址”：{ “存储库”：“https://github.com/mandiant/capa” }, “作者”：[ {"姓名": "威利·巴伦辛", "电子邮件": "wballenthin@hex-rays.com"}, {“姓名”：“莫里茨·拉贝”，“电子邮件”：“moritzraabe@google.com”} ], "keywords": ["能力检测"、"恶意软件分析"、"att&ck"、"静态分析"] } } ### PEP 723 内联依赖项如果您的插件使用 PEP 723 内联脚本元数据，请将 `pythonDependency` 设置为 `"inline"`： { “pythonDependency”：“内联” } 然后在你的入口点 Python 文件中： # /// 脚本 # 依赖关系 = [ #“请求>=2.0”， #“pydantic>=2” #] # /// 导入ida_kernwin # ...插件的其余部分 ## 打包原生插件本机插件需要为每个目标平台编译二进制文件（.dll、.so、.dylib）。 ### 目录结构我的本机插件/ ├── ida-plugin.json ├── README.md # 在plugins.hex-rays.com上显示 ├── my_plugin.dll # Windows ├── my_plugin.so # Linux └── my_plugin.dylib # macOS（通用或特定于架构） ### 入口点约定对于本机插件，请使用不带扩展名的**裸名称**： { “插件”：{ “entryPoint”：“我的插件”， “平台”：[“windows-x86_64”，“linux-x86_64”，“macos-x86_64”，“macos-aarch64”] } } IDA 将自动为当前平台附加正确的扩展名（`.dll`、`.so`、`.dylib`）。 ### 胖二进制档案将所有平台二进制文件包含在一个存档中。入口点使用裸名称，并在安装时选择正确的二进制文件。 ### 特定于平台的档案或者，为每个平台创建具有显式扩展名的单独存档： **Windows 存档：** { “插件”：{ "entryPoint": "my_plugin.dll", “平台”：[“windows-x86_64”] } } **Linux 存档：** { “插件”：{ "entryPoint": "my_plugin.so", “平台”：[“linux-x86_64”] } } ## 插件设置对于需要用户配置的插件，请在清单中声明设置。用户通过“hcli 插件配置”或 IDA GUI 来配置这些。 ### 设置架构 { “设置”：[ { “密钥”：“api_key”， “名称”：“API密钥”， “类型”：“字符串”， “必需”：真实， "documentation": "您的服务的 API 密钥" }, { “关键”：“端点”， "name": "API 端点", “类型”：“字符串”， “必需”：假， “默认”：“https://api.example.com”， "validation_pattern": "^https://.*$" }, { “关键”：“日志级别”， "name": "日志级别", “类型”：“字符串”， “必需”：假， “选择”：[“调试”，“信息”，“警告”，“错误”]， “默认”：“信息” }, { “关键”：“启用遥测”， "name": "启用遥测", “类型”：“布尔值”， “必需”：假， “默认”：假 } ] } ### 设置字段领域 |类型 |必填|描述 ---|---|---|--- `关键` |字符串|是的 |代码级标识符（例如“api_key”） `名称` |字符串|是的 |人类可读的标签（例如“API Key”） `类型` | `"字符串"` 或 `"布尔值"` |是的 |值类型 `必需` |布尔 |是的 |用户是否必须提供值 `文档` |字符串|没有|用户的帮助文本 `默认` |字符串或布尔值 |没有|如果没有配置则默认值 `验证模式` |字符串|没有|用于验证字符串值的正则表达式 `选择` |字符串数组 |没有|允许的值（与“validation_pattern”互斥） ### 访问插件代码中的设置使用“ida-settings”库：从 ida_settings 导入 get_current_plugin_setting api_key = get_current_plugin_setting("api_key") log_level = get_current_plugin_setting("log_level") ## 验证发布前始终进行验证： # 验证目录 hcli 插件 lint /path/to/my-plugin # 验证 ZIP 存档 hcli 插件 lint /path/to/my-plugin.zip linter 检查： * JSON 语法和架构合规性 * 存在必填字段 * 入口点文件存在 * 徽标文件存在（如果已声明） * 平台/二进制一致性 * 路径安全（无遍历） ## 发布到存储库 ### 第 1 步：创建 GitHub 版本 1. 标记您的提交：`git tag v1.0.0 && git push --tags` 2. 从标签创建 GitHub Release 3. 附上您的插件存档 (ZIP) ### 第 2 步：自动索引索引器每天运行并自动发现： * 根目录中带有“ida-plugin.json”的存储库 * 具有有效插件档案的 GitHub 版本无需手动注册。您的插件会在 24 小时内出现。 ### 步骤 3：显式注册（可选）要加快索引速度，请将您的存储库添加到“known-repositories.txt”： 1. 分叉 [HexRaysSA/plugin-repository]() 2. 将您的存储库 URL 添加到 `known-repositories.txt`（每行一个） 3. 提交拉取请求 ### 索引故障排除检查[索引器日志报告]()是否有错误。常见问题： * 无效的 JSON 语法 * 缺少必填字段（尤其是作者电子邮件） * 存储库 URL 与 GitHub 模式不匹配 * 在存档中找不到入口点文件 ## 多插件档案一个存档可以包含多个插件，每个插件都位于自己的子目录中：多插件.zip ├── 插件-a/ │ ├── ida-plugin.json │ └──plugin_a.py └── 插件-b/ ├── ida-plugin.json └──plugin_b.py 每个子目录必须有自己的“ida-plugin.json”。 ## 版本更新发布新版本： 1.更新`ida-plugin.json`中的`plugin.version` 2.创建与版本匹配的新git标签 3. 使用新存档创建 GitHub 版本 4. 索引器将自动拾取新版本用户通过以下方式升级：`hcli 插件升级 ` ## 常见模式 ### 最小 Python 插件清单 1. 创建包含必填字段的“ida-plugin.json” 2.确保入口点文件存在 3. 通过电子邮件添加作者 4.运行`hcli插件lint` 5. 使用源存档创建 GitHub 版本 ### 将设置添加到现有插件 1. 在 `ida-plugin.json` 中定义设置数组 2. 如果使用该库，请将“ida-settings”添加到“pythonDependencies” 3.更新插件代码以使用`get_current_plugin_setting()` 4.README中的文档设置 ### 转换旧版插件 1. **评估目录结构** : 验证所有插件代码是独立的 * 入口点和一个目录中的所有导入 * 没有对父目录的“../”引用 * 数据文件和资产与代码位于同一位置 2. **如果需要的话重构**：将 `ida-plugin.json` 移动到插件代码所在的位置 3. 创建包含必填字段的“ida-plugin.json” 4.设置正确的`entryPoint`（相对于`ida-plugin.json`） 5.添加适当的`idaVersions`（测试兼容性！） 6. 从requirements.txt声明`pythonDependency` 7. 在插件根目录添加`README.md`用于网页显示 8. 本地验证和测试：`hcli plugin lint` 9. 创建 GitHub 版本 ## HCLI 命令参考 # 列出可用的插件 hcli 插件列表 # 搜索插件 hcli 插件搜索 # 安装插件 hcli 插件安装 <名称> hcli 插件安装 <名称>==1.0.0 # 升级一个插件 hcli 插件升级 <名称> # 卸载插件 hcli 插件卸载 <名称> # 列出已安装的插件 hcli插件列表--已安装 # 配置插件设置 hcli 插件配置 <名称> 设置 <键> <值> hcli 插件配置 <名称> 获取 <键> # 验证插件 hcli 插件 lint /path/to/plugin ## 资源 * **插件存储库** : [plugins.hex-rays.com]() * **文档**：[hcli.docs.hex-rays.com]() * **存储库来源**：[github.com/HexRaysSA/plugin-repository]() * **HCLI 来源**：[github.com/HexRaysSA/ida-hcli]() * **IDA 设置库** : [github.com/williballenthin/ida-settings]() * **支持**：[github.com/HexRaysSA/ida-hcli/issues]()

包 Ida 插件

包含技能