审查 API/库设计、配置模式、密码学库人体工学…

在审查 API、配置、密码学或认证授权接口时，用于发现 footgun、危险默认值和易误用设计。

适用场景

解决思路

1. 使用 Read、Grep、Glob 工具读取和搜索代码、配置与参考文件。
2. 使用 `sharp-edges-analyzer` agent 自主运行完整的 sharp edges 分析工作流；它按四阶段工作流（Surface Identification、Edge Case Probing、Threat Modeling、Validate Findings）执行，并按需读取语言特定参考。
3. 贯彻“pit of success”原则：安全用法应是阻力最小路径；如果开发者必须理解密码学、仔细阅读文档或记住特殊规则才能避免漏洞，就判定 API 失败。
4. 拒绝合理化“It's documented”：开发者不会在截止压力下读文档；要求把安全选择设为默认或唯一选项。
5. 拒绝合理化“Advanced users need flexibility”：灵活性制造 footgun，大多数“高级”用法是复制粘贴；要求提供安全的高层 API，隐藏原语。
6. 拒绝合理化“It's the developer's responsibility”：这是责任转移，是你设计了 footgun；要求移除 footgun 或使其无法被误用。
7. 拒绝合理化“Nobody would actually do that”：开发者会在压力下做出一切想象得到的操作；假设最大程度的开发者困惑。
8. 拒绝合理化“It's just a configuration option”：配置即代码，错误配置会进入生产；要求验证配置并拒绝危险组合。
9. 拒绝合理化“We need backwards compatibility”：不安全默认不能 grandfather-claused；要求大声弃用并强制迁移。
10. 检查算法/模式选择 footgun：API 让开发者选择算法会诱导选错。
11. 检测算法/模式选择 footgun：函数参数如 `algorithm`、`mode`、`cipher`、`hash_type`。
12. 检测算法/模式选择 footgun：选择密码学原语的枚举/字符串。
13. 检测算法/模式选择 footgun：安全机制的配置选项。
14. 检查 JWT 模式：header 指定算法，攻击者可设 `"alg": "none"` 绕过签名。
15. 检查 JWT 模式：算法混淆，RS256→HS256 时 RSA 公钥被用作 HMAC 密钥。
16. 识别算法/模式选择 footgun 根因：让不可信输入控制安全关键决策。
17. 检查 PHP 例子：`password_hash($password, PASSWORD_DEFAULT)` 好——无选择；`hash($algorithm, $password)` 坏——接受 `crc32`、`md5`、`sha1` 等弱算法。
18. 检查危险默认值：不安全默认，或禁用安全的零/空值。
19. 检查 OTP 生命周期模式：`def verify_otp(code, lifetime=300): if lifetime == 0: return True`；质疑 0 是“接受所有”还是“立即过期”。
20. 检测危险默认值：接受 0 的超时/生命周期（无限？立即过期？）。
21. 检测危险默认值：绕过检查的空字符串。
22. 检测危险默认值：跳过验证的 null 值。
23. 检测危险默认值：禁用安全功能的布尔默认值。
24. 检测危险默认值：语义未定义的负值。
25. 询问危险默认值问题：`timeout=0`？`max_attempts=0`？`key=""`？会怎样。
26. 询问危险默认值问题：默认是否最安全选项？
27. 询问危险默认值问题：任何默认值能否完全禁用安全？
28. 检查原语 vs 语义 API：暴露原始字节而非有意义类型会引发类型混淆。
29. 检查 Libsodium vs Halite 模式：`sodium_crypto_box($message, $nonce, $keypair)` 容易交换 nonce/keypair、复用 nonce、用错密钥类型。
30. 检查 Libsodium vs Halite 模式：`Crypto::seal($message, new EncryptionPublicKey($key))` 用错密钥类型是类型错误而非静默失败。
31. 检测原语 vs 语义 API：对不同的安全概念使用 `bytes`、`string`、`[]byte`。
32. 检测原语 vs 语义 API：参数可交换而不产生类型错误。
33. 检测原语 vs 语义 API：同一类型用于 keys、nonces、ciphertexts、signatures。
34. 检查比较 footgun：`if hmac == expected { }` 有计时攻击；`if hmac.Equal(mac, expected) { }` 为常量时间；相同类型不同安全属性。
35. 检查配置悬崖：一个错误设置造成灾难性失败且无警告。
36. 检测配置悬崖：完全禁用安全的布尔标志。
37. 检测配置悬崖：未验证的字符串配置。
38. 检测配置悬崖：危险交互的设置组合。
39. 检测配置悬崖：覆盖安全设置的环境变量。
40. 检测配置悬崖：有合理默认但无验证的构造器参数（调用者可覆盖为不安全值）。
41. 检查配置悬崖例子：`verify_ssl: fasle` 拼写错误是否被静默当作真值。
42. 检查配置悬崖例子：`session_timeout: -1` 是否表示“永不过期”。
43. 检查配置悬崖例子：`auth_required: true`、`bypass_auth_for_health_checks: true`、`health_check_path: "/"` 危险组合被静默接受。
44. 检查 PHP 构造器例子：`public string $hashAlgo = 'sha256'`、`public int $otpLifetime = 120` 接受 `md5`、`0` 等。
45. 查看 `references/config-patterns.md#unvalidated-constructor-parameters` 获取详细模式。
46. 检查静默失败：错误不暴露，或成功掩盖失败。
47. 检测静默失败：安全失败时返回布尔而非抛异常。
48. 检测静默失败：安全操作周围空 catch 块。
49. 检测静默失败：解析错误时替换默认值。
50. 检测静默失败：验证函数对畸形输入“成功”。
51. 检查静默失败例子：`def verify_signature(sig, data, key): if not key: return True` 无密钥跳过验证。
52. 检查静默失败例子：`signature.verify(data, sig)` 失败抛异常 vs `crypto.verify(data, sig)` 失败返回 False，开发者忘记检查返回值。
53. 检查字符串化安全：安全关键值作为纯字符串会引发注入和混淆。
54. 检测字符串化安全：由字符串拼接构建 SQL/命令。
55. 检测字符串化安全：权限为逗号分隔字符串。
56. 检测字符串化安全：角色/范围为任意字符串而非枚举。
57. 检测字符串化安全：由字符串连接构造 URL。
58. 检查权限累积 footgun：`permissions = "read,write"`、`permissions += ",admin"` 太易提权；类型安全：`permissions = {Permission.READ, Permission.WRITE}; permissions.add(Permission.ADMIN)` 至少显式。
59. 执行 Phase 1 Surface Identification：映射安全相关 API：authentication、authorization、cryptography、session management、input validation。
60. 执行 Phase 1 Surface Identification：识别开发者选择点：哪里可选算法、配置超时、选择模式？
61. 执行 Phase 1 Surface Identification：寻找配置模式：环境变量、配置文件、构造器参数。
62. 执行 Phase 2 Edge Case Probing：对每个选择点问零/空/null：`0`、`""`、`null`、`[]` 会怎样？
63. 执行 Phase 2 Edge Case Probing：问负值：`-1` 表示无限？错误？
64. 执行 Phase 2 Edge Case Probing：问类型混淆：不同安全概念能否交换？
65. 执行 Phase 2 Edge Case Probing：问默认值：默认是否安全？是否文档化？
66. 执行 Phase 2 Edge Case Probing：问错误路径：无效输入会怎样？静默接受？
67. 执行 Phase 3 Threat Modeling：考虑 The Scoundrel：主动恶意开发者或控制配置的攻击者——能否通过配置禁用安全？能否降级算法？能否注入恶意值？
68. 执行 Phase 3 Threat Modeling：考虑 The Lazy Developer：复制粘贴示例、跳过文档——找到的第一个示例会安全吗？阻力最小路径安全吗？错误消息是否引导安全用法？
69. 执行 Phase 3 Threat Modeling：考虑 The Confused Developer：误解 API——能否交换参数而不产生类型错误？能否意外使用错误 key/algorithm/mode？失败模式是明显还是静默？
70. 执行 Phase 4 Validate Findings：对每个 sharp edge 复现误用：写最小代码演示 footgun。
71. 执行 Phase 4 Validate Findings：验证可利用性：误用是否造成真实漏洞？
72. 执行 Phase 4 Validate Findings：检查文档：危险是否文档化？（文档不能为坏设计开脱，但影响严重性）
73. 执行 Phase 4 Validate Findings：测试缓解：API 能否以合理努力安全使用？
74. 如果发现可疑，回到 Phase 2 探测更多边界情况。
75. 严重性分类 Critical：默认或明显用法不安全，如 `verify: false` 默认、允许空密码。
76. 严重性分类 High：容易误配置破坏安全，如算法参数接受 `"none"`。
77. 严重性分类 Medium：不常见但可能的误配置，如负超时有意外含义。
78. 严重性分类 Low：需要故意误用，如晦涩参数组合。
79. 按类别读取参考：Cryptographic APIs 见 `references/crypto-apis.md`。
80. 按类别读取参考：Configuration Patterns 见 `references/config-patterns.md`。
81. 按类别读取参考：Authentication/Session 见 `references/auth-patterns.md`。
82. 按类别读取参考：Real-World Case Studies 见 `references/case-studies.md`（OpenSSL、GMP 等）。
83. 按语言读取参考：C/C++ 见 `references/lang-c.md`。
84. 按语言读取参考：Go 见 `references/lang-go.md`。
85. 按语言读取参考：Rust 见 `references/lang-rust.md`。
86. 按语言读取参考：Swift 见 `references/lang-swift.md`。
87. 按语言读取参考：Java 见 `references/lang-java.md`。
88. 按语言读取参考：Kotlin 见 `references/lang-kotlin.md`。
89. 按语言读取参考：C# 见 `references/lang-csharp.md`。
90. 按语言读取参考：PHP 见 `references/lang-php.md`。
91. 按语言读取参考：JavaScript/TypeScript 见 `references/lang-javascript.md`。
92. 按语言读取参考：Python 见 `references/lang-python.md`。
93. 按语言读取参考：Ruby 见 `references/lang-ruby.md`。
94. 另见 `references/language-specific.md` 合并快速参考。
95. 质量检查：探测所有零/空/null 边界情况。
96. 质量检查：验证默认值安全。
97. 质量检查：检查算法/模式选择 footgun。
98. 质量检查：测试安全概念之间的类型混淆。
99. 质量检查：考虑全部三种对手类型。
100. 质量检查：验证错误路径不绕过安全。
101. 质量检查：检查配置验证。
102. 质量检查：构造器参数已验证（不只是有默认值）——见 `references/config-patterns.md#unvalidated-constructor-parameters`。

适用边界 · 注意事项

• 不适用于实现 bug（改用标准代码审查）
• 不适用于业务逻辑缺陷（改用领域特定分析）
• 不适用于性能优化（不同关注点）