前言¶

用 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