名称: sharp-edges 描述: “识别易错API、危险配置和导致安全失误的’陷阱’设计。在审查API设计、配置模式、加密库人体工学或评估代码是否遵循’默认安全’和’成功陷阱’原则时使用。触发词：陷阱、抗误用、安全默认、API可用性、危险配置。” 允许工具:

读取
搜索
全局匹配

锋利边缘分析

评估API、配置和接口是否抗开发人员误用。识别设计中“简易路径”导致不安全的情况。

何时使用

审查API或库设计决策
审计配置模式中的危险选项
评估加密API人体工学
评估认证/授权接口
审查任何向开发人员暴露安全相关选择的代码

何时不使用

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

核心原则

成功陷阱：安全使用应是最小阻力路径。如果开发人员必须理解加密、仔细阅读文档或记住特殊规则来避免漏洞，API就失败了。

需拒绝的合理化

合理化	为何错误	所需行动
“已文档化”	开发人员在截止压力下不读文档	使安全选择成为默认或唯一选项
“高级用户需要灵活性”	灵活性创造陷阱；大多数“高级”使用是复制粘贴	提供安全高级API；隐藏原语
“是开发人员的责任”	推卸责任；你设计了陷阱	移除陷阱或使其不可能误用
“没人会真的那么做”	开发人员在压力下会做一切想象的事情	假设最大开发人员困惑
“这只是一个配置选项”	配置即代码；错误配置会部署到生产	验证配置；拒绝危险组合
“我们需要向后兼容”	不安全默认不能祖父条款化	大声弃用；强制迁移

锋利边缘类别

1. 算法/模式选择陷阱

允许开发人员选择算法的API会招致错误选择。

JWT模式（典型示例）：

头部指定算法：攻击者可设置 "alg": "none" 以绕过签名
算法混淆：切换RS256→HS256时，RSA公钥用作HMAC密钥
根本原因：让不受信任输入控制安全关键决策

检测模式：

函数参数如 algorithm、mode、cipher、hash_type
枚举/字符串选择加密原语
安全机制的配置选项

示例 - PHP password_hash 允许弱算法：

// 危险：允许crc32、md5、sha1
password_hash($password, PASSWORD_DEFAULT); // 好 - 无选择
hash($algorithm, $password); // 坏：接受 "crc32"

2. 危险默认

不安全的默认值，或禁用安全的零/空值。

OTP生命周期模式：

# 当lifetime=0时发生什么？
def verify_otp(code, lifetime=300):  # 300秒默认
    if lifetime == 0:
        return True  # 哎呀：0意味着“接受所有”？
        # 或意味着“立即过期”？

检测模式：

接受0的超时/生命周期（无限？立即到期？）
绕过检查的空字符串
跳过验证的空值
禁用安全功能的布尔默认
语义未定义的负值

要问的问题：

timeout=0、max_attempts=0、key="" 时发生什么？
默认是最安全选项吗？
任何默认值能完全禁用安全吗？

3. 原语与语义API

暴露原始字节而非有意义类型的API会招致类型混淆。

Libsodium 与 Halite 模式：

// Libsodium（原语）：字节就是字节
sodium_crypto_box($message, $nonce, $keypair);
// 易于：交换nonce/keypair、重用nonce、使用错误密钥类型

// Halite（语义）：类型强制正确使用
Crypto::seal($message, new EncryptionPublicKey($key));
// 错误密钥类型 = 类型错误，而非静默失败

检测模式：

函数以 bytes、string、[]byte 接收不同安全概念
可交换而无类型错误的参数
密钥、随机数、密文、签名使用相同类型

比较陷阱：

// 时间安全比较看起来与不安全相同
if hmac == expected { }           // 坏：时序攻击
if hmac.Equal(mac, expected) { }  // 好：恒定时间
// 相同类型，不同安全属性

4. 配置悬崖

一个错误设置导致灾难性失败，无警告。

检测模式：

完全禁用安全的布尔标志
未验证的字符串配置
危险交互的设置组合
覆盖安全设置的环境变量
有合理默认但无验证的构造函数参数（调用者可用不安全值覆盖）

示例：

# 一个拼写错误 = 灾难
verify_ssl: fasle  # 拼写错误被静默接受为真值？

# 魔法值
session_timeout: -1  # 这意味“永不过期”？

# 危险组合被静默接受
auth_required: true
bypass_auth_for_health_checks: true
health_check_path: "/"  # 哎呀

// 合理默认不保护坏调用者
public function __construct(
    public string $hashAlgo = 'sha256',  // 好默认...
    public int $otpLifetime = 120,       // ...但接受md5、0等
) {}

详见配置模式.md获取详细模式。

5. 静默失败

不暴露的错误，或掩盖失败的“成功”。

检测模式：

函数返回布尔值而非安全失败时抛出
安全操作周围的空catch块
解析错误时替换默认值
对畸形输入“成功”的验证函数

示例：

# 静默绕过
def verify_signature(sig, data, key):
    if not key:
        return True  # 无密钥 = 跳过验证？！

# 返回值被忽略
signature.verify(data, sig)  # 失败时抛出
crypto.verify(data, sig)     # 失败时返回False
# 开发人员忘记检查返回值

6. 字符串化安全

安全关键值作为纯字符串会招致注入和混淆。

检测模式：

字符串连接构建的SQL/命令
逗号分隔字符串的权限
任意字符串的角色/范围而非枚举
连接字符串构建的URL

权限累积陷阱：

permissions = "read,write"
permissions += ",admin"  # 太易于升级

# 对比类型安全
permissions = {Permission.READ, Permission.WRITE}
permissions.add(Permission.ADMIN)  # 至少是显式

分析工作流

阶段1：表面识别

映射安全相关API：认证、授权、加密、会话管理、输入验证
识别开发人员选择点：开发人员可在何处选择算法、配置超时、选择模式？
查找配置模式：环境变量、配置文件、构造函数参数

阶段2：边缘案例探测

针对每个选择点，问：

零/空/null：0、""、null、[] 时发生什么？
负值：-1 意味什么？无限？错误？
类型混淆：不同安全概念可交换吗？
默认值：默认安全吗？已文档化？
错误路径：无效输入时发生什么？静默接受？

阶段3：威胁建模

考虑三个对手：

恶棍：主动恶意开发人员或控制配置的攻击者
- 他们能通过配置禁用安全吗？
- 能降级算法吗？
- 能注入恶意值吗？
懒惰开发人员：复制粘贴示例，跳过文档
- 他们找到的第一个示例会是安全的吗？
- 最小阻力路径安全吗？
- 错误消息引导向安全使用吗？
困惑开发人员：误解API
- 他们能不产生类型错误地交换参数吗？
- 能意外使用错误密钥/算法/模式吗？
- 失败模式明显还是静默？

阶段4：验证发现

针对每个识别的锋利边缘：

重现误用：编写最小代码演示陷阱
验证可利用性：误用会产生真实漏洞吗？
检查文档：危险已文档化吗？（文档不原谅坏设计，但影响严重性）
测试缓解：API能以合理努力安全使用吗？

如果发现看似可疑，返回阶段2并探测更多边缘案例。

严重性分类

严重性	标准	示例
关键	默认或明显使用不安全	`verify: false` 默认；允许空密码
高	易配置错误破坏安全	算法参数接受 “none”
中	不寻常但可能的配置错误	负超时有意外含义
低	需故意误用	晦涩参数组合

参考

按类别：

加密API：见参考/加密API.md
配置模式：见参考/配置模式.md
认证/会话：见参考/认证模式.md
真实世界案例研究：见参考/案例研究.md (OpenSSL、GMP等)

按语言（一般陷阱，非加密特定）：

语言	指南
C/C++	参考/语言-c.md
Go	参考/语言-go.md
Rust	参考/语言-rust.md
Swift	参考/语言-swift.md
Java	参考/语言-java.md
Kotlin	参考/语言-kotlin.md
C#	参考/语言-csharp.md
PHP	参考/语言-php.md
JavaScript/TypeScript	参考/语言-javascript.md
Python	参考/语言-python.md
Ruby	参考/语言-ruby.md

另见参考/语言特定.md获取综合快速参考。

质量检查清单

分析结束前：

[ ] 探测所有零/空/null边缘案例
[ ] 验证默认值安全
[ ] 检查算法/模式选择陷阱
[ ] 测试安全概念间类型混淆
[ ] 考虑所有三种对手类型
[ ] 验证错误路径不绕过安全
[ ] 检查配置验证
[ ] 构造函数参数已验证（不仅默认） - 见配置模式.md