Ghidra MCP 函数文档化工作流V5详解：7步打造生产级逆向文档的完整流程

Ghidra MCP 函数文档化工作流V5详解7步打造生产级逆向文档的完整流程【免费下载链接】ghidra-mcpGhidra MCP Server — 200 MCP tools for AI-powered reverse engineering. GUI plugin headless server, lazy tool loading, convention enforcement, batch operations, Ghidra Server integration, and Docker deployment.项目地址: https://gitcode.com/gh_mirrors/ghi/ghidra-mcpGhidra MCP 是一个为 Ghidra 逆向工程引擎提供 200 个 MCP 工具的 AI 逆向工程服务器支持 GUI 插件与无头服务器两种运行模式。它的函数文档化工作流 V5Function Documentation Workflow V5是一套经过上千个真实函数打磨的 7 步流程能指导 AI 助手自动完成函数重命名、原型定义、匈牙利命名法类型标注、Plate Comment 文档编写并输出 0–100 的完整性评分是打造生产级逆向工程文档的标准方法。为什么选择 V5 工作流早期的 V1–V4 版本在实际使用中暴露出一系列问题AI 助手反复调用单个工具导致请求超时、变量类型改了名字却没改类型、注释写在重命名之前又被原型修改清空……V5 针对这些失败模式做了系统性修正严格顺序先完成命名/原型/类型变更最后才写注释set_function_prototype会清空已有 Plate Comment批量化用rename_variables单次字典调用和batch_set_comments一次写完 Plate PRE EOL 注释API 调用减少 93%类型审计检查变量的真实存储类型storage type而不是反编译器的显示类型内置匈牙利命名法参考无需在提示词里反复粘贴风格指南验证评分analyze_function_completeness给出可量化的 0–100 分数明确告诉你缺什么完整定义见 FUNCTION_DOC_WORKFLOW_V5.md。准备工作连接检查与提示词配置开始之前先确认 Ghidra 已启动、插件可访问调用check_connection工具验证连接连接被拒时立即停止不要派发生成文档的子任务在 Ghidra CodeBrowser 中通过Tools GhidraMCP Start MCP Server启动服务器将 FUNCTION_DOC_WORKFLOW_V5.md 的内容作为系统提示词交给 AI 助手如果你还没有环境可以克隆仓库后按 README 部署git clone https://gitcode.com/gh_mirrors/ghi/ghidra-mcp cd ghidra-mcp python -m tools.setup ensure-prereqs --ghidra-path /path/to/ghidra python -m tools.setup build python -m tools.setup deploy --ghidra-path /path/to/ghidra7 步文档化流程详解第 1 步初始化与分类调用analyze_for_documentation(函数名)一次性获取函数边界、返回类型推断、现有名称等关键信息并做三件事核实函数边界范围不对就用正确范围重建函数检查返回类型若return_type_resolved为 false逐个检查每条 RET 指令处的 EAX验证现有名称即使已有自定义名也要确认它是否准确描述函数行为 若函数是 thunk仅一条 CALL/JMP、无逻辑的转发桩走快速路径只执行第 2、5、6 步即可。第 2 步重命名函数 设置原型并行调用rename_function和set_function_prototype可以在同一轮并行调用节省一个来回命名规则PascalCase 动词开头如GetPlayerHealth、ProcessInputEvent、ValidateItemSlotSKILLS_GetLevel→GetSkillLevelprocessData→ProcessData原型规则用带类型的结构体指针UnitAny*而非int*参数使用匈牙利命名法调用约定cdecl/stdcall 等以反汇编为准不要信反编译器的猜测⚠️ 原型变更会触发重新反编译并产生新的 SSA 变量第 3 步必须重新拉取变量列表第 3 步类型审计这是 V5 最关键的一步——必须显式调用get_function_variables查看真实存储类型不能依赖analyze_for_documentation的显示信息。逐一遍历每个参数和局部变量发现处理类型含undefined按使用上下文调用set_variable_type修复名字带指针前缀p/pp/lpsz但类型是int必须改为指针类型__thiscall的void*this 指针识别类/结构体后通过set_function_prototype设置正确的 this 类型幻影变量extraout_*、in_*反编译器伪影记录到 Plate Comment 的 Special Cases不要反复重试裸指针 偏移访问*(ptr 0x10)用search_data_types找匹配结构体找不到就在对应指令加 EOL 注释说明偏移含义⚠️Type-first 铁律绝不把变量改名为匈牙利前缀名dw、n、p等却还保留undefined*类型。先set_variable_type再重命名无法确定类型时就用描述性名字questBits而非dwQuestBits。第 4 步批量重命名变量类型全部解析后用一次rename_variables调用覆盖所有变量再调一次get_function_variables确认没有残留的undefined存储类型。常用前缀速查完整表见 HUNGARIAN_NOTATION.md类型前缀示例uint / DWORDdwdwFlagsintnnIndex指针ppData字符串参数/局部lpsz/szlpszFileName结构体指针p名称pUnit全局变量g_g_dwCount第 5 步一次性写入全部注释这一步必须在所有命名/原型/类型变更之后执行。先用apply_data_typerename_symbol处理反编译代码中可见的DAT_*/s_*全局变量加g_前缀 匈牙利命名然后一次batch_set_comments调用同时写入三类注释Plate Comment函数头部总览纯文本、不加装饰边框Ghidra 自动添加格式。标准结构一句话概述 →Algorithm:编号步骤 →Parameters:寄存器传递的参数标注 IMPLICIT 寄存器名→Returns:覆盖所有返回路径→Special Cases:魔法数用十六进制十进制双写、边界情况PRE_COMMENT反编译视图放在块起始地址说明上下文与算法步骤约 60 字符以内EOL_COMMENT反汇编视图放在指令地址32 字符以内包含所有十六进制常量可直接参考 PLATE_COMMENT_EXAMPLES.md 中 6 个不同函数类型的完整实例。第 6 步完整性验证调用analyze_function_completeness一次评分。判断标准可修复扣分 10 分→ 修掉通常是未解释的魔法数、未定类型的变量、缺失的 Plate 分区再验证一轮直到通过不可修复扣分→ 接受即可幻影变量、API 强制的void*参数、标准 API 的lp/h前缀等⏱️ 设置 Plate Comment 后建议等待 1–2 秒再评分——Ghidra 事件系统是异步的立即查询可能读到过期数据详见 PLATE_COMMENT_BEST_PRACTICES.md评分达到 100 的要求Plate Comment 至少 10 行、包含Algorithm:/Parameters:/Returns:三个分区、算法步骤带编号。第 7 步动态交叉验证可选v5.4.0对语义模糊的叶子函数哈希算法、CRC/校验和、位打包例程在报告 DONE 前用动态手段交叉验证静态文档analyze_dataflow(address, variable..., directionbackward)—— 确认 Plate Comment 中声称的值来源就是反编译器看到的唯一来源emulate_function(address, registers{...}, memory{...})—— 喂入已知输入、读输出寄存器是证伪错误算法声明最便宜的方式注意分数衡量的是文档规范性文档存在且格式良好不是真实性——一个写得完美但错误的算法描述依然能得 100 分。因此遇到[AUDIT falsify:*]标记时修正文档使其与反汇编一致是最高优先级反汇编永远拥有最终解释权。批量模式并行子代理扩展产出单函数流程跑通后用 FUNCTION_DOC_WORKFLOW_V5_BATCH.md 的编排模式扩展到整个二进制目标选择按完整性评分升序70% 优先、按调用图拓扑排序叶子函数优先、或直接筛出所有FUN_*/Ordinal_*前缀的未文档化函数并发上限 3 个子代理MCP 工具在 Ghidra HTTP 层是串行化的超过 3 个只会增加超时而不会更快防重名派发前用search_functions_enhanced检查候选名冲突避免两个不同函数同名错误处理超时重试一次后跳过评分 50% 标记人工审查50–70% 且扣分均不可修复的接受为完成总结生产级逆向文档的三道防线防线工具保证顺序与批量化V5 工作流规则注释不被原型修改清空、请求不超时类型与命名规范类型审计 匈牙利命名法名字与类型永远一致p前缀必是真正的指针量化验证analyze_function_completeness 动态交叉检查每个函数有分数背书可追溯、可复查按这套流程AI 助手对每个函数的产出都遵循统一契约规范的 PascalCase 名称、类型正确的原型、覆盖全部返回路径的 Plate Comment以及一个可验证的完整性分数。这正是 V5 被称为生产级的原因——文档不再是个人风格的产物而是可审计的资产。延伸阅读主工作流定义docs/prompts/FUNCTION_DOC_WORKFLOW_V5.md批量编排docs/prompts/FUNCTION_DOC_WORKFLOW_V5_BATCH.md匈牙利命名法完整参考docs/HUNGARIAN_NOTATION.mdPlate Comment 撰写示例docs/prompts/PLATE_COMMENT_EXAMPLES.mdPlate Comment 最佳实践与缓存延迟docs/PLATE_COMMENT_BEST_PRACTICES.mdMCP 工具用法指南docs/prompts/TOOL_USAGE_GUIDE.md【免费下载链接】ghidra-mcpGhidra MCP Server — 200 MCP tools for AI-powered reverse engineering. GUI plugin headless server, lazy tool loading, convention enforcement, batch operations, Ghidra Server integration, and Docker deployment.项目地址: https://gitcode.com/gh_mirrors/ghi/ghidra-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考