前言¶
很多安全問題不是某一行實現寫錯，而是接口把「省事的路徑」設成了不安全的路徑：可選弱算法、默認值能關掉校驗、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
