从零构建security-audit-skill：用AI编程助手实现代码安全审计标准化

最近我在折腾AI编程工具的时候遇到一个很有意思的技能包security-audit-skill。这东西说白了就是把代码安全审计的整套工作流从“凭经验人肉翻代码”变成“让AI助手按固定套路帮你审”而且这个“套路”可以被标准化、被复用甚至能被整个团队共享。很多人第一次听到“Skill”这个词脑子里冒出来的可能是游戏里的技能树或者是PPT里的某种动画效果。但在AI编程助手的语境里Skill其实就是一份“怎么干活”的行为指南。它把完成某类特定任务所需的步骤、规则、脚本、工具调用方式都打包成一个文件夹让AI助手在遇到对应场景时能按图索骥地执行。security-audit-skill就是专门干代码安全审计这一件事的。这篇内容我想从一个实际动手做过的角度把这东西的里里外外都拆一遍它解决什么问题、内部结构长什么样、怎么构建、怎么接入Claude Code、Codex、OpenCode这些主流工具以及我在真实项目里跑它时踩过哪些坑。不管你是安全工程师、后端研发还是刚入行想学代码审计的测试同学这篇都能给你一个能直接抄作业的参考。1. 先搞明白Skill到底是什么为什么安全审计这件事适合做成Skill1.1 从“会聊天的助手”到“会干活的打工人”要理解Skill得先理解AI助手现在的处境。你直接跟Claude或者Codex说“帮我审计一下这个项目的安全”它确实能给你回一大段分析但你会发现它每次给的答案都不太一样有时候先看依赖有时候先看配置有时候干脆抓不住重点。原因很简单通用大模型没经过特定任务的动作拆解训练它只是“会聊天”不是“会干活”。Skill干的事就是给AI助手补上“干活”这一课。它把某类任务从头到尾怎么做拆成一步一步的操作指引写进一个叫SKILL.md的文件里再配上需要的脚本、规则、参考文档。AI助手在工作时会先读这份指引按照里面定义的顺序、标准和产出格式去执行。我经常用一个类比来解释Skill和普通聊天的区别普通聊天是“你问一句它答一句”Skill是“你丢一个任务进去它自动按照SOP走完整条流水线”。拿安全审计来说普通人肉审计的流程大概是拉代码到本地、看依赖清单、查已知CVE、扫敏感信息、检查鉴权逻辑、看配置项是否安全、最后出一份审计报告。这套流程极其固定极其适合被标准化成Skill。1.2 security-audit-skill 到底解决什么问题实话实说代码安全审计这个行当长期面临一个尴尬的局面懂业务的人不一定懂安全懂安全的人又不可能把一个公司所有项目的代码都看一遍。一个稍微像样点的后端项目代码量动辄几万行起步光靠人肉去翻效率低到让人绝望。security-audit-skill解决的就是这个问题。它能做到三件事第一把安全专家的经验固化下来。一个资深安全工程师检查代码时脑子里其实在运行一个“检查清单”这个接口有没有做权限控制、SQL查询是不是用了预编译、上传文件有没有限制类型、日志里有没有打印敏感信息。这些清单完全可以写进Skill的规则文件里。第二让审计动作变得可重复。同一个项目今天审和明天审用Skill审和用专家审只要规则不变结论的稳定性就会比纯靠大模型自由发挥高得多。这跟写单元测试是同一个逻辑用例固定了才能回归对比。第三降低使用门槛。一个刚转行做安全的同学不需要先读三本渗透测试的书才能上手。他只需要把Skill加载进AI助手就能获得一个接近中级安全工程师审稿水平的基础输出。我自己的体会是这类Skill最适配的项目规模是中型以上、有清晰目录结构的代码仓库。单文件脚本那种项目反而没必要用大炮打蚊子规则跑起来都嫌浪费Token。1.3 Skill和Agent的区别以及为什么我选Skill不选Agent在热词列表里反复出现一个问题“skill和agent的区别”。这也是我刚开始接触时特别困惑的地方。我的理解是这样的Agent是一个“自主决策体”它被赋予一个目标后可以自己决定调用哪些工具、执行哪些步骤甚至自己写代码来解决问题。而Skill更像是一本“操作手册”它本身不做决策只是约束AI助手“遇到这类问题就按这个流程走”。用安全审计场景举例Agent版本的审计助手会自己决定“我先用grep找一下敏感字段再调用一个漏洞库的API最后写报告”Skill版本则更像是“AI助手拿到了一个审计SOP文档文档写了第一步扫依赖、第二步查配置、第三步看代码、第四步出报告AI按步骤执行”。那为什么我推荐普通团队从Skill入手因为Agent的不可控性太强了。你很难保证它每一次都走同一个流程也很容易跑偏Skill则不同它的行为边界清晰出问题也好排查。过程可控结果才可预期这在安全审计这种严谨场景里是刚需。2. 安全审计Skill的内部结构拆开看它由哪些零件组成2.1 核心工作流人肉审计怎么做Skill就怎么写我构建security-audit-skill的第一步不是写代码而是把“人肉安全审计”的标准流程画出来流程在心中不搞图表那套。通用流程大概是下面这样摸清项目底细是什么语言、什么框架、用了哪些依赖、有没有锁文件。依赖安全检查依赖版本对照已知CVE漏洞库看有没有带洞上线的情况。敏感信息泄露搜索API Key、数据库连接串、私钥、Token等硬编码。配置安全检查看是否开启了调试模式、跨域配置是否过宽、鉴权中间件是否生效。代码逻辑审计重点关注SQL拼接、命令执行、文件上传、反序列化、越权等经典漏洞点。输出报告按风险等级整理问题列表给出修复建议。这个流程就是Skill骨架。SKILL.md里写的步骤基本就是上面这份清单的细化版本。2.2 一份可用的安全审计Skill由哪些文件构成以我现在常用的一份Skill为例它的目录结构大概是这样的security-audit-skill/ ├── SKILL.md ├── scripts/ │ ├── scan_sensitive.py │ ├── check_dependencies.py │ └── analyze_config.py ├── rules/ │ ├── sensitive_patterns.txt │ ├── java_secure_rules.md │ ├── python_secure_rules.md │ └── frontend_secure_rules.md ├── references/ │ ├── cwe_top25.md │ ├── owasp_cheatsheet.md │ └── fix_examples.md └── assets/ └── report_template.mdSKILL.md是入口相当于这份技能的使用说明书。AI助手拿到任务后先读它确认“这个任务我该按什么流程干”。scripts目录放可执行脚本比如自动搜索高危敏感字段、比对依赖版本与漏洞库等。rules目录是灵魂里面放的是不同语言、不同类型项目的检查规则可以理解成“安全审查判断标准”。references目录放的是参考文档用来让大模型在不确定“某种写法是否属于漏洞”时去查证。assets目录一般放报告模板保证AI输出的审计报告格式统一。2.3 规则文件是真核心安全专家经验都沉淀在这里如果只保留Skill里的一个部分我肯定选rules目录。规则文件的质量直接决定这份Skill是“玩具”还是“生产工具”。拿Java项目举例一个合格的java_secure_rules.md应该覆盖这些点MyBatis/MyBatis-Plus中的${}拼接是否导致SQL注入文件下载接口是否存在路径穿越越权接口有没有做Owner校验反序列化时是否使用了不安全的ObjectInputStream定时任务里是否有危险的命令执行调用拿前端项目举例frontend_secure_rules.md应该关注有没有把敏感接口地址写死在JS代码里本地存储是否存放了Token或用户隐私是否有DOM XSS高风险写法比如直接innerHTML插入用户输入依赖包里是否存在已知漏洞的版本这些规则看起来不多但每一条背后都是真实事故换来的教训。Skill的价值就在这里大模型本身“知道”这些规则但如果没有Skill把它唤醒并让它按优先级逐个检查它就很容易漏掉关键点。3. 动手实操从零构建一版能用的security-audit-skill3.1 先定目录再定边界不要试图一步到位我在写第一版Skill时犯过一个错误想覆盖所有语言、所有框架结果SKILL.md写得像一本百科全书AI助手执行起来反而不知所措。后来我把策略改成了“先精后广”先选择一个最常用、最核心的场景做深跑通了再往外扩展。对一个安全审计Skill来说最先应该覆盖的三个场景是敏感信息扫描、依赖漏洞检查、配置安全检查。这三个场景通用性强、规则明确、产出见效快适合作为第一版的核心功能。代码逻辑审计这种重度依赖上下文的场景可以放到第二版再做。3.2 SKILL.md的写法让AI一眼就知道怎么干SKILL.md本质上是一份给大模型看的“任务协议”。我建议用这样的结构编写# Security Audit Skill ## 技能目标 对指定代码仓库执行安全审计输出符合规范的风险报告。 ## 适用场景 - 新项目上线前的安全评估 - MR/PR 合并前的代码安全检查 - 存量代码安全巡检 - 第三方代码/开源项目引入前的安全评估 ## 执行流程 当用户要求进行安全审计时按以下流程执行 1. 分析项目结构识别语言、框架、包管理器、构建工具 2. 检查依赖安全调用 scripts/check_dependencies.py比对已知漏洞库 3. 扫描敏感信息调用 scripts/scan_sensitive.py检查硬编码密钥 4. 检查配置安全重点覆盖调试开关、跨域配置、认证鉴权配置 5. 审查核心代码依据 rules/ 目录下对应语言的规则逐项检查 6. 生成报告使用 assets/report_template.md 模板输出 ## 输出格式 报告按以下章节组织 - 项目概览 - 风险总览高/中/低三级 - 问题明细含文件路径、行号、风险说明、修复建议 - 修复优先级建议 ## 重要提醒 - 遇到资金交易、用户隐私数据、权限绕过相关逻辑时提高风险等级 - 不确定的漏洞点先到 references/ 目录查证不要直接下结论 - 所有结论基于静态分析需注明“可能存在”避免绝对化表述这份文件写清楚了三件事这个技能是干什么的、接到任务后按什么顺序做、最后产出什么格式的结果。大模型非常依赖这种结构化的指引你把步骤写得越清晰它执行起来就越不跑偏。3.3 用脚本补足大模型的短板扫描敏感信息的正确姿势大模型最大的短板是“不擅长精确匹配”。你让它“找一下代码里有没有API Key”它能给你列出一堆疑似点但准确率感人。这种时候就该脚本上场了。我写了一个很简单的Python脚本用来做第一轮敏感信息粗筛#!/usr/bin/env python3 import os import re import sys SENSITIVE_PATTERNS [ (r(?i)(api[_-]?key|secret|token|password|passwd|pwd)\s*[:]\s*[\][^\]{8,}[\], Hardcoded credential), (r(?i)AKIA[0-9A-Z]{16}, AWS Access Key), (r(?i)sk-[a-zA-Z0-9]{20,}, OpenAI API Key), (r(?i)-----BEGIN (RSA|EC|OPENSSH|DSA) PRIVATE KEY-----, Private Key), (r(?i)mongodb(?:\srv)?://[^\s\], MongoDB Connection String), (r(?i)mysql://[^\s\], MySQL Connection String), (r(?i)redis://[^\s\], Redis Connection String), ] SKIP_DIRS {node_modules, vendor, dist, build, .git, __pycache__, .next} SKIP_EXT {.png, .jpg, .jpeg, .gif, .ico, .pdf, .woff, .woff2, .ttf} def scan_directory(root_path): findings [] for dirpath, dirnames, filenames in os.walk(root_path): dirnames[:] [d for d in dirnames if d not in SKIP_DIRS] for filename in filenames: ext os.path.splitext(filename)[1] if ext in SKIP_EXT: continue file_path os.path.join(dirpath, filename) try: with open(file_path, r, encodingutf-8, errorsignore) as f: for line_no, line in enumerate(f, start1): for pattern, desc in SENSITIVE_PATTERNS: if re.search(pattern, line): findings.append({ file: file_path, line: line_no, desc: desc, content: line.strip()[:200] }) break except Exception: continue return findings if __name__ __main__: if len(sys.argv) 2: print(Usage: python scan_sensitive.py project_path) sys.exit(1) results scan_directory(sys.argv[1]) for item in results: print(f[{item[desc]}] {item[file]}:{item[line]}) print(f {item[content]})这个脚本的思路很简单但很实用。它不依赖大模型直接用正则做第一轮粗筛把明显的问题全部捞出来。AI助手拿到脚本输出后只需要做二次研判判断哪些是误报、哪些是真问题效率提升非常多。3.4 依赖漏洞检查不能只靠大模型“背”CVE依赖漏洞这块核心难点在于漏洞库是动态更新的大模型的知识截止日期永远赶不上最新CVE。所以Skill里不能只靠大模型自己的知识得让它学会“查”。我建议把依赖检查拆成两层如果项目里有lock文件package-lock.json、pnpm-lock.yaml、poetry.lock、pom.xml等让AI助手先执行npm audit、pip-audit、mvn org.owasp:dependency-check-maven:check这类工具命令拿到真实的漏洞报告如果没有lock文件再退而求其次让AI助手根据依赖名和版本号去查公开漏洞库接口。# 前端项目 npm audit --json # Python 项目 pip-audit --format json --path . # Java 项目 mvn org.owasp:dependency-check-maven:check -DformatJSON把这一步放到Skill流程里等于让AI助手有了实时更新漏洞库的能力。这是单靠prompt提示词做不到的。3.5 接入Claude Code、Codex、OpenCode的通用姿势关于Skill怎么“安装”到不同的AI工具里网上讨论很多。我实测下来主流工具的做法都类似把Skill文件夹放到项目根目录的.claude/skills/Claude Code、.codex/skills/Codex、.opencode/skill/OpenCode等指定位置然后在对话中触发对应关键词工具就会自动加载。很多时候用户会发现“我明明装了Skill但AI好像没反应”大概率是触发方式不对。一部分工具要求你明确说出Skill的名字比如“使用security-audit-skill对这个项目做安全审计”另一部分工具则支持自动触发识别到“安全审计”“代码安全”这些语义就会自动加载。稳妥起见初期建议都在指令里显式指定Skill名。如果你用的是Claude Code在项目根目录配置CLAUDE.md把“优先加载security-audit-skill”写进去也是一个很管用的办法。这相当于在项目级别预设了默认技能每次会话会自动带入。4. 真实场景实战用security-audit-skill跑一个项目全流程4.1 场景一新项目上线前的快速安全体检我拿一个实际项目来演示流程。那是一个基于Spring Boot的电商后端服务加上一个Vue3的管理前端。上线前我把security-audit-skill接到了Claude Code里然后输入指令使用security-audit-skill对当前项目执行安全审计。Skill的第一反应不是直接扫描而是先读项目结构。它自动识别出了后端是Maven工程、前端是npm工程于是针对性地加载了java_secure_rules.md和frontend_secure_rules.md两份规则文件。这一步很关键不同技术栈的检查项差异很大规则选错了报告质量就会打折。接着它执行了依赖检查脚本。前端这边npm audit跑出来3个high级别漏洞都是开发依赖里的构建工具版本太旧后端这边问题更严重一点spring-boot-starter-web的版本存在一个已知的反序列化漏洞。这些信息AI助手直接引用工具输出没有硬编可信度更高。然后进入敏感信息扫描环节。脚本在配置目录里发现了一个测试环境的数据库连接串密码是明文写在application-dev.yml里的。这个虽然不是线上配置但按照“测试环境密钥也可能被滥用”的原则还是被标记为中风险。最后是代码逻辑审查。AI助手按照Java安全规则逐项排查在一个订单查询接口里发现了一个典型的越权问题接口只从请求参数里读取userId没有从当前登录会话中获取用户身份这意味着任何登录用户都可以传别人的ID查订单。这个发现给了个high风险评分修复建议是改成从SecurityContext中获取当前用户信息。4.2 场景二把Skill接进代码审查流程除了拿它做“上线前体检”我还把security-audit-skill用在了日常的代码审查上。做法是把它跟CI流程做了结合确切说是把它的脚本部分抽了出来做成一个独立的Git Hook。每次有commit或push时scan_sensitive.py自动跑一遍一旦发现硬编码密钥或者私钥直接拦截提交。这个效果立竿见影上线两周就拦下了3次开发把测试密钥误提交的情况。以前这种事只能靠代码审查人眼发现现在机器自动就帮你挡住了。这块的实际感觉是Skill里能独立出来的判断逻辑就应该尽量独立成脚本而不是让大模型每次都去“重新思考”一遍。判断逻辑越下沉、越自动化整个流程就越稳、越快、越省Token。让大模型只做它擅长的事——理解和总结别让它干精确匹配的活儿。4.3 场景三安全审计经验的团队复用Skill还有个容易被忽视的价值它是团队知识沉淀的载体。我们团队以前的安全审查经验散落在几个老员工的备忘录和聊天记录里。新人来了只能靠口口相传效率低还容易漏。现在我把security-audit-skill整理好放进团队的代码模板仓新项目初始化时自动带一套新人做安全自查时直接用AI助手加载Skill就行。这个实践做完之后团队里做代码Review的节奏明显变了。以前每个MR都要安全老手人工过一遍现在先用Skill跑基础检查老手只需要看Skill报告的产出和剩余疑点精力可以集中在更复杂的业务逻辑审查上。5. 使用中的高频问题与避坑经验5.1 为什么我加载了SkillAI却像没看见这是最常见的翻车点。用下来原因基本逃不过下面三种一是路径放错了。不同工具要求的Skill目录不一样我见过有人把文件夹放到~/.claude/skills/下然后在Codex里加载当然找不到。正确做法是先确认当前工具读的是哪个目录不确定就看官方文档或者直接问工具本身。二是SKILL.md的格式不规范。Skill不是“文件夹放对就行了”SKILL.md需要有清晰的frontmattername、description和结构化的正文。AI助手通过description字段判断“什么时候该用这个Skill”如果这个字段写得太抽象它就识别不出来。三是触发方式错了。有的工具支持自动触发有的必须显式点名。最稳的办法就是在指令里带上Skill的名字比如“使用security-audit-skill检查当前项目的安全问题”命中率几乎100%。5.2 误报率太高、报告水得没法看怎么办Skill刚建起来的时候误报率高是很正常的。我第一版的敏感信息扫描脚本把测试环境里的各种mock数据都当成了真密钥报告里一半都是无效信息。优化误报要靠两条腿走路一方面把明确的误报样本写进脚本的排除逻辑比如加一个忽略清单文件.auditignore让分析师可以手动标记“这些路径不扫”另一方面把研判工作交给大模型做二次过滤脚本只负责抓“候选”AI负责判断“是不是真问题”。我现在的流程是脚本粗筛出候选列表AI助手逐条判断并给出理由只有AI认为“高度疑似”的才进最终报告。这样既能保证覆盖度又能把报告精简到可用的程度。5.3 Skill不是万能药它对哪些安全场景无能为力用久了你会发现Skill依然有它的边界。基于静态分析的Skill对下面几类问题基本无能为力逻辑漏洞比如优惠券叠加使用的金额计算错误、并发场景下的条件竞争这些必须结合业务理解才能发现。需要运行时才能暴露的问题比如内存溢出、SSRF的实际可用性静态扫描看不到运行时状态。第三方组件深层次漏洞工具能告诉你某个依赖版本有CVE但它无法判断你的代码是否真的走到了受影响的分支。所以我对Skill的定位是“安全审计的第一道筛子”不是“安全审计的终点”。它帮你把80%的机械性检查干掉但剩下那20%需要业务理解和系统视角的深水区还是得靠人。5.4 从Skill扩展到更多场景它只是一种内容形态最后聊一个延伸话题。很多人看到security-audit-skill以为它只能用于代码安全。但理解了Skill的本质之后你会发现它其实就是一种“把某种能力打包给AI助手”的格式什么场景都能用。前端有vue-best-practices skill专门让AI按Vue的工程规范写代码测试有软件测试skill让AI按用例设计规范输出测试方案就连做PPT、写会议纪要这种办公场景也有对应的Skill。它们的原理和我们说的security-audit-skill一模一样一份SKILL.md定义流程若干规则文件定义标准若干脚本处理机械性工作。想自己写Skill的人直接以security-audit-skill为模板把“安全审计的检查规则”换成“你自己业务场景的执行标准”换一下rules目录的内容再换一下输出模板一个全新的Skill就诞生了。这算是Skill最有意思的地方它把人类专家的做事情的方法论变成了一种可以被AI复用、被团队复制、被社区传播的资产。