AI 技能AI 插件应用安全网络安全AI 评测【免费下载链接】skillsTrail of Bits Claude Code skills for security research, vulnerability detection, and audit workflows项目地址https://gitcode.com/gh_mirrors/skills8/skills点击查看免费下载导读本文系统讲解 Trail of Bitsskills仓库中sharp-edges技能skill的核心方法论它专门用于识别易于被开发者误用的 API、危险配置与 footgun误用陷阱设计。无论你是审计 API 设计、配置 schema还是评估加密库的人机工学ergonomics、认证/授权接口锐利边缘分析都能帮你回答一个关键问题安全用法是否恰好是阻力最小的路径。读完本文你将掌握六大 sharp edge 类别、四阶段分析工作流、三种对抗者模型以及一套可直接落地的严重性分级与质量检查清单。一、什么是 Sharp Edges 分析sharp-edges是 Trail of Bits 安全研究团队为 Claude Code 设计的一类技能其定位在 SKILL.md 的 frontmatter 中描述得非常明确Identifies error-prone APIs, dangerous configurations, and footgun designs that enable security mistakes. Use when reviewing API designs, configuration schemas, cryptographic library ergonomics, or evaluating whether code follows secure by default and pit of success principles.翻译成白话这类审计不是找实现层面的 bug而是评估 API、配置和接口在抵抗开发者误用方面的设计质量——识别出那些最容易走的路恰好通向不安全的设计。适用场景When to Use审查 API 或库的设计决策reviewing API or library design decisions审计配置 schema 中暴露的安全相关危险选项auditing configuration schemas for dangerous options评估加密 API 的人机工学设计evaluating cryptographic API ergonomics评估认证 / 授权接口assessing authentication/authorization interfaces审查任何把安全关键决策暴露给开发者的代码不适用场景When NOT to Use实现 bug交给常规代码审查standard code review业务逻辑缺陷交给领域专项分析domain-specific analysis性能优化属于另一类关注点different concern也就是说sharp edges 分析聚焦的是设计层而不是实现层。落地载体Agent 与 CLI 技能在仓库中这套方法论有两个落地形态Agent 定义sharp-edges-analyzer.md 定义了名为sharp-edges-analyzer的子代理它拥有Read、Grep、Glob三个工具可全自动执行完整的四阶段分析工作流Surface Identification → Edge Case Probing → Threat Modeling → Validate Findings并按需读取语言专项参考文档。Skill 元数据openai.yaml 提供界面展示信息display_name、icon 等README.md 给出了插件安装命令install trailofbits/skills/plugins/sharp-edges。注意仓库是只读的本文只介绍查看、安装与使用方法不涉及修改仓库内容。二、核心原则成功之坑The Pit of SuccessSharp edges 分析的全部理念浓缩在一个核心原则上The pit of success: Secure usage should be the path of least resistance. If developers must understand cryptography, read documentation carefully, or remember special rules to avoid vulnerabilities, the API has failed.安全用法应当是阻力最小的路径。如果开发者必须理解密码学原理、仔细阅读文档、或者记住特殊规则才能避免漏洞那么这个 API 已经失败了。对应地还有一个逆向概念就是footgun——一把专为打自己脚设计的枪API 表面上提供了灵活性实则在诱导开发者做出不安全的选择。三、必须拒绝的六大合理化借口在审计实践中你几乎一定会听到开发者或同事为设计缺陷辩护。该技能明确列出了一张必须拒绝的合理化借口表审查者应逐条对照绝不放行合理化借口为什么是错的必须采取的行动文档里写了开发者在截止日期压力下不会读文档让安全的选择成为默认值或唯一选项高级用户需要灵活性灵活性制造 footgun大多数高级用法其实是复制粘贴提供安全的高层 API隐藏底层原语这是开发者的责任这是在推卸责任footgun 是你设计者造的移除 footgun 或使其不可能被误用没有人真会那样用压力之下开发者什么事都干得出来假定开发者处于最大程度的困惑状态这只是一个配置项配置就是代码错误的配置会发布到生产环境校验配置拒绝危险的组合我们需要向后兼容不安全的默认值无法通过祖父条款洗白高调弃用强制迁移这些借口在 Agent 定义 中也以## Rationalizations to Reject一节重复强调说明它们是审计实践中出现频率最高的挡箭牌。四、六大 Sharp Edge 类别详解该技能把易误用的设计归纳为六大类别。以下是每一类的判定模式、代码示例与修复思路。4.1 算法/模式选择 FootgunsAlgorithm/Mode Selection核心问题允许开发者选择算法的 API就是在邀请开发者选错算法。最典型的案例是 JWTJSON Web Token。JWT 范式canonical exampleHeader 指定算法攻击者可以设置alg: none直接绕过签名校验算法混淆攻击当服务端从 RS256 切换到 HS256 时RSA 公钥被当作 HMAC 密钥使用公钥是公开的攻击者因此能伪造合法签名。根因让不可信输入控制安全关键决策。检测模式形如algorithm、mode、cipher、hash_type的函数参数用于选择密码学原语的枚举/字符串配置项中的安全机制开关。示例PHP// DANGEROUS: allows crc32, md5, sha1 password_hash($password, PASSWORD_DEFAULT); // Good - no choice hash($algorithm, $password); // BAD: accepts crc32references/crypto-apis.md 对这一类别做了更深展开包括JWT alg 头攻击的两种形式none算法跳过验签、RS256→HS256 算法混淆加密模式参数def encrypt(plaintext, key, modeECB)——ECB 永远不会是正确的选择正确设计应是无参数、内部固定使用 AES-256-GCM哈希算法降级PHP 的hash()接受任意算法字符串crc32、md5、sha256都能通过编译而password_hash()通过限制算法选择来规避此问题。修复方向算法应硬编码为唯一的安全选项绝不由数据或调用方决定。4.2 危险的默认值Dangerous Defaults核心问题默认值本身不安全或零/空值会禁用安全机制。OTP 生命周期范式# What happens when lifetime0? def verify_otp(code, lifetime300): # 300 seconds default if lifetime 0: return True # OOPS: 0 means accept all? # Or does it mean expired immediately?lifetime0的语义完全取决于实现可能意味着无限期有效最危险、立即过期、或跳过过期检查。真实世界的失败案例见 config-patterns.md包括OTP 库中lifetime0表示接受任意年龄的 OTP限流器中max_attempts0禁用了限流会话管理器中timeout0表示会话永不过期。检测模式接受 0 的超时/生命周期参数无限期立即过期绕过检查的空字符串跳过校验的 null 值禁用安全特性的布尔默认值语义未定义的负数值必问问题timeout0、max_attempts0、key时会发生什么默认值是最安全的选项吗是否存在能完全禁用安全的默认值修复示例来自 config-patterns.md# BAD def verify_otp(code: str, lifetime: int 300): if lifetime 0: return True # What?? # GOOD def verify_otp(code: str, lifetime: int 300): if lifetime 0: raise ValueError(lifetime must be positive)4.3 原语 API vs 语义 APIPrimitive vs. Semantic APIs核心问题暴露裸字节而非有意义的类型就是在邀请类型混淆。密钥、nonce、密文、签名如果用同一类型表达参数之间极容易被悄悄换位。Libsodium vs Halite 范式// Libsodium (primitives): bytes are bytes sodium_crypto_box($message, $nonce, $keypair); // Easy to: swap nonce/keypair, reuse nonces, use wrong key type // Halite (semantic): types enforce correct usage Crypto::seal($message, new EncryptionPublicKey($key)); // Wrong key type type error, not silent failure检测模式对不同安全概念都接收bytes、string、[]byte的函数参数互换不会产生类型错误的场景密钥、nonce、密文、签名使用相同类型。比较操作 footgunGo 示例// Timing-safe comparison looks identical to unsafe if hmac expected { } // BAD: timing attack if hmac.Equal(mac, expected) { } // Good: constant-time // Same types, different security properties相同类型、不同安全属性——这正是看起来一样安全性天差地别的典型。crypto-apis.md 中给出的修复方向是为不同概念定义独立类型type EncryptionKey [32]byte type Nonce [24]byte func Encrypt(plaintext []byte, key EncryptionKey, nonce Nonce) []byte // Now type system catches swaps这一类别还延伸到nonce 复用GCM/ChaCha 下 nonce 复用是灾难性的正确做法是内部生成 nonce 并随密文一起返回与常量时间比较hmac.compare_digest与直接的差别。4.4 配置悬崖Configuration Cliffs核心问题一个错误的设置就造成灾难性失败且毫无警告。检测模式完全禁用安全的布尔标志未经校验的字符串配置危险交互的配置组合覆盖安全设置的环境变量有合理默认值但无校验的构造函数参数调用方可覆盖为不安全值示例# One typo disaster verify_ssl: fasle # Typo silently accepted as truthy? # Magic values session_timeout: -1 # Does this mean never expire? # Dangerous combinations accepted silently auth_required: true bypass_auth_for_health_checks: true health_check_path: / # Oops// Sensible default doesnt protect against bad callers public function __construct( public string $hashAlgo sha256, // Good default... public int $otpLifetime 120, // ...but accepts md5, 0, etc. ) {}config-patterns.md 为这一类别提供了非常详尽的子模式包括布尔陷阱verify_ssl: false、check_signature: false、sanitize_input: false等任何禁用安全控制的布尔项以及verify_ssl: false字符串 false 在很多语言中是真值、verify_ssl: 0这类类型陷阱还有disable_auth: false、skip_validation: false这样的双重否定命名应改成auth_enabled: true、validate_input: true这类肯定式命名。魔法值max_retries: -1、cache_ttl: -1、timeout_seconds: -1真实漏洞案例——连接池的max_connections: -1表示无限导致 DoS连接耗尽。特殊字符串如allowed_origins: *CORS 通配符、log_level: none禁用安全日志同样危险。组合危害require_authentication: true与allow_anonymous_access: true同时为真时谁胜出session_cookie_secure: true与force_http: true相互矛盾修复方向是明确优先级、冲突时告警、矛盾时直接失败。环境变量危害export DATABASE_PASSWORDsecret会暴露在ps aux进程列表、被子进程继承、出现在错误转储中DEBUGtrue之类的环境变量覆盖攻击可以开启敏感信息的详细日志。配置路径穿越log_file: ../../../etc/passwd、template_dir: ../../../etc/shadow、certificate_file: /proc/self/environ——即使只读路径也可能泄露秘密修复方向是校验路径、限制在允许目录内。4.5 静默失败Silent Failures核心问题错误不上浮或者成功掩盖了失败。检测模式安全失败时返回布尔值而非抛异常的函数包裹安全操作的空 catch 块解析错误时替换默认值对畸形输入成功的验证函数示例# Silent bypass def verify_signature(sig, data, key): if not key: return True # No key skip verification?! # Return value ignored signature.verify(data, sig) # Throws on failure crypto.verify(data, sig) # Returns False on failure # Developer forgets to check return value两种 API 风格并存本身就是 footgun有的验证函数抛异常、有的返回布尔值开发者一旦混用就可能在忘记检查返回值时静默放行。auth-patterns.md 中还给出了一组相关模式空密码绕过if not stored: return True、null 绕过user is None时返回None随后None None通过比较、密码静默截断bcrypt 72 字节限制下password[:72]悄悄截断攻击者只需暴力破解截断版本、用户名枚举User not found vs Wrong password 的不同错误消息泄露用户是否存在。4.6 字符串化安全Stringly-Typed Security核心问题把安全关键值当作普通字符串导致注入与混淆。检测模式用字符串拼接构建 SQL/命令逗号分隔字符串表示的权限用任意字符串而非枚举表示的角色/作用域通过拼接字符串构造 URL权限累加 footgunpermissions read,write permissions ,admin # Too easy to escalate # vs. type-safe permissions {Permission.READ, Permission.WRITE} permissions.add(Permission.ADMIN) # At least its explicit字符串拼接让权限提升过于顺手类型安全版本至少让每一次提权都显式可见。auth-patterns.md 进一步展示了字符串权限的连环坑any(p in user.permissions for p in required.split(,))的 any-match 逻辑、if admin in user.role的子串匹配readonly_admin_viewer意外包含admin等。五、四阶段分析工作流Agent 定义与 SKILL.md 共同给出了完整的四阶段工作流它既是子代理的执行逻辑也是审计者可以手动照做的步骤。Phase 1表面识别Surface Identification映射安全相关 API认证、授权、密码学、会话管理、输入校验识别开发者选择点开发者能在哪里选择算法、配置超时、选择模式、覆盖默认值寻找配置 schema环境变量、配置文件、构造函数参数、builder 模式中接受安全相关值的部分。Phase 2边界用例探测Edge Case Probing对每个选择点系统性地追问零/空/null0、、null、[]会发生什么是禁用安全还是未定义行为负值-1意味着什么无限超时报错无符号溢出类型混淆不同安全概念密钥、nonce、密文能否在不触发类型错误的情况下互换默认值默认值安全吗能否被危险值覆盖而毫无校验错误路径无效输入时会发生什么静默接受回退到不安全默认值Phase 3威胁建模Threat Modeling围绕三种对抗者模型进行评估The Scoundrel恶棍主动恶意的开发者或控制配置的攻击者——能否通过配置禁用安全能否降级算法能否注入恶意值The Lazy Developer懒惰开发者复制粘贴示例、跳过文档、走最小阻力路径——他们找到的第一个示例是安全的吗最省事的用法是安全的吗错误消息是否引导他们走向安全用法The Confused Developer困惑开发者误解 API 契约——能否在无类型错误的情况下互换参数能否意外使用错误的密钥/算法/模式失败模式是明显的还是静默的Phase 4验证发现Validate Findings对每个识别的 sharp edge复现误用编写最小代码演示 footgun验证可利用性误用是否真的造成真实漏洞而非理论担忧检查文档危险是否被文档化文档不能为糟糕的设计开脱但会影响严重性评级测试缓解这个 API 能否以合理成本被安全使用如果某个发现存疑返回 Phase 2 继续探测更多边界用例再决定是否报告。六、严重性分级严重性判定标准示例Critical默认或明显用法即不安全verify: false是默认值允许空密码High简单的错误配置即破坏安全算法参数接受noneMedium不常见但可能发生的错误配置负超时具有意外含义Low需要刻意误用冷门参数组合这一分级在 SKILL.md 与 agent 定义中保持一致且与文档是否说明风险挂钩——文档不豁免糟糕设计但会影响评级。七、输出格式规范Agent 对每个发现按固定字段报告这也是审计报告的最小结构Category类别——六大类别之一Severity严重性——Critical/High/Medium/LowLocation位置——file:lineDescription描述——sharp edge 的具体内容Minimal misuse example最小误用示例——展示开发者如何踩坑的代码Recommendation建议——如何让 API 抗误用八、参考资源地图SKILL.md 提供了分层级的参考文档体系分析时可按需取用路径已转换为仓库根目录相对路径按类别加密 API见 references/crypto-apis.md配置模式见 references/config-patterns.md含未校验的构造函数参数小节即 SKILL.md 中链接的#unvalidated-constructor-parameters锚点认证/会话见 references/auth-patterns.md真实世界案例见 references/case-studies.mdOpenSSL、GMP 等按语言通用 footgun不限于密码学语言指南C/Creferences/lang-c.mdGoreferences/lang-go.mdRustreferences/lang-rust.mdSwiftreferences/lang-swift.mdJavareferences/lang-java.mdKotlinreferences/lang-kotlin.mdC#references/lang-csharp.mdPHPreferences/lang-php.mdJavaScript/TypeScriptreferences/lang-javascript.mdPythonreferences/lang-python.mdRubyreferences/lang-ruby.md跨语言速查可看 references/language-specific.md。参考文档中的亮点素材真实世界案例case-studies.mdGMP 的可变时间运算mpz_powm泄露指数位、mpz_clear不清零内存、OpenSSL 的SSL_CTX_set_verify回调陷阱开发者只想加日志却return 1无条件接受一切证书、RAND_bytesvsRAND_pseudo_bytes一字之差、SSL_get_peer_certificatevsSSL_get0_peer_certificate的所有权混淆、Pythonpickle与 YAMLyaml.load()的任意代码执行、PHPstrcmp类型魔术strcmp(array, string)返回NULLNULL 0为真认证被绕过。语言专项language-specific.mdC/C 的整数溢出 UB、Go 的静默回绕Go 与 Rust 的 debug/release 溢出行为差异、Go 接口 typed nil 陷阱与 JSON 大小写不敏感字段匹配{ADMIN: true}也能匹配admin字段、Rust 的mem::forget跳过析构、JS 原型污染与 ReDoS 正则、Python 的可变默认参数与eval/exec、PHP 的类型魔术哈希0e462... 0等。九、质量检查清单在得出分析结论前逐项核对已探测所有 zero/empty/null 边界用例已验证默认值是安全的已检查算法/模式选择 footgun已测试安全概念之间的类型混淆已考虑全部三种对抗者类型已验证错误路径不会绕过安全已检查配置校验构造函数参数已校验而不只是有默认值——详见 config-patterns.md关于未校验的构造函数参数的补充SKILL.md 与 config-patterns.md 反复强调一个极易被忽视的陷阱合理默认值陷阱The Sensible Default Trap。默认值安全并不代表 API 安全——调用方永远可以覆盖它// Default is secure... public function __construct( public string $hashAlgo sha256 // Good default! ) {} // ...but callers can still shoot themselves $config new Config(hashAlgo: md5); // Oops规则只要参数影响安全就必须校验。默认值只保护不指定值的开发者校验保护所有人。这类构造参数会在构造时静默接受不安全值、在后续使用时才爆炸是典型的时间炸弹。检测特征是参数名为algo、algorithm、hash*、cipher、mode、*_type算法类、*lifetime、*timeout、*ttl、*duration、max_*、min_*、*_seconds、*_attempts数值范围类、host、hostname、domain、*_url、*_uri、endpoint、callback*主机/URL 类且未在构造时校验。结语Sharp edges 分析提供了一套可复用的反 footgun审计框架六大类别帮助快速归类、四阶段工作流保证探测的系统性、三种对抗者模型覆盖人性的全部阴暗面、严重性分级让报告可排序。它的最终目标不是找到更多 bug而是推动 API 与配置设计走向成功之坑——让开发者即使想犯错也难以下手。配合仓库中按类别、按语言的参考文档crypto-apis、config-patterns、auth-patterns、case-studies 及 11 种语言的专项指南你可以在任何代码库上立即开始一次完整的锐利边缘审计。赞分享AI 技能AI 插件应用安全网络安全AI 评测【免费下载链接】skillsTrail of Bits Claude Code skills for security research, vulnerability detection, and audit workflows项目地址https://gitcode.com/gh_mirrors/skills8/skills点击查看免费下载相关推荐Sharp Edges 实战Java 高频易错点与安全审计参考指南Trail of Bits Sharp Edges 技能Sharp Edges 实战Java 高频易错点与安全审计参考指南Trail of Bits Sharp Edges 技能 本文是 Trail of BiAI 技能AI 插件应用安全网络安全AI 评测FontForge 中的 Bézier 样条三次与二次曲线的数学原理与双向转换指南FontForge 中的 Bézier 样条三次与二次曲线的数学原理与双向转换指南 Bézier 样条是字体轮廓的基础PostScript 与 TrueTyAI 技能AI 插件应用安全网络安全AI 评测Easy-Vibe 前端路由与导航深度解析从 MPA 翻页式体验到 SPA 丝滑切换的完整实战指南Easy Vibe 前端路由与导航深度解析从 MPA 翻页式体验到 SPA 丝滑切换的完整实战指南 ::: tip 导读 本文以 Easy Vibe 开源仓库AI 技能AI 插件应用安全网络安全AI 评测上一篇告别卡顿Motion Canvas帧速率自适应方案让动画流畅运行全设备下一篇终极Android依赖版本管理指南从混乱到清晰的完整实践方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
