前言¶

用 Cursor、Codex CLI 等 AI 編程工具寫代碼，速度往往比人工快一個數量級，但安全細節也更容易被一帶而過：SQL 注入、不安全的 CORS 配置、Cookie 未設 HttpOnly、公開接口使用自增 ID……這些問題在 AI 生成的樣板代碼裏並不少見。傳統做法是靠安全團隊做 Code Review，或上線前跑一輪 SAST 掃描，成本高、節奏也慢。

OpenAI 在官方 openai/skills 倉庫的 .curated 目錄中提供了 security-best-practices 這一 Agent Skill。它把 Python、JavaScript/TypeScript、Go 常見框架的安全規範寫進 references/ 參考文檔，讓 Agent 在寫新代碼、被動巡檢或生成安全報告時，有章可循。本文基於官方 SKILL.md 與參考文件覈實，介紹它的定位、能力與用法。

這是什麼¶

security-best-practices 是 OpenAI 官方精選（curated）Skill 之一，遵循通用 Agent Skills 格式（SKILL.md + 資源目錄）。官方描述爲：針對語言與框架執行安全最佳實踐審查並給出改進建議；僅在用戶明確要求安全最佳實踐指導、安全審查/報告或 secure-by-default 編碼幫助時觸發；僅支持 Python、JavaScript/TypeScript、Go；不用於一般代碼審查、調試或非安全類任務。

Skill 目錄結構（摘自官方倉庫）大致如下：

security-best-practices/
├── SKILL.md              # 技能說明、工作流與報告格式
├── references/           # 各語言/框架安全規範（MUST/SHOULD 級要求）
│   ├── python-django-web-server-security.md
│   ├── python-fastapi-web-server-security.md
│   ├── python-flask-web-server-security.md
│   ├── javascript-express-web-server-security.md
│   ├── javascript-general-web-frontend-security.md
│   ├── javascript-jquery-web-frontend-security.md
│   ├── javascript-typescript-nextjs-web-server-security.md
│   ├── javascript-typescript-react-web-frontend-security.md
│   ├── javascript-typescript-vue-web-frontend-security.md
│   └── golang-general-backend-security.md
├── agents/               # Agent 相關配置
└── LICENSE.txt

官方 README 註明 openai/skills 倉庫已標記爲 deprecated，後續 Skill 示例遷移至 OpenAI Plugins 倉庫；當前目錄下的 Skill 仍可安裝使用，團隊落地時建議關注上游更新。

核心功能與亮點¶

1. 自動識別技術棧並加載對應規範¶

Skill 的第一步是識別項目中的全部語言與核心框架（前後端均需覆蓋）。隨後到 references/ 目錄查找匹配文檔：文件名格式爲 <language>-<framework>-<stack>-security.md，也可能存在 <language>-general-<stack>-security.md 這類與具體框架無關的通用規範。

例如全棧 Web 項目使用 React + FastAPI，Agent 應分別加載 javascript-typescript-react-web-frontend-security.md 與 python-fastapi-web-server-security.md；若前端框架未指定，官方建議額外查閱 javascript-general-web-frontend-security.md。

2. 三種工作模式¶

官方 SKILL.md 定義了三種互補的運行方式：

1. Secure-by-default 編碼（主模式）：寫新代碼時默認遵循參考規範中的 MUST/SHOULD 要求，適合新項目或新增模塊。
2. 被動檢測：在日常改代碼過程中，對觸及範圍內的高影響漏洞或明顯違背安全指引的問題進行提醒，聚焦最大風險項。
3. 主動安全報告：用戶明確要求審查或改進安全時，產出按嚴重程度分級的完整報告，並附修復建議。

若 references/ 中沒有匹配文檔，Agent 可結合已知最佳實踐或聯網檢索；生成報告時應如實說明「無具體官方參考文檔」，避免把推斷當作確定結論。

3. 內置 10 份框架級安全規範¶

references/ 目錄目前包含 10 份 Markdown 規範，每份文件體量在 3 萬～5 萬字量級，以 MUST/SHOULD/MAY normative 要求 + 審計規則的形式編寫。以 python-fastapi-web-server-security.md 爲例，覆蓋內容包括：

• 安全邊界：禁止輸出/記錄密鑰，禁止通過關閉 CORS、跳過簽名校驗等方式「僞修復」
• 輸入信任模型：Query、Body、Header、Cookie、文件上傳、WebSocket 消息均視爲不可信
• 審計順序：入口腳本 → ASGI 配置 → 中間件/CORS → 認證授權 → CSRF → 注入類 → SSRF 等
• 生成、被動、主動三種模式下的具體行爲要求

其他參考文件對應 Django、Flask、Express、Next.js、React、Vue、jQuery 前端及 Go 後端等場景，Agent 會讀取所有與當前技術棧相關的文件，而非只看一份。

4. 結構化安全報告¶

用戶請求安全報告時，Skill 要求將結果寫入 security_best_practices_report.md（或用戶指定的路徑），格式包括：

• 頂部簡短 executive summary
• 按嚴重程度分節，每條發現帶數字 ID 便於引用
• Critical 級別附一句 impact 說明
• 引用代碼時須標註文件路徑與行號
• 報告寫完後在對話中摘要告知，並說明文件保存位置

5. 審慎的修復流程¶

Skill 對修復環節有明確約束，避免「爲了安全把項目改掛」：

• 一次只修一個 finding，改動附簡短註釋說明依據的安全實踐
• 修復前評估對現有功能的影響， insecure 代碼有時被其他邏輯依賴
• 遵循用戶既有的 commit / 測試流程；多個無關 finding 不要塞進同一個 commit
• 項目文檔若明確要求 override 某條最佳實踐，Agent 應尊重並可在註釋中說明，而非與用戶對抗

6. 跨語言通用安全建議¶

SKILL.md 還收錄了幾條與語言無關的提示，例如：

• 對外暴露的資源 ID 避免使用小整數自增，改用 UUID4 或隨機 hex，降低枚舉風險
• 開發環境通常無 TLS，不應把「未啓用 TLS」直接報爲漏洞；Secure Cookie 也只在 HTTPS 部署時啓用，避免本地調試中斷
• 謹慎推薦 HSTS，誤配可能導致長期 outage

7. 與安全 Skill 套件協同¶

在 OpenAI curated 目錄中，security-best-practices 與 security-threat-model、security-ownership-map 組成安全三件套：威脅建模 → 代碼歸屬映射 → 最佳實踐 enforcement，可按需組合安裝。

安裝與啓用¶

security-best-practices 遵循通用 SKILL.md 格式，可在 Codex CLI、Cursor 等支持 Agent Skills 的工具中使用。以下方式來自官方 README 或 Agent Skills 生態公開說明；各工具細節以本地環境爲準。

方式一：Codex CLI 內置安裝器¶

在 Codex 會話中執行（curated Skill 可直接按名稱安裝）：

$skill-installer security-best-practices

也可指定 GitHub 目錄 URL：

$skill-installer install https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices

安裝後重啓 Codex 以加載新 Skill。默認安裝路徑爲 $CODEX_HOME/skills/（通常爲 ~/.codex/skills/）。可用 $skill-installer list 查看已安裝列表。

方式二：Skills CLI 安裝¶

npx skills add https://github.com/openai/skills --skill security-best-practices

方式三：手動複製 Skill 目錄¶

Skill 是自包含的，需複製整個 security-best-practices 文件夾（含 references/），而不僅是 SKILL.md：

# 項目級（Cursor 示例）
.cursor/skills/security-best-practices/

# 項目級（Claude Code 示例）
.claude/skills/security-best-practices/

# Codex 用戶級
~/.codex/skills/security-best-practices/

注意：僅複製 SKILL.md 而不帶 references/，Agent 無法加載框架級安全規範，審查質量會大幅下降。

典型用法示例¶

啓用 Skill 後，需明確表達安全相關意圖纔會觸發（不會替代普通 code review）。以下爲基於官方工作流整理的提示詞示例：

示例 1：對現有 FastAPI 項目做安全審查

請對當前 FastAPI 項目做 security best practices 安全審查，
按嚴重程度輸出報告，寫入 security_best_practices_report.md，
引用代碼時請標註文件路徑和行號。

示例 2：新功能 secure-by-default 開發

我要新增一個 Express 用戶註冊接口，請按 security-best-practices
規範編寫，默認使用安全的密碼哈希、輸入校驗和合理的 CORS 配置。

示例 3：全棧項目前後端同時覆蓋

這是一個 Next.js + Django 的全棧項目，請檢查前後端是否遵循
security-best-practices 中對應框架的安全要求，列出 Critical 和 High 級別問題。

示例 4：修復單個 finding

請根據 security_best_practices_report.md 中的 #3  finding，
給出最小改動的修復方案，修完跑現有測試確認無迴歸。

Agent 會先識別技術棧、加載 references/ 中相關文件，再按模式執行編碼、被動提醒或生成報告。

適用場景與注意事項¶

適合誰用¶

• 用 AI 快速迭代 Web 後端或全棧項目，希望在開發階段就嵌入安全檢查的開發者。
• 技術負責人希望在 PR 或迭代節點獲得結構化安全報告、而非零散提醒的團隊。
• 正在學習 Agent Skills 寫法、希望參考「規範文檔 + 多模式工作流」設計模式的安全或平臺工程師。

使用限制¶

1. 必須主動觸發：Skill 不會在普通「幫我改個 bug」「優化性能」類請求中自動介入；描述中需包含安全審查、secure-by-default 等明確意圖。
2. 語言範圍有限：官方僅覆蓋 Python、JavaScript/TypeScript、Go；Rust、Java、PHP 等需依賴 Agent 通用知識，無 bundled 參考文檔時結論應更謹慎。
3. 需完整 Skill 目錄：references/ 是核心價值所在，缺省後只剩 SKILL.md 中的通用建議。
4. 不替代專業滲透測試：Skill 面向最佳實踐與常見漏洞模式，不能取代人工紅隊、依賴掃描或合規審計。
5. 尊重項目 override：若業務文檔明確要求繞過某條規範，Agent 會配合而非強行「修復」；團隊可在項目內記錄 override 原因以便後續一致執行。
6. 上游倉庫狀態：openai/skills 已 deprecated，長期使用建議跟蹤 OpenAI Plugins 或 Codex Skills 文檔 的遷移說明。

小結¶

security-best-practices 把 OpenAI 整理的語言/框架安全規範打包成 Agent Skill，通過「識別技術棧 → 加載 references → 編碼/巡檢/報告」三條路徑，讓 AI 輔助開發不再默認犧牲安全底線。對於 Python、JavaScript/TypeScript、Go 技術棧的 Web 項目，它是 Codex 官方 curated 目錄裏值得優先安裝的安全基線 Skill；與威脅建模、歸屬映射類 Skill 組合使用，可形成更完整的安全工作流。

官方 Skill 目錄：

• https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices
• Codex Skills 說明：https://developers.openai.com/codex/skills
• Agent Skills 開放標準：https://agentskills.io