前言¶
很多安全问题不是某一行实现写错，而是接口把「省事的路径」设成了不安全的路径：可选弱算法、默认值能关掉校验、verify 返回布尔却被忽略。常规代码审查容易盯着逻辑漏洞，却较少系统地问「timeout=0 会怎样」「空 key 会不会直接通过」。
下面介绍 Trail of Bits 维护的 Agent Skill sharp-edges。它面向 API、配置与库接口的误用抗性评估，把「成功坑」（pit of success）当作核心标准：安全用法应当是阻力最小的默认路径，而不是文档里的一句警告。
这是什么¶
sharp-edges 是 Trail of Bits skills 仓库 中的 Agent Skill，用一句话概括：识别容易让开发者踩坑的 API 设计、危险配置与 footgun 接口。
Skill 元数据中的触发场景包括：footgun、misuse-resistant、secure defaults、API usability、dangerous configuration；适用对象包括 API 设计评审、配置 schema 审计、密码学库 ergonomics，以及是否遵循 secure by default / pit of success 的判断。
与「查实现 bug」的审查不同，官方明确将其定位为设计层分析：实现缺陷、业务逻辑缺陷、性能优化分别应走其他路径，不宜用本 Skill 替代。
在 Trail of Bits 的安全 Skill 系列里，它偏少见的价值是设计审查视角——对写公开 API、配置 schema 或封装密码学能力的作者，比堆 checklist 更有结构性启发。
核心功能¶
核心原则¶
Pit of success：安全用法应是阻力最小的路径。若开发者必须精通密码学、细读文档或记住特殊规则才能避免漏洞，API 在设计上已失败。
六类 Sharp Edge¶
官方 SKILL 将常见 footgun 归纳为六类（下列能力与示例均来自官方文档）：
-
算法 / 模式选择 footgun
允许调用方自选algorithm、cipher、hash_type等，易选弱算法或遭遇算法混淆（如 JWT 中alg: none、RS256/HS256 混用）。检测点包括枚举/字符串选原语、安全配置项等。 -
危险默认值
默认不安全，或0/空串/null语义不清从而禁用安全能力。典型探针：timeout=0、max_attempts=0、key=""时行为是什么；默认是否是最安全选项。 -
原语 API vs 语义化 API
用裸bytes/string承载密钥、nonce、密文等不同概念，参数可互换且无类型错误；对比 Libsodium 式原语与 Halite 式带类型封装。另含「看起来一样、安全属性不同」的比较（如 Go 中普通==与hmac.Equal）。 -
配置悬崖
单一错误配置即可灾难性失效且无警告：布尔开关关掉全部安全、未校验的字符串配置、危险组合被静默接受、环境变量覆盖安全项、构造函数有安全默认但仍接受不安全入参等。 -
静默失败
安全失败不抛出、返回True掩盖错误、解析失败用默认值、验证函数对畸形输入仍「成功」；布尔返回值易被忽略等。 -
字符串化的安全语义
权限、角色、URL、SQL 等用拼接字符串表达，易注入或权限累加误操作；对比枚举/类型安全集合。
应拒绝的「合理化」¶
官方表格列出常见推诿及应对方向，例如「文档里写了」→ 应让安全选择成为默认或唯一选项；「高级用户需要灵活」→ 提供安全的高层 API、隐藏原语；「只是配置项」→ 校验并拒绝危险组合等。写作审查报告时可对照，避免把 footgun 留给出错率最高的路径。
分析工作流与专用 Agent¶
完整流程分四阶段：Surface Identification（映射安全相关 API 与开发者选择点）、Edge Case Probing（对每个选择点做边界探针）、Threat Modeling、Validate Findings。
需要独立、端到端跑一遍时，可使用 sharp-edges-analyzer agent；它会按上述四阶段自主执行，并按需读取语言相关 reference。
Skill 声明的可用工具为：Read、Grep、Glob（在仓库内读代码与配置，而非替代动态渗透测试）。
安装与启用¶
officialskills.sh 上的安装说明 给出的命令如下。将 Skill 从 Trail of Bits monorepo 中按名称 sharp-edges 添加：
npx skills add https://github.com/trailofbits/skills --skill sharp-edges
也可向编码助手提供仓库链接，请求安装对应 Skill：
https://github.com/trailofbits/skills/tree/main/plugins/sharp-edges
具体在 Cursor、Codex CLI、Claude Code 中的菜单或配置文件差异，当前公开资料未逐项列出；以你使用的客户端对「Agent Skills / npx skills」的文档为准。
典型用法¶
官方 When to Use 与 skills.sh 页面归纳了可复现的触发方式（用自然语言描述任务即可，无需固定咒语）：
- 审查密码学库的 API，是否存在算法选择 footgun（如接受
none、md5）。 - 评审构造函数：虽有安全默认值，是否仍接受不安全实参（如
otpLifetime=0、hashAlgo=md5）。 - 审计配置 schema：
0/null/ 负值是否静默关闭安全能力。 - 评估 JWT 或会话 token API 是否把算法等安全决策暴露给不可信输入。
- 识别调用点上难以区分的时间安全比较与不安全比较。
需要系统化报告时，可明确要求启用 sharp-edges-analyzer，按四阶段工作流输出发现，并对照六类分类与「Rationalizations to Reject」表验证结论是否可落地（默认改安全、校验危险组合、类型化语义等）。
示例探针思路（来自官方 Edge Case Probing）：对每个选择点追问边界值语义，与资料中的 OTP lifetime=0、空 key 跳过验签等模式一致。
适用场景与注意¶
适合：
- API 或库的设计评审、配置 schema 审计。
- 认证/授权接口、会话管理、输入校验边界的 ergonomics 评估。
- 判断新接口是否默认走在「容易误用就不安全」的路径上。
不适合（官方 When NOT to Use）：
- 实现层 bug（用常规范码审查）。
- 业务逻辑缺陷（用领域分析）。
- 性能优化（另一类关切）。
注意： 本 Skill 是结构化误用与 footgun 分析，不替代威胁建模工具链的全部环节，也不保证覆盖所有语言运行时细节；深度模式可参考仓库内 references/（如 config-patterns.md），由 agent 按需加载。
结尾¶
若你的工作包含对外暴露安全相关选择（算法、超时、开关、密钥形态），sharp-edges 把「默认是否最安全、边界值是否关安全、易路径是否等于不安全路径」变成可重复的检查清单，并配有 sharp-edges-analyzer 与四阶段工作流。官方 Skill 与源码路径：
https://github.com/trailofbits/skills/tree/main/plugins/sharp-edges/skills/sharp-edges
