使用 AiPy 构建开源项目白盒源码审计工作流

本文讨论如何基于 AiPy 构建面向开源项目的白盒源码审计工作流。

摘要

随着大语言模型在代码理解、代码生成和任务编排方面的能力提升，AI Agent 开始进入安全审计场景。然而，直接要求模型“审计一个项目并寻找漏洞”通常会得到不稳定的结果：模型容易忽略认证边界、重复分析已验证路径，或生成缺乏证据链的漏洞报告。

本文以 AiPy 为基础，介绍一套面向开源项目的白盒源码审计架构。该架构包含两条互补路径：其一是从零开始的常规白盒审计流程，由 whiteAudit 插件负责项目探索、候选点拆解、单点漏洞分析和报告复核；其二是历史漏洞学习驱动的定向审计流程，由 whiteAudit_study 插件负责学习 CVE、GHSA、security commit 和历史补丁模式，并将知识沉淀到 Serena project memory 中，再基于记忆开展同源或相似模式审计。

实践表明，将审计过程拆分为项目探索、历史漏洞学习、定向分析、利用路径去重和报告复核等阶段，可以显著降低模型上下文压力，提高报告一致性和可验证性。

引言

AiPy 是由知道创宇团队开发的开源 AI 智能体平台。与只聚焦代码补全的 AI 编程助手不同，AiPy 以 “Python-Use” 为核心理念：将 Python 运行环境和生态能力提供给大语言模型，使模型能够根据任务需要编写代码、调用库函数、操作文件系统、访问网络资源，并完成多步骤自动化任务。

在白盒源码审计场景中，这一范式具有天然优势。安全研究人员不只需要阅读代码，还需要完成仓库准备、依赖识别、危险函数定位、调用链追踪、补丁比对、报告编写和证据复核等大量重复工作。AiPy 可以承担其中可工程化的部分，使研究人员将精力集中在审计策略、漏洞价值判断和最终结论确认上。

本文关注的问题不是“AI 是否能够替代安全研究人员”，而是“如何把安全研究人员的工作方法转化为 AI 可执行的流程”。在这一前提下，AI 不被视为一次性给出结论的黑盒，而被视为能够调用工具、维护记忆、拆解任务、生成报告并接受复核的审计协作者。

问题定义

传统开源项目白盒审计通常有两类路径：

1. 使用静态分析或白盒扫描工具，对代码库进行规则化扫描。
2. 使用 IDE、调试器和代码检索工具，由人工进行结构分析、入口点识别和数据流追踪。

第一类方法适合快速发现已知模式，但面对复杂业务逻辑、认证边界和上下文相关漏洞时容易产生误报或漏报。第二类方法准确性更高，但高度依赖安全研究人员经验，在大型开源项目中成本较高。

AiPy 审计工作流采用第二类路径，即将“人工阅读代码并验证漏洞”的流程转化为多 Agent 协作流程。模型可以使用系统命令、代码检索工具和 Serena MCP 等能力阅读代码；主任务则负责维护待办事项、分配子任务、汇总结果和触发复核。

这一设计需要解决三个关键问题：

1. 上下文连续性：AI 默认缺少跨轮次记忆，重复审计时容易从头开始，无法继承已验证的结论。
2. 任务粒度控制：如果任务过大，模型容易忽略关键约束；如果任务过碎，主任务又会产生较高调度成本。
3. 报告可信度：模型可能生成形式完整但证据不足的报告，因此需要独立复核机制确认 Source、Sink、权限边界、触发路径和 PoC。

Serena project memory 为第一个问题提供了基础能力。它是项目级记忆，而不是全局记忆，适合记录某个仓库中已学习的漏洞模式、已分析过的利用路径和已证伪的候选点。

方法一：从零开始的白盒审计

常规审计流程适用于尚未明确历史漏洞线索的项目。该流程以项目探索为起点，先识别项目语言、框架、入口点、认证模型、敏感功能和已有记忆，再将候选审计目标拆解为独立分析任务。

graph TD
    A["用户输入项目地址"] --> B["AiPy 白盒审计主任务"]
    B --> C["克隆或更新目标项目"]
    C --> D["创建项目探索子任务"]
    D --> E["主任务整理候选审计目标"]
    E --> F["创建单目标漏洞分析子任务"]
    F --> G["输出草稿报告"]
    G --> H["报告复核子任务"]
    H --> I{"漏洞是否可信?"}
    I -->|"是"| J["生成可提交的漏洞报告"]
    I -->|"否"| K["记录证伪原因和已分析路径"]

该流程的目标不是让模型泛化地“扫描整个项目”，而是使模型先建立结构化理解，再对单个入口、单条数据流或单类危险操作进行深度分析。与一次性全仓库审计相比，单目标分析更容易保持上下文稳定，也更便于后续复核。

方法二：历史漏洞学习驱动审计

仅依赖从零开始的探索仍然存在效率问题。对于成熟开源项目，公开 CVE、GHSA、security commit、issue、PR 和 release note 往往包含高价值线索：它们揭示了项目过去在输入处理、权限模型、模板渲染、文件访问或网络请求等方面出现过何种缺陷。

因此，第二套流程将历史漏洞视为审计样本。模型先学习某个 CVE、补丁或漏洞模式，提炼根因、补丁特征、Source/Sink、触发条件和相似代码搜索策略，再将结果写入 Serena project memory。随后，定向审计子任务读取该 memory，在当前源码中寻找同类风险。

优先关注的历史线索包括：

• CVE、GHSA、NVD、官方公告和漏洞分析文章。
• 包含安全语义的 commit、PR、release note 和 advisory。
• commit message 中出现 security、vulnerability、CVE、GHSA、sanitize、validate、auth、permission、escape、RCE、SSRF、SQL injection 等关键词的变更。

历史漏洞学习流程采用串行流水线，而不是让学习任务和审计任务并行运行。原因在于，并行方式可能使审计子任务读取到尚未抽象完成的半成品记忆，导致报告质量不稳定。串行流程则保证每轮输入、输出和复核边界清晰。

flowchart TD
    A["主 AiPy"] --> B["选择 CVE / GHSA / security commit / issue / 漏洞模式"]
    B --> C["创建历史漏洞学习子任务"]
    C --> D["检索公告、issue、release note 和 security commit"]
    D --> E["提炼根因、补丁特征、Source/Sink 和搜索策略"]
    E --> F["写入 Serena project memory"]
    F --> G["创建基于 memory 的定向审计子任务"]
    G --> H["审计当前源码中的相似模式"]
    H --> I{"发现可信漏洞?"}
    I -->|"是"| J["写入 aipy_report/drafts/"]
    I -->|"否"| K["记录证伪原因"]
    J --> L["创建报告复核子任务"]
    L --> M{"复核通过?"}
    M -->|"是"| N["移动到 aipy_report/verified/"]
    M -->|"否"| O["移动到 aipy_report/rejected/"]
    K --> P["更新已分析利用路径 memory"]
    N --> P
    O --> P

whiteAudit 智能体设计

whiteAudit 是常规白盒审计流程的实现。它不是传统扫描器，而是一个角色化子任务通道，用于将白盒审计拆分为项目探索、单目标分析和报告复核等阶段。

AiPy 智能体本质上可以通过 MCP 服务器向主任务注入提示词和工具。例如，插件可以通过 addition-system-instruction 提示词为主任务提供审计流程约束；也可以通过工具封装子任务创建、结果等待和报告目录管理逻辑。

whiteAudit 提供的主要工具包括：

• create_explorer_subtask：在漏洞分析前执行项目探索，识别语言、框架、入口点、认证模型、敏感功能和已有 memory。
• create_analyzer_subtask：创建单目标漏洞分析子任务，只分析主任务指定的入口、文件、函数或数据流。
• create_report_reviewer_subtask：创建报告复核子任务，验证漏洞链路、证据引用、认证边界和 PoC 是否成立。
• create_audit_subtask：高级兼容接口，允许调用方自定义完整 instruction、skills、model 等参数。

远程仓库会被克隆到共享工作区：

audit_workspace/repos/<repo_name>_<hash>/src

如果稳定工作区已经存在，插件会先执行 git fetch --prune origin，再执行 git merge --ff-only <upstream>。这一策略尽量保证审计基于最新代码。如果本地分支发散、存在冲突、网络失败或 upstream 不可用，插件会阻断审计并要求用户处理工作区状态，避免在不确定代码版本上继续分析。

flowchart TD
    A["用户输入 Git URL 或本地路径"] --> B["whiteAudit 解析目标"]
    B --> C{"目标是 Git 仓库?"}
    C -->|"否"| D["校验本地路径"]
    C -->|"是"| E{"稳定工作区已存在?"}
    E -->|"否"| F["git clone --depth 1"]
    E -->|"是"| G["git fetch --prune origin"]
    G --> H["git merge --ff-only upstream"]
    F --> I["准备 aipy_report 目录"]
    H --> I
    D --> I
    I --> J["创建角色化 AiPy 子任务"]
    J --> K["等待子任务结束"]
    K --> L["主任务根据结果决定下一步"]

子任务调用采用同步等待模式。AiPy 子任务本身异步运行，但主任务不需要持续轮询中间输出；插件会等待子任务进入结束态后，将最终结果一次性返回给主任务。返回值中的 task_id 用于审计追踪和异常恢复，而不是用于主任务循环轮询。

whiteAudit_study 智能体设计

whiteAudit_study 是历史漏洞学习驱动审计流程的实现。它与 whiteAudit 共享工作区、报告目录和利用路径去重机制，但角色定位更偏向安全知识提炼与定向审计。

该插件提供四个主要工具：

• create_cve_study_subtask：学习历史漏洞知识点，可以是 CVE、GHSA、commit、issue、漏洞名称或自然语言漏洞模式。
• create_memory_audit_subtask：读取指定 Serena memory，根据学习到的根因和补丁特征审计当前项目。
• create_report_reviewer_subtask：复核草稿报告，判断证据是否充分、链路是否完整、结论是否来自历史漏洞学习记忆的有效类推。
• create_study_subtask：高级兼容接口。

其插件级工作流如下：

flowchart TD
    A["用户输入 Git URL 或本地路径"] --> B["whiteAudit_study 解析目标"]
    B --> C{"目标是 Git 仓库?"}
    C -->|"否"| D["校验本地路径"]
    C -->|"是"| E{"稳定工作区已存在?"}
    E -->|"否"| F["git clone --depth 1"]
    E -->|"是"| G["git fetch --prune origin"]
    G --> H["git merge --ff-only upstream"]
    F --> I["准备 aipy_report 目录"]
    H --> I
    D --> I
    I --> J["创建历史漏洞学习子任务"]
    J --> K{"是否学习到新的知识点?"}
    K -->|"是"| L["写入 Serena project memory"]
    L --> J
    K -->|"否"| M
    M["创建基于 memory 的定向审计子任务"]
    M --> N["输出草稿报告或证伪结论"]
    N --> O["创建报告复核子任务"]
    O --> P{"复核是否通过?"}
    P -->|"是"| Q["移动到 aipy_report/verified/"]
    P -->|"否"| R["移动到 aipy_report/rejected/ 并追加原因"]
    Q --> S["更新利用路径 memory"]
    R --> S

whiteAudit_study 的关键价值在于将“历史漏洞经验”从一次性上下文转化为项目级记忆。每个学习子任务都需要输出可复用知识，而不是仅给出自然语言总结。

Serena memory 的作用

Serena memory 在该架构中承担两类职责。

第一类是学习记忆。例如：

whiteaudit-study/<slug>

这类 memory 记录某个 CVE、GHSA、security commit 或漏洞模式的学习结果，至少包含：

• 受影响组件。
• Source/Sink。
• 认证和鉴权边界。
• 触发条件。
• 补丁特征。
• 修复前后的差异。
• 相似代码搜索策略。
• 当前项目中值得优先审计的薄弱点。

第二类是已分析利用路径记忆：

whiteaudit/exploit-paths

这是去重机制的核心。仅检查 aipy_report/verified/ 目录不足以避免重复报告，因为同一条利用路径可能在不同阶段被写成草稿、被驳回或被证伪。更稳妥的方式是记录“已经验证过的利用路径”，而不是只记录“已经生成过的报告”。

一条利用路径指纹至少包含：

• 漏洞类型和 CWE。
• 入口、路由或 API。
• Source 参数。
• Sink 或危险操作。
• 涉及文件和函数。
• 认证、鉴权和权限边界。
• 过滤或绕过条件。
• 根因摘要。
• 利用原语。
• 验证结论。
• 报告路径或证伪原因。

判断重复时，不以报告标题、CVSS、文件名或 CVE 编号为准，而以 Source 到 Sink 路径、根因、权限边界和利用原语是否等价为准。

flowchart TD
    A["发现候选利用点"] --> B["抽取利用路径指纹"]
    B --> C["读取 Serena memory: whiteaudit/exploit-paths"]
    C --> D{"是否存在等价路径?"}
    D -->|"是"| E["标记 duplicate，不写新报告"]
    D -->|"否"| F["继续验证可利用性"]
    F --> G{"验证成功?"}
    G -->|"是"| H["写入 drafts/ 并记录 draft 指纹"]
    G -->|"否"| I["记录 not_exploitable 和证伪原因"]
    H --> J["报告复核"]
    J --> K{"复核通过?"}
    K -->|"是"| L["更新 memory 为 verified"]
    K -->|"否"| M["更新 memory 为 rejected"]

报告规范与复核机制

为了避免模型输出缺乏证据链的概括性文本，插件提示词对报告格式进行了硬约束。

第一，一个漏洞对应一个报告文件。多个独立漏洞必须拆分为多个 Markdown 文件，不能合并到同一份报告中。主任务可以输出总结，但落盘报告必须保持一漏洞一文件。

第二，每份漏洞报告必须包含以下章节：

• 简介。
• 涉及的文件。
• 漏洞 CWE。
• CVSS。
• 触发路径。
• PoC。
• 漏洞影响。
• 修复建议。
• 证据引用。
• 利用路径指纹。

如果报告来自 whiteAudit_study，还必须包含“历史漏洞启发”章节，用于说明该漏洞候选点与学习 memory 之间的关联。

报告复核子任务需要回到源码中确认文件路径、行号、Source、Sink、认证/鉴权、过滤/绕过和 PoC 是否成立。如果证据不足、不可利用、多个漏洞混写，或与已验证路径重复，报告应进入 aipy_report/rejected/，并追加明确的驳回原因。

实践目录结构

一次审计任务完成后，目标项目中会出现如下目录：

aipy_report/
├── studies/
├── drafts/
├── verified/
└── rejected/

各目录含义如下：

• studies/ 保存历史漏洞学习笔记，仅 whiteAudit_study 必须使用。
• drafts/ 保存分析子任务生成的草稿报告。
• verified/ 保存复核通过的漏洞报告。
• rejected/ 保存被驳回的报告，并在报告末尾追加驳回原因。

Serena memory 用于保存项目级记忆。对于利用路径去重，约定固定 memory 名称为：

whiteaudit/exploit-paths

整体架构

最终，whiteAudit 和 whiteAudit_study 形成互补关系。

whiteAudit 适合从零开始进行常规白盒审计：

flowchart LR
    A["项目探索"] --> B["建立 Todolist"]
    B --> C["单目标漏洞分析"]
    C --> D["草稿报告"]
    D --> E["报告复核"]
    E --> F["verified / rejected"]

whiteAudit_study 适合围绕历史漏洞和 security commit 进行定向审计：

flowchart LR
    A["学习 CVE / commit"] --> B["写入学习 memory"]
    B --> C["读取 memory 定向审计"]
    C --> D["利用路径去重"]
    D --> E["草稿报告"]
    E --> F["报告复核"]

两者共享以下基础设施：

• 统一工作区 audit_workspace/。
• 统一报告目录 aipy_report/。
• 统一利用路径去重 memory whiteaudit/exploit-paths。
• 同步等待子任务结束的调用方式。
• Git 仓库存在时先 fetch/merge 的代码更新策略。

讨论

AI 白盒审计的关键挑战不是模型能否阅读代码，而是能否在长任务中保持目标稳定、证据完整和结论可复核。直接把大型项目交给模型进行自由分析，容易出现三个问题：上下文被无关信息稀释、候选点缺少系统性优先级、报告中混入未验证结论。

本文提出的流程通过多阶段拆解缓解上述问题。项目探索阶段负责建立全局认知；单目标分析阶段负责深挖具体路径；历史漏洞学习阶段负责将外部安全知识转化为可执行搜索策略；Serena memory 负责保存已学习知识和已分析路径；报告复核阶段负责剔除证据不足或重复的结果。

从工程角度看，这一模式的价值在于将安全研究经验显式化。提示词、工具、memory、目录约定和报告规范共同构成了一套可重复执行的审计协议。模型能力越强，该协议的执行质量越高；但即使模型能力有限，流程本身也能通过任务拆分、去重和复核降低错误累积。

结论

使用 AiPy 进行开源项目白盒审计，重点不在于让大模型一次性读完整个项目并直接给出漏洞结论，而在于构建一套可执行、可沉淀、可复核的审计工作流。

whiteAudit 将常规白盒审计拆解为项目探索、目标分析和报告复核；whiteAudit_study 将历史漏洞、补丁模式和安全 commit 转化为项目级记忆，再基于 memory 进行定向审计。二者结合后，AiPy 不再只是对代码进行自然语言解释的工具，而成为能够维护审计状态、继承历史知识、减少重复路径并输出结构化报告的安全分析协作者。

这一方法并不消除人工判断的必要性。相反，它将人工判断前置到流程设计和结果复核中，把重复的代码定位、模式搜索、路径追踪和报告整理交给 AI 执行。对于开源项目安全研究而言，这是一种更稳健、可扩展的 AI Agent 应用方式。