AI编程安全审计：为Codex与Claude构建security-audit-skill实战指南

最近把手上的工作流梳理了一遍发现最值得拿出来分享的是我在 Codex 和 Claude 这类 AI 编程环境里沉淀下来的一个security-audit-skill。如果你平时用 AI 生成代码或者团队里已经有同学在通过 Codex、Claude、opencode 提效那你大概率遇到过这种情况AI 写业务功能挺快但代码里的安全问题它自己根本意识不到比如硬编码的密钥、可直接注入的 SQL、随手写出来的命令拼接、越权接口……你让 AI 修它也只能头疼医头。这个 skill 解决的就是“AI 会写代码但不会安全审计”的尴尬。它把安全审计的规则、流程、检查项沉淀成一份 Agent 能读懂能执行的“技能包”让 AI 在写完代码后自动按安全视角过一遍。这篇文章我从设计思路讲起然后拆一个能直接落地复用的实现最后聊几个实际使用中踩过的坑。适合正在用 Codex、Claude 这类工具写代码或者想给团队 Agent 加一层安全兜底的人。1. 为什么我会做一个 security-audit skill1.1 Skill 和 Agent 到底有什么区别先解决一个很多人搜过的概念问题skill 和 agent 有什么区别。我一开始也分不太清后来在实际写代码时慢慢有了一个直观的类比——agent 是那个干活的“人”它负责理解任务、拆解步骤、调用工具skill 则是这个人脑子里装着的一套“作业指导书”。你有再多 agent如果它没有对应领域的 skill做起事来就是印象流东一榔头西一棒子。放到安全审计这个场景里体会更深。让一个普通 agent 直接“帮我检查这个项目有没有安全问题”它大概率会泛泛地看几个文件名扫两眼 README然后给你一份像模像样但毫无价值的报告。而挂上security-audit-skill之后agent 就会按 skill 里的规则抽丝剥茧地走流程先读依赖清单再查配置文件然后逐层扫 API 层、SQL 层、鉴权逻辑最后汇总成标准格式的风险报告。Skill 是“术”agent 是“道”。一个没有 skill 的 agent 就像一个没有菜谱的厨师菜能熟但味道全看运气。在 Codex 生态里skill 文件就是一个带特定格式的 Markdown 包里面有 YAML frontmatter 描述元信息正文描述任务流程、检查规则、输出格式。引入这个机制之后我做的security-audit-skill就能直接被 agent 调用整个审计过程从“看心情”变成了“走流程”。1.2 这个 skill 要解决什么问题安全审计这个词范围很大从 DAST、渗透测试、合规检查到代码审计都能沾上边。但在 AI 辅助编程这个场景下我想要的 skill 必须聚焦它主要解决四类问题。第一类是密钥泄露。这是最常见也最扯淡的问题GitHub 上随便一搜就有无数把 AWS Secret Key 提交进仓库的项目。AI 写代码的时候特别喜欢直接把各种 token、密码、密钥硬编码进去因为它只是“按你的要求把功能写出来”至于这个 key 应不应该出现在仓库里它完全没有概念。第二类是注入类漏洞。SQL 注入、命令注入、模板注入这些在传统的 MVC 架构代码里太常见了。AI 生成代码时如果直接拼接用户输入进 SQL 或 shell 命令审计 skill 必须能识别出来并给出修正建议。第三类是越权问题。这个在纯静态代码审计里不好做但至少可以通过接口路径、参数传递模式发现可疑点比如某个接口只靠前端隐藏按钮来控制访问后端的鉴权逻辑缺失skill 应该能标记出来让开发者重点确认。第四类是依赖供应链风险。项目的 package.json、requirements.txt、pom.xml 里用了哪些库、是否有已知高危版本这个靠人工去翻 CVE 太不现实skill 可以定义调用 osv-scanner 或 npm audit 这类工具的流程把结果写进审计报告。这四类问题覆盖了我在实际开发中 90% 以上的安全痛点。把这四件事做扎实比做一个大而全的“AI 安全审计平台”靠谱得多。2. 核心设计思路安全审计到底审什么2.1 静态代码层的审计项在设计security-audit-skill的检查规则时我把审计对象分成了三个层次第一层就是源码里的静态代码。这一层主要靠模式匹配和抽象语法分析来发现问题Agent 执行时可以借助 semgrep、bandit、gosec 这类工具也可以用代码搜索的方式直接扫特征。静态代码层的审计项我建立了下面这张表作为 skill 内部检查清单的底稿审计项典型风险检查方法硬编码密钥云厂商 AK/SK、数据库密码、JWT Secret 泄露正则匹配长度和特征前缀如AKIA、sk-SQL 注入直接拼接用户输入进 SQL 语句检查字符串格式化处是否出现在 SQL 执行语句中命令注入用户可控参数拼入os.system、exec等追踪用户输入是否流入命令执行函数路径穿越文件名参数直接拼路径读取文件检查是否使用了path.join 未净化输入不安全的反序列化pickle.loads、yaml.load 存在 RCE 风险搜索高危反序列化函数调试后门debug 接口、测试接口遗留在生产代码搜索debugtrue、test/hack接口这里有一个容易被忽略的细节不要只检查“危险函数是否出现”比如你直接搜eval(现代代码里可能根本没有这玩意儿但各种间接的调用方式反而容易漏掉。我让 skill 在审计时先做“数据流追踪”从请求入口开始看用户输入往哪里传如果最终流向了危险函数才判定为风险。这个策略明显比单纯匹配函数名有效但实现成本也高一些后面会在规则的编写逻辑里细说。2.2 配置与依赖层的审计项第二层是配置文件。现在很多后端项目已经不用纯代码管理配置了但.env、.env.example、config/*.yaml、docker-compose.yml、application.yml这些文件仍然藏着大量风险。审计 skill 必须专门扫这些文件不是扫文件内容里的密码而是扫“这个文件是否泄漏到了不该去的地方”。比如.env.example文件里如果写了真实的数据库地址这个风险等级比.env被提交还要高因为 example 文件本来就是给别人复制用的里面出现真实地址就意味着所有人都能看到。再比如docker-compose.yml里把 MySQL 端口映射到宿主机0.0.0.0:3306又没有设置访问白名单这在云上跑起来等于数据库裸奔。依赖层的审计要区分应用类型。前端项目要看 package-lock.json 或者 yarn.lock后端 Python 看 requirements.txt 或 poetry.lockJava 看 pom.xml。审计流程里我定义了一条规则锁定清单文件优先于锁定声明文件。因为package.json里的^1.2.3是模糊版本实际装的可能已经被升级到了带漏洞的版本只有 lockfile 才记录了实际安装的精确版本。让 agent 先读 lockfile再交给依赖漏洞检查工具比对已知 CVE得到的报告才有参考价值。2.3 业务逻辑层的审计项第三层是最难的一层业务逻辑安全。这一层没有现成的工具能做因为问题不在单行代码而在多个接口之间的逻辑关系。比如一个删除接口前端传一个 id 过来后端没有校验当前用户是否拥有这个资源的操作权限这就是水平越权。security-audit-skill里对业务逻辑层的检查规则定为三个步骤。第一步扫描所有标注了 HTTP 方法的路由或视图函数列出端点清单第二步对每个端点寻找鉴权标记确认是否使用了全局鉴权中间件、装饰器或注解第三步重点关注“获取资源 ID 并操作”这一类接口检查操作前是否有“确认该资源属于当前用户”的逻辑。这一步非常依赖 agent 的推理能力也是纯静态审计工具做不到的地方。不过在 skill 的定义里我不强求 agent 100% 识别所有越权点而是要求它把“可疑接口”清单列出来标注风险等级和原因交给开发者人工确认。安全审计本身就是一个辅助决策的过程skill 的价值是缩小排查范围而不是替代人的判断。3. 实操从零写一个 security-audit skill3.1 先想清楚目录结构再动手写文件一个 standard 的 AI skill 在文件组织上通常是一个独立的目录里面有主描述文件、辅助资源文件和示例文件。以我常用的目录结构为例security-audit-skill/ ├── SKILL.md ├── rules/ │ ├── secret-detection.md │ ├── injection-detection.md │ └── dependency-audit.md ├── scripts/ │ ├── run_bandit.py │ └── scan_secrets.py ├── templates/ │ └── report_template.md └── examples/ ├── vulnerable_sample.py └── secure_sample.py实际的目录可以根据你使用的框架调整但核心原则是主文件只负责定义流程和规则概览具体规则拆分成独立文件维护脚本工具独立成文件避免把几百行内容全堆在一个 SKILL.md 里。我自己一开始就把所有规则写在了一个文件里结果 agent 在上下文窗口里加载了大量冗余信息审计效率反而很低后来拆成细粒度文件之后agent 只按需读取对应规则文件效果立刻改善。3.2 编写 SKILL.md 主文件的格式与要点SKILL.md 是 agent 的入口。Codex、Claude、opencode 这类工具对 skill 的识别机制不尽相同但普遍会读文件和解析 YAML frontmatter。所以这个文件一定要写好name和description因为 agent 是靠 description 来判断“什么任务应该调用这个 skill”。一个可用的 SKILL.md 骨架长这样--- name: security-audit-skill description: Perform automated security audit for code projects. Use when user asks to check code security, find vulnerabilities, audit dependencies, or review risky code patterns. --- # Security Audit Skill ## Goal Automatically scan a codebase for common security issues, generate structured risk report with severity levels and remediation suggestions. ## Trigger Conditions - User explicitly asks to run security audit/check. - User asks is this code safe. - Code review workflow requires security pass. ## Workflow 1. Identify project type based on lockfiles and language. 2. Load dependency audit rules from rules/dependency-audit.md. 3. Run secret scan using scripts/scan_secrets.py. 4. Run static analysis rules in order defined in rules/injection-detection.md and rules/secret-detection.md. 5. Compile all findings into templates/report_template.md. 6. Output report with risk levels H/M/L. ## Constraints - Do not modify source code unless user explicitly asks for fixes. - Do not run active penetration tests against live systems. - Mark all automated results as requires manual verification.description 字段我有几个心得。第一不要只写一个宽泛的 “security audit skill”agent 在意图匹配时可能匹配不上第二要多写几个同义触发场景“check security”“find vulnerabilities”“code safety review”这些都要带上第三在 description 里注明适用语言和技术栈能减少后面跨语言误调用的问题比如 “Designed for Python and JavaScript projects”。3.3 审计规则的编写逻辑不是列清单而是给判断标准规则文件rules/secret-detection.md是 skill 的核心逻辑。这里我踩过一个严重的坑一开始我让 agent 用“搜索关键字”的方式找密钥比如搜password 、secret 结果误报率接近 70%因为password可能只是一个表单字段名不一定是硬编码口令。后来我把规则改成“三层判断法”实测误报率下降到 20% 以下。第一层是结构判断看变量赋值右侧的值是否符合密钥格式特征比如长度、字符集、特殊前缀第二层是上下文判断看这个赋值是来自环境变量读取os.environ.get、配置中心接口还是字面量字符串第三层是来源判断看密钥值里是否混入了项目名、域名等可推断的低熵内容。在注入检测的规则里我也把“搜索危险函数”改成了“追踪数据流 污点分析”。对 agent 来说这一步需要理解代码语义不能靠正则完成所以我在规则文件里直接定义了数据流的分析路径找输入源request params、form data、query string、CLI args、文件读取内容找汇聚点SQL execute、shell 执行、HTML 渲染、pickle.loads、yaml.load在每条汇聚点处回溯上游变量判断输入是否经过净化参数化查询、转义函数、白名单校验如果输入未经净化直达汇聚点记录为 High 风险。这套思路与其说是规则文件不如说是给 agent 的“思考脚手架”。agent 本身有语义理解能力但没有领域经验不知道“哪里该看、哪里该停”。skill 的价值正在于把这些经验结构化成 agent 可以直接照着执行的操作步骤。3.4 接入现成工具别什么都让 agent 硬扫Agent 能靠推理找出一些问题但有些事天然适合专用工具。比如依赖漏洞比对你不会想让 agent 靠记忆去判断某个版本有没有 CVE这超出了模型的知识范围。所以在 skill 的 Workflow 里我专门定义了一个步骤调用本地脚本运行对应的扫描工具再把输出结果解析为统一格式。以 Python 项目为例我在scripts/run_bandit.py里写了一个简单的包装脚本重点是输出标准化 JSON 供 agent 解析import subprocess import json import sys def run_bandit(target_path): result subprocess.run( [bandit, -r, target_path, -f, json, -q], capture_outputTrue, textTrue ) try: data json.loads(result.stdout) except json.JSONDecodeError: print(json.dumps({error: result.stderr, target: target_path}, indent2)) sys.exit(1) findings [] for issue in data.get(results, []): findings.append({ file: issue.get(filename), line: issue.get(line_number), severity: issue.get(issue_severity), confidence: issue.get(issue_confidence), cwe: issue.get(issue_cwe, {}).get(id), text: issue.get(issue_text), }) print(json.dumps(findings, indent2)) if __name__ __main__: run_bandit(sys.argv[1])这个脚本本身不复杂但有一个关键点一定要在 skill 的规则文件里说明输出格式的含义告诉 agentseverity字段的映射关系HIGH、MEDIUM、LOW以及它应该怎么把工具输出和前后文代码结合起来判断。否则 agent 拿了 bandit 的 JSON 只会原样贴在报告里不会做二次判断。前端项目我接的是npm audit --json输出解析逻辑类似但增加了“只输出 high 和 critical 等级”的过滤规则因为 npm audit 报的 moderate 问题太多了全量写进报告反而淹没了真正危险的项。4. 落地到 Codex / Claude / opencode怎么让 agent 真正用起来4.1 注册 skill 与加载路径配置写好 skill 文件之后下一步就是让 Codex、Claude 或 opencode 能发现它。不同工具加载 skill 的方式有差异但大体思路是一致的把 skill 目录放到一个 agent 可扫描的约定路径下或者在 agent 的配置里声明 skill 搜索路径。在 Codex 的环境里可以在项目根目录建.agents/skills/目录把security-audit-skill整个文件夹放进去或者在全局配置目录下放置让所有项目都能共享。Claude 的 Agent SDK 则需要在使用时通过 system prompt 或 tool 定义把 skill 内容注入到上下文中。opencode 的插件机制也类似它支持在配置里指定 skill 搜索路径。如果你用的工具是通过 system prompt 加载 skill那有一个技巧不要把 SKILL.md 全文塞进 system prompt而是只塞一段加载器文本。加载器里写清楚 skill 目录的路径和触发条件让 agent 在收到安全审计任务时自己去读取 SKILL.md 和相关规则文件。这样能大幅节省上下文窗口效果比全文注入好得多。我实际常用的加载器提示词长这样You have access to a security audit skill located at /path/to/security-audit-skill. When the user requests a security review or vulnerability check, first read /path/to/security-audit-skill/SKILL.md and follow the workflow defined there. Use the rules in the rules/ directory to guide your analysis, and run scripts from the scripts/ directory when needed.4.2 在真实项目中跑一遍审计流程我把这个 skill 在一个 Flask Vue 的演示项目上实际跑了一遍这里还原一下大致过程方便你直观感受效果。项目结构比较简单有登录接口、文件上传接口和一个管理后台的查询接口。Agent 接到“用 security-audit-skill 审计这个项目”的指令后第一步读取了 SKILL.md然后开始按 Workflow 走。它先扫描了目录结构识别出是 Python JavaScript 项目接着调用了run_bandit.py对 Python 源码做静态扫描拿到了 3 个 bandit 中高风险问题。然后按secret-detection.md的规则扫了一遍环境变量文件和配置发现在.env.example里存在一个看起来像真实 JWT Secret 的字符串。接下来 agent 做了几件我没想到但确实是规则预期内的事它回溯了登录接口的 JWT 生成代码定位了那个疑似密钥的变量是从环境变量读取还是硬编码又在 Vue 前端代码里搜了一遍localStorage和sessionStorage检查是否直接存储了敏感 token最后检查了文件上传接口发现代码没有对上传文件的后缀名做白名单校验只做了 content-type 检查而 content-type 是客户端可以直接伪造的它把这一条标成了 High 风险。最终生成的报告自动套用了report_template.md模板每个发现项都包含文件、行号、风险等级、问题说明和修复建议。整个流程比我以前手动跑一遍 bandit npm audit 效率高太多关键是 agent 能把工具输出和业务代码逻辑串起来分析这个信息整合的价值是单纯工具输出没法比的。5. 常见问题与排查技巧实录5.1 误报太多报告根本没法看这是我实际使用中遇到的第一个问题也是问的最多的一个问题。skill 第一版上线后agent 扫描一个中型项目抛出了 60 多个“风险”看起来好像很尽职但点开一看三分之一是第三方依赖库里检测出的低危告警、四分之一是文档字符串里包含了password这个词、还有一些是错误地把测试代码当成了生产代码。后来我给报告输出加了三道过滤第一排除测试目录test/、tests/、__tests__/、spec/除非用户特别要求审计测试代码第二低置信度的风险降级为INFO不进入主报告只出现在附注里第三依赖类问题只保留HIGH和CRITICALmoderate 和 low 都折叠到明细里。加了这三个过滤之后报告长度直接砍掉了七成剩下的每一条都值得人工点开看一眼。5.2 Agent 只会按流程走不会结合业务上下文怎么办另一个常见问题是agent 虽然加载了 skill但它对项目业务完全不了解审计结果往往停留在“代码片段有问题”的层面意识不到“这个接口是内部管理系统接口、影响面不大”或“这个接口是公开注册接口、风险极高”这类业务差异。我的做法是在 skill 的 Workflow 里加了一步“上下文采集”。在执行静态扫描之前先让 agent 读项目的 README、接口文档、最近的 commit 信息尝试理解项目定位和核心业务逻辑。然后在校验阶段让 agent 对每个风险点打一个“业务影响值”这个值不是规则写死的而是 agent 结合上下文推测的。虽然这个推断不一定 100% 准确但可以让开发者更快地判断“这个问题要不要立刻处理”。如果项目有 API 文档或者 OpenAPI 规范文件我强烈建议在 skill 配置里把这个文件的路径作为强制读取项。一份规范的 OpenAPI 文档能让 agent 把代码审计结果对应到具体业务接口上审计报告的可用性会上一个台阶。5.3 多语言项目怎么适配这个 skill 最开始只写了 Python 的规则后来项目里有前端、有 Java 服务agent 拿着 Python 规则去审 JavaScript 代码就会出现大面积漏检。现在的做法是给规则文件加了语言标签在 SKILL.md 的 Workflow 开头就要求 agent 先识别项目里每一类代码的语言和技术栈然后按语言加载对应的规则子集。rules/ ├── _shared.md # 通用规则 ├── python_rules.md # Python/Flask/Django ├── javascript_rules.md # Node/Express/Vue/React └── java_rules.md # Spring Boot/MyBatis另外我建议在多语言项目里让 agent 在最终报告里按语言分组输出前端、后端、基础设施各自的审计结果分开列修复责任人也能一眼看清该把哪个部分派给谁。5.4 Skill 被 Agent “跳过”了明明调用了却不生效这种情况我也遇到过。调用了 skill但 agent 只回答了一堆泛泛的“安全很重要你要注意代码质量”之类的话完全没有按 SKILL.md 的流程走。排查下来最可能的原因是 skill 的description写得不够精确agent 在意图匹配阶段觉得这个任务不适合调用这个 skill于是自己“自由发挥”。另外一个原因是 SKILL.md 里的 Workflow 写得太模糊agent 读了以后不了解先做什么后做什么。解决方法是把 Workflow 写成“可执行的操作序列”每一步都明确输入、操作、输出。不要让 agent 自己想“我该怎么审计”而是告诉它“第一步看什么文件、第二步运行什么脚本、第三步输出什么格式”。它就不容易跑偏了。6. 把 skill 变成团队资产几条实战心得到这里一个可用的security-audit-skill已经从设计、编写到落地部署完整走了一遍。最后分享几点我在真实项目里反复验证过的体会。第一skill 不是写一次就完事的东西。安全规则库变化很快新的攻击手法、新的漏洞类型层出不穷。我每个季度会更新一次规则文件把团队最近踩过的坑补充进去把误报率高的规则调整掉。把规则文件拆成独立文件的一大好处就是更新成本很低只改动一个 markdown 文件就能让全团队的 agent 受益。第二不要试图让 skill 覆盖所有安全问题。它在少数几个领域内做深比眉毛胡子一把抓更可靠。我的选择是聚焦密钥泄露、注入、越权和依赖风险这四个方向其他的比如加密算法强度、证书配置、合规要求这些交给专业的审计工具去做skill 不加戏。专注才能真正可用这个体会来自我踩过的所有“大而全但什么都没查出来”的坑。第三也是最实际的一个建议先跑通一次完整的审计流程拿到一份像样的报告再考虑扩能力。第一次调试 skill 的时候我把大部分时间花在了调整输出格式上而不是优化检查规则。后来发现输出格式直接影响开发者愿不愿意看这份报告。结构清晰、风险明确、修复建议可执行比把报告写成一个长篇大论的安全论文重要得多。如果你现在正打算给团队内部的 AI 编程流程加一个安全兜底环节最有效的做法就是照着这篇文章搭一个最小的security-audit-skill出来先跑通再迭代。等到哪一天 agent 帮你提前拦下一个硬编码的数据库密码你会觉得这些折腾都值了。