前言¶

提 PR 之前，很多人会让 AI「帮忙看一眼代码」。常见结果有两种：一种是只挑空格和命名，真正的注入、越权和竞态被略过；另一种是按关键词乱报一通，把框架已经防住的写法也标成漏洞。缺的不是「再审一遍」这句话，而是一套固定流程：先拿到完整 diff，再画攻击面，再按清单逐项核对，最后还要证明问题确实存在。

find-bugs 就是把这套流程写进 Agent Skill 的产物。它来自 Sentry 工程团队维护的公开仓库 getsentry/skills，官方说明见 skills/find-bugs/SKILL.md。仓库 README 写明：这是 Sentry 员工日常开发使用的 Agent Skills 集合，遵循 Agent Skills 开放格式，许可证为 Apache-2.0。

这是什么¶

一句话定位：针对当前本地分支相对默认分支的变更，按五阶段流程查找 bug、安全漏洞和代码质量问题，只出报告、不改代码。

官方 frontmatter 如下：

• name：find-bugs
• description：在本地分支变更中查找 bug、安全漏洞和代码质量问题；在被要求 review changes、find bugs、security review，或审计当前分支代码时使用

目录里目前只有这一份 SKILL.md，没有附带脚本或 references/。它不是静态分析器，也不会调用 Sentry 的产品 API；真正干活的是读了这份清单的 AI Agent，配合 git 和 GitHub CLI（gh）拿到完整 diff。

同仓库里还有职责相近、但范围不同的 Skill，不宜混用：

• code-review：按 Sentry 工程实践做 PR 审查（运行时错误、性能、测试、设计）
• security-review：安全专项审查，只报告高置信、可利用的漏洞，并带有独立的语言/基础设施参考文档

find-bugs 的边界更窄：只看本分支相对默认分支的改动，安全、缺陷、质量一起过，但明确跳过纯风格和格式问题。

核心功能与亮点¶

根据官方 SKILL.md，工作流固定为五个阶段。

阶段 1：完整收集输入¶

Agent 必须先拿到完整 diff，而不是摘要：

git diff $(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')...HEAD

这条命令用 gh repo view 查出仓库默认分支（main / master 等），再对「默认分支…当前 HEAD」做三点 diff（即相对合并基线的本分支变更）。官方还要求：

1. 若输出被截断，就逐个打开改动文件，直到每一行改动都读过
2. 进入下一阶段前，先列出本分支修改过的全部文件

也就是说，不允许「扫了几个文件就开始下结论」。

阶段 2：攻击面映射¶

对每个改动文件，先列出这些点，而不是直接猜漏洞：

• 所有用户输入（请求参数、Header、Body、URL 组成部分）
• 所有数据库查询
• 所有认证 / 授权检查
• 所有会话 / 状态操作
• 所有外部调用
• 所有密码学操作

这一步的作用是把 diff 翻译成「攻击者能碰到什么」，后面的清单才有落点。

阶段 3：安全清单（每个文件、每一项都要过）¶

官方清单共 11 项，要求对每个文件逐项勾选：

• Injection：SQL、命令、模板、Header 注入
• XSS：模板里的输出是否正确转义
• Authentication：受保护操作是否都做了认证
• Authorization / IDOR：是否验证了访问控制，而不只是「已登录」
• CSRF：改状态的操作是否有防护
• Race conditions：读后写路径上是否有 TOCTOU
• Session：固定会话、过期、Secure 等标志
• Cryptography：安全随机数、算法是否合适、密钥是否进日志
• Information disclosure：错误信息、日志、时序侧信道
• DoS：无界操作、缺限流、资源耗尽
• Business logic：边界情况、状态机被破坏、数值溢出

这不是「想到什么查什么」，而是一张必须走完的检查表。

阶段 4：核实¶

对每一个可疑点，官方要求再确认三件事：

• 问题是否已在本次改动的其他位置处理过
• 是否已有测试覆盖该场景
• 读周围上下文，确认问题是真的

目的是压假阳性：看到 execute 或字符串拼接，不等于可以立刻报注入。

阶段 5：收口前审计¶

给出最终结论之前，必须先做：

1. 列出审查过的每个文件，并确认读完
2. 列出清单每一项：是发现了问题，还是确认干净
3. 列出未能充分核实的区域及原因
4. 然后才给最终发现

输出格式¶

优先级固定为：安全漏洞 > bug > 代码质量。风格和格式问题直接跳过。

每条问题按下面字段写：

• File:Line：简要描述
• Severity：Critical / High / Medium / Low
• Problem：错在哪里
• Evidence：为什么这是真问题（例如：没有在别处修掉、没有现成测试）
• Fix：具体改法建议
• References：适用时引用 OWASP、RFC 等标准

官方还有两条硬约束：

• 没有明显问题就直说，不要编造
• 不要改代码，只报告；由使用者决定修哪些

安装与启用¶

该 Skill 收录在 getsentry/skills 仓库，作为 sentry-skills 插件的一部分对外提供。安装方式以官方 README 为准。

Claude Code（官方插件市场）¶

claude plugin marketplace add getsentry/skills
claude plugin install sentry-skills@sentry-skills

装完后重启 Claude Code。官方说明：相关场景下 Skill 会自动启用。更新可以用：

claude plugin marketplace update
claude plugin update sentry-skills@sentry-skills

或在对话里运行 /plugin 打开插件管理。若用 claude plugin marketplace add --sparse 添加该仓库，需要把 skills、agents 和 .claude-plugin 一并包含，因为根目录的插件清单会加载仓库顶层的 skills/ 与 agents/。

skills.sh（Cursor / Claude Code / Copilot 等）¶

官方 README 同时提供 skills.sh 安装方式，并写明适用于 Claude Code、Cursor、Cline、GitHub Copilot 及其他兼容 Agent：

npx skills add getsentry/skills

若只装这一个 Skill，skills.sh 上的命令是：

npx skills add https://github.com/getsentry/skills --skill find-bugs

手动放到各工具的 Skill 目录¶

SKILL.md 是通用 Agent Skills 格式。按 Cursor 文档，项目级会从 .agents/skills/、.cursor/skills/ 自动发现；用户级对应 ~/.agents/skills/、~/.cursor/skills/。兼容目录还包括 .claude/skills/、.codex/skills/ 以及对应的用户级路径。手动放置时目录应类似：

.cursor/skills/find-bugs/SKILL.md

或：

.agents/skills/find-bugs/SKILL.md

Claude Code 项目级为 .claude/skills/find-bugs/SKILL.md，用户级为 ~/.claude/skills/find-bugs/SKILL.md。Codex CLI 则扫描 $CODEX_HOME/skills（默认 ~/.codex/skills）以及项目内的 .codex/skills/。

启用后，在 Agent 对话里输入 /，搜索 find-bugs 即可手动调用。官方 description 里带有 review changes、find bugs、security review、audit code 等触发词，描述匹配时 Agent 也可能自动选用。

典型用法示例¶

前置条件¶

按官方命令，运行环境需要：

• 当前目录是 Git 仓库，并且已经在一条功能分支上（相对默认分支有提交或未提交的可比对变更）
• 已安装并登录 GitHub CLI（gh），因为默认分支名是靠 gh repo view 查的
• 远程是 GitHub 上的仓库；gh repo view 对非 GitHub 远程会失败，这时需要自己给出默认分支，再让 Agent 用 git diff <default>...HEAD 补齐——这是环境限制，不是 Skill 正文里的替代流程

唤起方式¶

官方没有单独给「示例提示词」，但 description 已经写清触发场景。在已安装 Skill 的对话里，可以直接说（或先 /find-bugs 再补充）：

请按 find-bugs 审查当前分支相对默认分支的全部改动：
先拿到完整 diff，列出所有改动文件，做攻击面映射，
再按安全清单逐项检查，最后只输出带证据的问题报告，不要改代码。

也可以把范围说得更具体，例如「只看这次 API 鉴权相关的 diff」——Agent 仍应按五阶段走完，而不是跳过收集 diff 直接下结论。

报告长什么样¶

官方要求的条目形态可以理解成下面这样（路径和行号必须来自当次 diff，不能照抄）：

**app/api/orders.py:142** - 按对象 ID 取订单时未校验归属
- **Severity**: High
- **Problem**: 已登录用户传入任意 `order_id` 即可读到他人订单（IDOR）
- **Evidence**: 本分支新增该查询；同文件及中间件未见对象级授权；无对应测试
- **Fix**: 查询时加上当前用户（或租户）约束，例如 `order.user_id == request.user.id`
- **References**: OWASP A01:2021 Broken Access Control

如果五阶段走完没有值得上报的问题，按原文应明确说「没有发现显著问题」，而不是为了交差编几条风格意见。

适用场景与注意事项¶

适合

• 功能分支即将开 PR，希望先做一轮「安全优先」的本地审查
• 改动涉及用户输入、鉴权、会话、外部调用或密码学，需要按清单过一遍，而不是只看业务逻辑
• 团队已经用 Cursor / Claude Code / Codex 等支持 Agent Skills 的工具，希望审查步骤可重复、可共享

使用时要注意

1. 依赖 gh 和 GitHub 远程。 官方取 diff 的命令写死了 gh repo view。没装 gh、未登录、或仓库不在 GitHub 上时，这条命令会失败；需要先解决环境，或明确告诉 Agent 默认分支名称。
2. 范围是「本分支相对默认分支」，不是整个仓库。 它不会替代全量安全审计，也扫不到你没改、但被这次改动间接触达的旧代码——阶段 4 只要求读周围上下文做核实，并不是全库扫描。
3. 只报告、不修改。 原文最后一句是：不要改代码，由你决定修哪些。若需要顺手修，应另开一轮对话或改用别的工作流，避免和这份 Skill 的职责冲突。
4. 质量不等于风格。 官方明确跳过 stylistic / formatting。想查命名和空格，不该用它。
5. 假阳性仍可能出现，但流程在压它。 阶段 4 要求核对「是否已处理、是否有测试、上下文是否坐实」。即便如此，Agent 仍可能误判框架默认防护（例如模板自动转义、ORM 参数化）。同仓库的 security-review 在这一点上更严：只报高置信、攻击者可控输入已确认的问题。需要更强安全专项时，可以在 find-bugs 之后再跑 security-review。
6. 没有测试套件或评测集。 当前目录只有 SKILL.md。效果取决于模型是否严格执行五阶段，尤其是「diff 被截断时必须读完每个文件」和「收口前必须列出清单覆盖情况」。

小结¶

find-bugs 把 Sentry 团队自己在用的「分支级审查」写成一份可移植的 Skill：完整 diff → 攻击面 → 11 项安全清单 → 核实 → 收口审计，再按「安全 > 缺陷 > 质量」输出带证据的报告。它不替代专业渗透测试，也不自动改代码，但能把「让 AI 随便看看」收成一条可重复执行的预提交扫描。

官方地址：
https://github.com/getsentry/skills/tree/main/skills/find-bugs