我真正下决心做security-audit-skill是在一次线上事故复盘之后。当时我让Codex直接审查一个订单服务的代码结果它花了二十分钟给出一份看起来很全面、但实际上漏掉了最关键的越权接口的检查报告。问题不在于模型能力而在于我给的指令太含糊。后来我把安全审计的流程、规则、工具调用方式全部做成了Agent Skill再让同一个模型去跑表现稳定了一个层级。这篇内容就是记录我如何设计、编写、调试一个security-audit-skill并让它落地到日常开发和CI流程里。如果你正在给Codex、Claude这类AI代理编写专属skill或者想用AI做代码安全审计这篇文章应该能帮你少踩不少坑。1. 项目概览为什么AI代理需要“安全审计技能”1.1 直接对话式审计的痛点很多人的第一反应是既然大模型会写代码、能读文件那直接让它“审计一下这个项目”不就行了我一开始也这么干但实际用下来会碰到几个非常具体的问题。第一是检查范围不收敛。模型可能只读了一个目录或者被某个文件里的细节带跑偏压根没有系统性地覆盖整个仓库。安全审计要求的是“资产面全覆盖”漏一个配置文件可能就是事故但大模型默认不会像专业工具那样按清单执行。第二是判断标准不可控。同一个代码片段你可能希望它按你的团队规范判断而不是按模型的通用知识判断。比如你们内部规定数据库连接不上传、密钥必须走密钥管理服务这种组织级的规则靠聊天式prompt很难稳定生效。第三是没有可复现的执行流程。聊天式审计每次的输出结构、执行时长、覆盖深度都不一样你很难把它接入自动化流水线也没法做前后对比。把审计经验固化成security-audit-skill本质上就是把“人怎么审代码”的作业指导书写成模型能稳定执行的指令包再挂上真正的扫描工具。大模型负责调度、解释和补上下文工具负责确定性检测各干各擅长的事。1.2 Skill到底是什么它和普通Prompt有什么不同这里先说清楚一个概念。在Codex、Claude这类助手生态里Skill并不神秘通常就是一个约定格式的目录核心是SKILL.md外加若干辅助脚本和示例文件。模型会在任务开始前读取这个文件从中获得完整的执行规程。它和普通Prompt的区别在于普通Prompt是一次性的临时写在对话里换一次会话就失效。Skill是可复用的放在项目的.agents/skills/或者用户级配置目录下Agent能自动发现并按需加载。普通Prompt只有“文字指导”Skill可以捆绑脚本和规则文件让模型调工具而不是空想。Skill支持维护和版本管理你可以像维护代码一样去改进它。给Agent一个security-audit-skill就好比给刚入职的安全工程师发一本《安全审计SOP手册》里面写着先做什么、后做什么、遇到什么情况调用哪个工具、报告必须怎么写。模型拿着这份手册去工作产出质量自然比“临场发挥”高得多。1.3 适用对象与典型场景这个东西适合谁用我列几个在我工作中真实出现的场景个人开发者或小团队希望在PR合并前让AI助手自动检查敏感信息泄露和明显的注入点而不想搭一整套重量级安全平台。安全工程师想把自己沉淀的检测规则快速变成团队可复用的流程减少重复解释工作。AI应用工程师正在研究Agent Skill机制需要一个完整的参考实现作为学习样例。想给私有仓库做例行巡检的团队希望每晚自动跑一次基础安全扫描生成报告供第二天排查。这个项目的定位不是替代商业级安全产品而是把“AI代码助手的审计能力”标准化。它解决的核心问题是让同一个模型、同一个流程在不同项目里输出稳定可用的审计结果。2. Skill设计思路先让Agent“知道怎么审”再动手2.1 拆解安全审计的底层能力写Skill之前我没有急着写代码而是先把“安全审计”拆成了几个可以独立执行的能力项。这个步骤非常关键它可以避免把SKILL.md写成一团浆糊。参考我平时人工做审计的方法拆成了四层能力层要发现什么典型工具输出重点是啥敏感信息层硬编码密钥、Token、数据库口令、私钥gitleaks、trufflehog、正则规则文件路径、行号、密钥类型依赖风险层直接和传递依赖的已知漏洞npm audit、pip-audit、osv-scanner漏洞编号、严重级别、修复版本代码缺陷层SQL注入、命令注入、不安全反序列化、路径穿越semgrep、CodeQL、自定义规则缺陷类型、触发位置、调用链配置与权限层过度开放权限、危险CRON、错误security group配置semgrep、checkov、云厂商策略工具配置项、责任方、修复建议拆完之后我就能明确告诉模型Agent负责调用这些工具、解析输出、结合代码上下文判断是否为真实风险工具负责精确匹配避免模型靠记忆瞎编漏洞。这个分工也解决了很多人担心的“模型幻觉”问题——凡是涉及精确扫描的部分都让工具先出结果模型只做标记和解释。2.2 把人工经验转成可执行步骤拆完能力层之后我把人工审计的顺序也固化下来。为什么顺序很重要因为有些步骤之间存在依赖关系。比如我先跑敏感信息扫描再看依赖漏洞最后看代码缺陷。一旦发现硬编码密钥我就知道这个项目可能存在“配置管理不规范”的问题在最后输出报告时会更关注整体风险反过来如果先看代码缺陷很容易陷进某一段业务逻辑忽略全局风险。我的执行顺序是先收集项目基础信息包括语言、框架、包管理器、目录结构。执行敏感信息扫描快速定位高风险泄漏。执行依赖漏洞扫描区分生产依赖和开发依赖。执行代码缺陷扫描按语言和框架选择规则集。检查敏感配置文件、权限和部署配置。汇总所有发现输出按严重级别排序的报告。把这套顺序写进SKILL.md之后模型在每次执行时都会按照这个节奏推进而不是想一出是一出。2.3 为什么选择“指令包外部工具”而不是纯模型判断方案设计过程中我也考虑过“完全靠大模型知识做审计”的方案就是不让模型调用任何扫描器纯粹通过阅读代码找出问题。这个方案看起来部署简单但实测不靠谱。模型对常见漏洞模式的识别能力不错但它无法精确计算依赖版本号对应的漏洞编号也容易漏掉藏在长文件第300行的硬编码密钥。纯靠模型判断还有一个问题它给出的“位置”“行号”偶尔是错的这种报告拿到开发那里信任度会迅速归零。所以我最终选定了“指令包外部工具”的混合架构确定性高的事情交给gitleaks、semgrep这类工具完成。模型负责理解工具输出、筛选误报、补充调用链分析、生成修复建议。规则匹配结果是证据模型解释是辅助。这样做的成本是需要在环境里预装工具并且写一些胶水脚本但换来的可靠性远远大于成本。3. 核心实现从SKILL.md到可跑通的最小版本3.1 SKILL.mdAgent的作业指导书整个Skill的核心文件是SKILL.md。我把它放在项目里的.agents/skills/security-audit/SKILL.md。Codex、Claude等工具在扫描项目时会自动识别这类结构。下面是一个精简但能跑通的版本--- name: security-audit description: 对代码仓库执行多维度安全审计包括敏感信息、依赖漏洞、代码缺陷和配置风险检查。适用于代码审查、CI流程和上线前巡检。 --- # security-audit 你是一名安全审计工程师。请按照以下步骤对仓库执行审计不要跳过任何一步。 ## 输入 - 目标目录默认是当前工作目录 - 需要审计的范围可以通过用户指定例如“只审计src目录” ## 执行步骤 1. 收集项目信息 - 识别语言和框架读取 package.json、requirements.txt、go.mod 等依赖清单。 - 如果存在多个子项目列出子项目清单并逐个覆盖。 2. 检查敏感信息 - 在项目根目录执行 gitleaks detect --source . --no-banner --redact。 - 同时运行配套脚本中的正则扫描检测私有IP、AK/SK形态的字段。 - 输出时记录文件路径、行号和匹配到的密钥类型严禁输出完整密钥值。 3. 检查依赖漏洞 - 根据依赖清单类型调用对应扫描器 - Node.jsnpm audit --json - Pythonpip-audit - Gogovulncheck ./... - 只保留 severity 为 high 或 critical 的结果并列出修复版本。 4. 检查代码缺陷 - 运行 semgrep scan --config auto --json -o semgrep_result.json . - 重点分析注入、认证缺失、路径穿越、反序列化等规则。 - 对每一条结果给出是否可能被利用的简要判断。 5. 检查配置与权限 - 查找 Dockerfile、docker-compose.yml、Kubernetes YAML 中是否包含明文环境变量、危险权限、latest镜像标签。 - 检查 .env 是否被提交到仓库。 6. 输出审计报告 - 按严重级别排序输出 markdown 表格或 JSON。 - 每条记录必须包含问题描述、文件路径、触发位置、证据、修复建议。 - 如果没有发现问题明确说明“未发现明显风险”不要编造发现。这份SKILL.md大概有40多行它给模型划定了清晰的边界。我特意强调了两点一是“严禁输出完整密钥值”避免审计报告本身成为泄露源二是“没有发现就别编造”这是安全领域的大忌。3.2 配套脚本把工具调用封装成统一入口SKILL.md可以指导模型但模型在执行时如果自己拼命令很容易出错。我写了一个Python脚本作为统一入口把敏感信息扫描、依赖扫描和代码缺陷扫描都封装起来模型只需要记住一个命令python scripts/audit.py --source . --output report.json。脚本核心逻辑如下import subprocess import json import sys import os def run_gitleaks(source_dir): result subprocess.run( [gitleaks, detect, --source, source_dir, --no-banner, --redact, --report-format, json, --report-path, gitleaks.json], capture_outputTrue, textTrue ) if os.path.exists(gitleaks.json): with open(gitleaks.json, r, encodingutf-8) as fp: return json.load(fp) return [] def run_semgrep(source_dir): result subprocess.run( [semgrep, scan, --config, auto, --json, -o, semgrep_result.json, source_dir], capture_outputTrue, textTrue ) if os.path.exists(semgrep_result.json): with open(semgrep_result.json, r, encodingutf-8) as fp: return json.load(fp) return {results: []} def summarize(raw): items [] for leak in raw.get(Leaks, []): items.append({ category: secret, rule: leak.get(RuleID), file: leak.get(File), line: leak.get(StartLine), message: 检测到疑似敏感信息已脱敏, severity: high, }) return items if __name__ __main__: source sys.argv[1] if len(sys.argv) 1 else . output sys.argv[2] if len(sys.argv) 2 else report.json leaks run_gitleaks(source) semgrep_data run_semgrep(source) report { secrets: summarize(leaks), code_issues: semgrep_data.get(results, []), } with open(output, w, encodingutf-8) as fp: json.dump(report, fp, ensure_asciiFalse, indent2) print(json.dumps(report, ensure_asciiFalse, indent2))注意脚本里的两个设计点所有外部命令都指定了输出文件避免直接解析stdout时因为编码或格式问题翻车。gitleaks使用了--redact参数报告里只保留脱敏后的信息真实密钥不会出现在日志里。在实际项目中我会把这个脚本再扩展一层支持--skip-dep和--severity-filter之类参数。这样Agent可以根据用户需求减少扫描范围避免每次审计都要等全部工具跑完。3.3 自定义Semgrep规则让模型和工具用同一种语言说话工具自带的规则库覆盖面很广但企业项目往往有自己特有的坑。比如团队经常误用某个自研加密函数或者经常在日志里打印敏感字段这些用通用规则检测不到。所以我为security-audit-skill设计了一个自定义Semgrep规则目录模型在做代码缺陷检查时会优先加载这些规则。一个简单的检测“print敏感字段”的规则示例rules: - id: log-sensitive-data patterns: - pattern-either: - pattern: print($SECRET) - pattern: logger.info($SECRET) metavariable-regex: metavariable: $SECRET regex: (?i)(password|token|secret|api[_-]?key) message: 疑似在日志或输出中打印敏感信息$SECRET languages: - python - javascript - go severity: WARNING这个规则的价值在于它把团队的编码规范也变成了可执行检查项。写好之后放在Skill的rules/目录下模型执行Semgrep时用--config rules/指定即可。我建议每个团队都做这一步。通用规则本质上来自“行业的共性教训”但你们项目的特殊性只有你们自己最清楚。把特殊性沉淀成规则才是安全审计技能最有价值的部分。3.4 与Codex、Claude等Agent的接入方式Skill写好后接入方式根据代理工具不同略有差异。以我常用的两种为例Codex把整个目录放到项目的.agents/skills/security-audit/下面或者放到用户级目录例如~/.codex/skills/security-audit/。这样在任何项目里都能自动识别到。Claude Code等工具通常也是读取项目下的.claude/skills/或通过插件机制导入。我会同时把Skill目录复制到项目级确保团队clone后能直接使用。接入之后要验证Agent是否真的会加载这个Skill。我最快的验证方法是在项目里输入“帮我审计当前目录”然后看Agent是否主动执行了SKILL.md里的步骤而不是凭空回答。如果Agent没有加载优先检查目录名、SKILL.md文件名是否准确以及是否放进了Agent扫描的顶层目录。很多工具对Skill目录有固定的前缀约定不能随意改名。4. 实操过程在真实项目里跑一次完整审计4.1 前置环境准备我这里以Linux/macOS环境为例所有工具都需要提前安装。依赖扫描工具按项目语言来选我把常见的都列出来工具安装方式用途gitleaksbrew install gitleaks或go install github.com/gitleaks/gitleaks/v8latest敏感信息扫描semgreppip install semgrep静态代码缺陷扫描npmNode环境自带npm依赖漏洞检查pip-auditpip install pip-auditPython依赖漏洞检查govulncheckgo install golang.org/x/vuln/cmd/govulnchecklatestGo依赖漏洞检查安装完成后先用一条命令验证工具能正常调用gitleaks version semgrep --version我踩过的坑是gitleaks在某些系统上默认不进入PATH导致Agent执行时找不到命令。解决办法是在SKILL.md里写上工具的绝对路径或者把安装目录加入PATH环境变量。Agent的Shell环境和你手动终端的环境未必一致这一点特别容易被忽略。4.2 执行一次最小审计并解读结果我在一个模拟的Node.js项目上跑了一次审计项目结构大致如下demo-app/ ├── package.json ├── src/ │ ├── server.js │ ├── db.js │ └── utils/ │ └── encrypt.js ├── .env └── README.md启动Skill后Agent首先读取package.json识别出这是一个Express应用然后依次执行敏感信息、依赖、代码缺陷扫描。我这里简化一下最终的输出报告{ summary: { total: 3, high: 1, medium: 2 }, findings: [ { type: secret, severity: high, file: .env, message: 检测到疑似数据库口令文件已被提交到仓库, suggestion: 将密钥迁移到密钥管理服务删除仓库中的.env并轮换该口令 }, { type: dependency, severity: medium, file: package.json, message: axios 1.2.0 存在已知的的高危漏洞建议升级到1.6.8以上, suggestion: 运行 npm install axios^1.6.8 }, { type: code_issue, severity: medium, file: src/db.js, message: 拼接SQL存在注入风险使用参数化查询, suggestion: 改用 prepared statement } ] }Agent拿到这些工具输出后会做一次“人力审查”。比如对于.env被提交这个问题它会去git log里确认这个文件的历史判断是否真的曾被推到远端对于SQL注入它会沿着调用链去查输入是不是用户可控。这一步正是纯工具做不到的也是security-audit-skill相比普通扫描器的真正优势。4.3 审计结果接入CI/CD项目里的安全审计不能只在本地偶尔跑一次必须进CI。我把Skill封装成一个GitHub Actions工作流每次PR都会自动执行。一个可用的配置示例name: security-audit on: push: branches: [ main ] pull_request: jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Python uses: actions/setup-pythonv5 with: python-version: 3.12 - name: Install security tools run: | pip install semgrep go install github.com/gitleaks/gitleaks/v8latest export PATH$PATH:$(go env GOPATH)/bin - name: Run security audit skill run: | python .agents/skills/security-audit/scripts/audit.py \ --source . \ --output audit-report.json - name: Upload report artifact uses: actions/upload-artifactv4 with: name: security-audit-report path: audit-report.json如果只是生成报告团队不一定真的会看。我通常再加一个步骤如果审计结果中存在high级别问题就让CI失败并阻止合并。这一步的力度取决于团队文化有些团队觉得太严格推进不下去那就先把critical设为阻塞级别也是可以的。4.4 从报告到修复Agent如何给出可操作建议纯粹的报告只是第一步真正有价值的是修复。Skill里我明确要求Agent在输出每个问题时必须附带一个“最小修复示例”。例如如果是硬编码密钥给出改用环境变量的前后对比。如果是SQL注入给出参数化查询的改写方式。如果是依赖漏洞给出具体的升级命令。这个要求让模型从“报问题的人”变成“能解决问题的人”实际使用中开发者的接受度一下子高了很多。之前有人抱怨安全工具只会报一堆漏洞现在Agent会顺手把补丁示例贴出来开发只需要review后合入即可。5. 常见问题与排查技巧实录5.1 Skill明明放好了Agent却没有调用这个问题我排查了无数次常见的三个原因第一目录结构不对。多数Agent要求Skill目录名和SKILL.md文件名严格匹配比如security-audit/SKILL.md如果你写成了security_audit.md或者目录嵌套多了一层可能就无法识别。第二Agent没有重新加载。有些工具启动时会缓存Skill索引新增Skill后需要重启会话或重新加载项目。第三权限不足。Agent可能没有读取Skill目录的权限尤其是放在/Users/xxx/.codex/skills/这类目录时需要检查属主和权限位。我的排查模板是先手动用cat确认文件能被读取再用Agent的调试模式查看它加载了哪些Skill最后看日志里是否有“skill not found”之类的提示。5.2 扫描结果太多误报率高得没法看误报是所有静态分析工具的通病。你的Skill如果同时加载了gitleaks和semgrep第一次跑出来的报告可能有一百多条“疑似问题”但真正值得处理的不到10条。我的处理思路不是删除规则而是分级处理把severityWARNING的信息在报告中折叠只展示摘要。在Skill的步骤里明确告诉模型先过滤掉测试文件、mock目录、自动生成代码。对高频误报规则直接在Semgrep配置里增加paths排除。对确认误报的规则在审计脚本里维护一个白名单例如某些路径允许包含特定格式测试字符串。不要轻易禁用规则因为禁用规则会同时禁用掉它本来能发现的问题。更好的办法是让Agent在报告里自动分级哪些可以自动修复哪些需要人工确认。5.3 Agent扫描时“偷懒”给了个空报告这是我最担心的现象Agent绕过了所有工具直接说“未发现明显风险”。这种情况在模型上下文过长或工具执行超时时容易发生模型为了尽快完成任务给出了一个看似合理但实际没做事的回答。为了堵住这个口子我在SKILL.md里做了两条硬约束必须先生成工具调用记录再输出报告报告里的每条结论必须引用具体工具输出路径。如果某一类检查没有执行必须在报告里写明“未执行”和原因而不是用“未发现风险”来替代。实际操作中如果Agent试图给空报告我会检查是不是哪个工具运行超时了。给脚本加上合理的超时处理让Agent知道运行失败后应该重试或报告错误而不是默默跳过。5.4 Skill在大型仓库里运行太慢大型Monorepo里跑一次完整审计可能要十几分钟非常影响体验。我的优化方案是按层拆分执行先只跑敏感信息扫描这个最耗时小于30秒。再按改动文件范围跑增量代码扫描使用semgrep scan --baseline-commit。依赖漏洞检查可以放到定时任务里每晚执行而不是每次PR都跑全量。另外一个技巧是把Skill拆成两个子Skillsecurity-audit-quick和security-audit-full。快速版用于日常开发全量版用于上线前或夜间巡检。模型会根据用户指令自动选择合适的版本体验会好很多。5.5 Skill写得很完整但Agent就是不按步骤走大模型对长指令的执行并不总是严格遵循尤其当SKILL.md超过300行时模型的注意力可能被分散。我的经验是核心步骤控制在6步以内每步描述不超过5行。把详细规则放到独立文件中SKILL.md里只写“按rules/sensitive-patterns.txt执行”。在步骤后面增加“完成检查”的描述例如“如果上一步失败不要继续执行后续步骤”。从实测来看一个精简的SKILL.md比冗长的文档执行效果好得多。模型只需要记住主干细节放在外部规则文件里需要时再读。6. 从Skill到团队资产一点实际经验回头看security-audit-skill真正解决的不是“让AI更聪明”而是“让AI按标准干活”。它把过去只能靠人传人、靠开会宣讲的安全规范变成了一个可安装、可更新、可度量效果的工程产物。我现在的做法是每月更新一次规则库把新发现的问题模式补充进去相当于让这个Skill随着团队代码一起演进。如果你只是一个人用那直接在本地放一个目录就行。但如果你想让整个团队都用起来我建议做到两点把Skill目录纳入Git管理保证所有人拿到的是同一版本为规则和报告格式建立一份简单的更新日志免得团队看到一份格式和上周完全不一样的报告。最后分享一个个人感受Skill设计得好不好有一个判断标准——你把它交给另一个团队的人他不需要你额外解释照着SKILL.md就能跑出可用的结果。如果还需要你从头讲一遍流程那说明指令包还不够完整。多做几轮“把Skill交给别人测试”的循环你会发现自己做出来的东西越来越像一个合格的安全审计同事而不是一个“偶尔给点建议的聊天机器人”。