做了一周 AI Agent 安全审计我把整套流程沉淀成了一个 Skill最近这阵子AIGC 圈子里Skill这个词被反复提起。从 Claude 的 Skill Store 到 Codex 的 skill 插件再到 OpenCode、Spring AI 这类框架里的 skill 机制本质上都是同一件事把某个领域的专业流程、检查清单、判断规则固化下来让 Agent 在需要时能像调用工具一样调用这套方法论。我平时做安全审计和代码检测比较多顺手把过去一周处理过的几个项目审查流程整理了一下封装成了一个 security-audit-skill这里把完整的设计思路和实操过程分享出来。先明确一下这个 skill 到底解决什么问题。过去让 AI 做代码安全审计通常是在对话里甩一句帮我看一下这段代码有没有漏洞。大模型确实能看出一些问题但结果往往零散、深浅不一而且经常漏掉跨文件调用、权限模型、配置项这类隐藏风险。security-audit-skill 的核心价值在于把审计这件事从随缘提问变成有标准流程的专业服务——它定义了一套完整的审计框架让 Agent 按阶段执行每一步需要检查哪些点、输出什么样的报告、用什么样的评分标准全部都有明确约束。实测下来同一段代码在加了这层 skill 约束之后发现的潜在风险点数量和质量都有明显提升。这套流程适用于几类场景代码上线前的安全检查、第三方依赖和开源项目引入前的风险评估、甲方安全团队做外包代码验收以及给 AI 编程助手叠加安全能力。如果你正在用 Codex、Claude Code、OpenCode 之类的工具写代码又对安全问题有要求那这篇文章可以直接照着落地。1. 内容整体设计与思路拆解1.1 为什么安全审计必须沉淀成 Skill 而不是靠提示词很多人的第一反应是安全审计不就是写一段详细的 system prompt 吗我一开始也这么想但实际跑过之后发现差异很大。核心原因在于安全审计是一个强流程、强状态依赖的任务。一个标准的企业级安全审计至少包含信息收集、威胁建模、静态分析、动态验证、人工复核、报告汇总六个阶段。用普通提示词对话时Agent 很容易在前面的阶段还没做完的情况下就直接跳到结论或者对某些阶段的理解产生偏差。而 Skill 提供的是一个结构化的执行框架它把审计过程拆成一个个可执行、可验证的步骤Agent 会按照定义好的顺序和规则推进而不是靠自由发挥。更关键的一点Skill 可以绑定特定的工作流和执行工具。比如审计 Python 代码时我不希望 Agent 只是肉眼读代码我希望它能调用 bandit、semgrep 这些静态扫描工具把真实扫描结果作为分析依据。这在纯提示词场景下很难稳定实现但通过 Skill 可以明确指定先执行哪个工具、拿到什么格式的输出、再基于这个输出做哪些判断形成一套可复现的自动化流水线。另外安全审计本身是一个高专业门槛的领域对 CWE 分类、CVSS 评分、常见漏洞模式的理解深度决定了审计结果的质量。把这些专业判断规则固化进 Skill实际上是把一个资深安全工程师的分析方法论复制给了 Agent让它能稳定输出接近专家水准的结论而不是每次凭模型当时的心情去推断。1.2 Skill 的基本运行机制先说清楚 Skill 在常见 Agent 平台里是怎么工作的。以当前主流的实现来看Skill 通常是一个包含指令文件的目录里面通过 Markdown 格式定义了这个技能的名称、适用场景、执行步骤和输出规范。当 Agent 接收到用户请求时它会先做一轮意图匹配——根据当前任务描述在已安装的 Skill 列表中寻找最匹配的那个匹配成功后就加载对应的 Skill 说明按照里面定义的规则来执行任务。这个机制和插件Plugin有本质区别。插件往往是一段封装好的代码提供特定功能接口。而 Skill 更像是一份方法论说明书外加执行编排规则它告诉 Agent 什么时候该做什么而不是替 Agent 做完某件事。打个比方插件像是一台预制好的冲床一按就出模具Skill 则是一份加工工艺文件告诉操作员用哪台机器、什么转速、按什么顺序加工中间还可以根据实际情况调整参数。理解这个差异之后设计 Skill 的重点就清晰了——重点不是写代码而是把审计知识、判断标准和执行流程组织好。让 Agent 在执行过程中能够随时查阅和遵循这才是真正的核心工作。1.3 我对 security-audit-skill 的定位思考在设计这个 skill 时我给它的定位非常明确不是替代人工安全专家而是做一个高水平的自动化审计预检工具把重复性高、规则明确的检查项全部自动化让安全人员把精力集中在需要深度分析的逻辑漏洞和业务风险上。这个定位决定了 skill 的边界。它应该覆盖 SQL 注入、XSS、命令注入、文件上传绕过、敏感信息泄露这些标准漏洞模式也应该覆盖硬编码密钥、不安全依赖版本、弱加密算法这类配置性风险但对于需要理解复杂业务逻辑才能判断的风险——比如越权漏洞、支付逻辑绕过这类它更适合给出疑似风险的提示然后由人工确认。这样一来无论是直接使用这个 skill 做全量扫描还是把它作为大模型编程助手的补充审计能力都能获得清晰的收益。用户不会对它抱有不切实际的期望Agent 的输出质量也更容易控制。2. 核心细节解析与实操要点2.1 审计流程的分层设计整个 skill 的核心是一个分层审计模型我把审计过程拆成五个层级从外到内、从静态到动态逐层深入。第一层是配置与依赖审计主要检查项目的部署配置文件、依赖清单、环境变量重点关注有没有硬编码密钥、依赖版本是否存在已知高危漏洞、是否有暴露管理端口的错误配置。这一层最容易用自动化工具完成通常能快速发现一批中低危问题。第二层是入口与鉴权审计重点检查 API 路由、过滤器、中间件逻辑。这一层要看的内容包括接口是否做了身份校验、JWT 的生成与解析逻辑是否安全、关键操作是否有二次授权、权限模型是否存在越权可能。这一层非常考验 Agent 对代码调用链的理解如果只看单个文件很容易漏必须结合整个项目的路由注册逻辑一起看。第三层是输入输出审计也就是经典的注入和 XSS 检查。SQL 拼接、命令拼接、模板渲染、反序列化入口这些位置全都需要重点排查。Agent 在这一层要做的不仅是找到可疑写法还要判断数据流的走向——用户可控的输入到底能不能到达危险函数中间有没有经过过滤和转义。第四层是业务逻辑审计这是最难自动化的一层。我通常会要求 Agent 重点标记出那些疑似逻辑缺陷的位置比如缺少细粒度权限校验的接口、可以越权操作他人数据的查询、未做并发控制导致重复扣款的代码附上上下文信息供人工复核。第五层是输出与报告层把前面四层发现的所有问题汇总成结构化报告。报告必须包括风险等级、问题位置、漏洞类型CWE 编号、问题描述、修复建议五要素等级评分统一参考 CVSS 3.1 标准。这样不管是开发人员还是安全团队拿到报告都能直接进入修复流程。2.2 输出报告的结构化设计设计报告格式时我参考了行业内大多数扫描工具的统一风格最终定下的模板包含以下几部分审计概览项目名称、语言/框架、审计范围、整体风险评分漏洞明细表每个漏洞一行包含风险等级严重/高危/中危/低危、CWE 编号、文件位置文件行号、简要描述详细分析对每个高危及以上漏洞做详细展开包括漏洞代码片段、攻击路径复现步骤、影响范围修复建议针对每个问题给出具体可操作的修复方案指明应该改哪个文件、用什么方式改审计盲区声明明确列出本次审计未能覆盖或需要人工确认的范围结构化的好处非常明显Agent 的输出不再是我觉得这里有问题这样模棱两可的描述而是直接生成一份可以直接被追踪系统消费的规范报告。我试过把生成的报告直接导入项目的 issue 管理工具基本不需要额外的格式转换。2.3 工具链选型安全审计要做得好不能只靠 Agent 读代码必须有静态扫描工具配合。我在 skill 里预设了几个常用工具根据项目语言动态选择项目类型推荐工具用途PythonBandit、Semgrep基础漏洞扫描、规则自定义匹配JavaScript/TypeScriptESLint security plugin、Semgrep代码规范检查、不安全模式识别JavaSpotBugs、FindSecBugs字节码级安全分析GogosecGo 语言安全扫描所有语言gitleaks硬编码密钥与敏感信息检测通用OWASP Dependency-Check依赖组件漏洞扫描Skill 在运行时需要先探测项目语言然后自动选择对应的工具链组合。这个设计能显著提高审计效率避免用 Python 的安全规则去扫描 Java 项目产生大量无效告警。这里需要特别说一句工具扫描结果只是中间产物Agent 的核心价值在于对扫描结果的二次解读。工具往往会有大量的误报Agent 需要结合代码上下文来判断这个告警是真正可利用的漏洞还是误报。这也是 skill 不同于单纯脚本的地方——它不仅有扫描环节还有分析判断环节。3. 实操过程与核心环节实现3.1 skill 目录结构的设计下面直接给出我这个 security-audit-skill 的目录骨架你可以直接照搬调整security-audit-skill/ ├── SKILL.md # 核心指令文件 ├── skills/ # 规则与模板目录 │ ├── audit_rules.md # 审计规则明细 │ ├── cwe_mapping.md # 漏洞类型与CWE映射 │ ├── report_template.md # 报告输出模板 │ └── tool_config.md # 工具链配置说明 ├── scripts/ │ ├── preflight.sh # 环境预检脚本 │ ├── scan_python.sh # Python项目扫描脚本 │ ├── scan_js_ts.sh # JS/TS项目扫描脚本 │ └── report_generator.py # 报告汇总生成脚本 └── references/ ├── owasp_top10_2021.md ├── cwe_top25.md └── common_weakness_patterns.mdSKILL.md 是整个 skill 的入口里面定义了技能的元信息、触发条件、执行主流程。外围的 skills 目录存放的是执行过程中需要查询的知识库文件scripts 目录是具体的扫描执行脚本references 目录存放经常需要查阅的行业标准文档。3.2 SKILL.md 的核心写法SKILL.md 的内容是整个 skill 的灵魂它的质量决定了审计过程是否专业、结果是否可靠。我写的简化版本如下你可以看看整体结构--- name: security-audit description: 对指定项目或代码片段进行全面的安全审计覆盖配置风险、依赖漏洞、输入注入、越权问题、业务逻辑缺陷等输出结构化审计报告。 version: 1.0.0 author: security-team trigger: 用户要求进行安全审计、代码安全检查、漏洞扫描、渗透测试辅助、安全评估等 --- # 安全审计执行流程 当用户触发安全审计任务时按以下流程执行 ## 阶段一信息收集必做 1. 识别项目类型和主要语言package.json / requirements.txt / pom.xml 等manifest文件 2. 梳理项目目录结构定位核心源码路径 3. 检查依赖清单记录所有第三方组件的名称和版本 4. 读取项目的部署配置、环境变量文件注意不要输出敏感信息 ## 阶段二工具扫描必做 1. 运行 preflight.sh 检查环境依赖是否满足 2. 根据项目语言选择对应的扫描脚本 3. 保存工具扫描结果作为后续分析的参考依据 ## 阶段三人工分析核心 1. 结合工具扫描结果手动审阅高风险代码路径 2. 对疑似问题执行数据流追踪输入源 - 处理逻辑 - 危险函数 3. 对照 cwe_mapping.md 判断漏洞类型 4. 使用 CVSS 3.1 标准进行风险评估 ## 阶段四报告输出必做 严格按 report_template.md 模板生成审计报告不得省略修复建议与审计盲区声明部分这里最关键的是阶段的强制性和顺序性。必做标签要在指令里明确写出来Agent 接到指令后必须按顺序走完整条流程不允许跳过。没有强约束的话Agent 很可能只做一部分就给出结论说未发现严重问题。3.3 审计规则的编写要点audit_rules.md 是给 Agent 看的审计规范相当于给一个初级审计员看的作业指导书。里面要写清楚每种漏洞类型的具体特征和排查方法。举几个例子# SQL 注入排查规则 ## 特征识别 - 字符串拼接 SQLSELECT * FROM users WHERE id userId - f-string 拼接fSELECT * FROM users WHERE id {user_id} - ORM 框架中使用 raw query 且直接拼接受外部输入的参数 - MyBatis 等框架中使用 ${} 而不是 #{} ## 数据流追踪 1. 起点查找 request.getParameter()、req.query、body 解析、form 表单字段 2. 路径追踪参数是否经过过滤、编码、白名单校验 3. 终点是否到达 executeQuery()、session.execute()、raw() 等危险函数 ## 判断标准 - 用户可控输入未经参数化直接进入 SQL 执行 → 判为严重 - 用户可控输入经过简单 replace 但可绕过如替换空格为%20 → 判为高危 - 输入经过严格白名单校验 → 视为已修复标注已验证每条规则按特征识别→数据流追踪→判断标准三要素组织。实践下来这种结构比单纯写检查是否存在SQL注入有效得多因为它给了 Agent 一套可执行的判断路径而不仅仅是一个目标。3.4 脚本化落地让工具扫描闭环执行为了让 skill 真正能跑起来我写了几个配套脚本。拿 Python 项目的扫描脚本举例#!/bin/bash # scan_python.sh - Python 项目安全扫描 PROJECT_PATH$1 REPORT_DIR${2:-./audit_result} if [ ! -d $PROJECT_PATH ]; then echo [ERROR] 项目路径不存在: $PROJECT_PATH exit 1 fi mkdir -p $REPORT_DIR # 1. 使用 Bandit 做基础安全扫描 echo [INFO] 运行 Bandit 扫描... bandit -r $PROJECT_PATH -f json -o $REPORT_DIR/bandit_result.json 2/dev/null # 2. 使用 Semgrep 做自定义规则扫描 echo [INFO] 运行 Semgrep 扫描... semgrep scan --configauto --json --output $REPORT_DIR/semgrep_result.json $PROJECT_PATH 2/dev/null # 3. 使用 gitleaks 检查硬编码密钥 echo [INFO] 运行 gitleaks 扫描... gitleaks detect --source $PROJECT_PATH --report-format json --report-path $REPORT_DIR/gitleaks_result.json 2/dev/null # 4. 使用 OWASP Dependency-Check 检查依赖漏洞 echo [INFO] 运行依赖安全检查... dependency-check --scan $PROJECT_PATH --format JSON --out $REPORT_DIR/dependency_check_result.json 2/dev/null echo [INFO] 扫描完成结果保存在: $REPORT_DIR脚本的作用是把整个扫描过程固化成可重复执行的流程而且输出格式统一为 JSON方便后续的 report_generator.py 汇总分析。3.5 报告生成与人工复核机制扫描和分析的最终产物需要一份完整报告我写了一个 report_generator.py 来汇总所有扫描结果再结合 Agent 的分析结论生成最终报告。核心逻辑是读取全部 JSON 文件提取关键信息按风险等级排序输出一份 Markdown 格式的报告。考虑到人工复核环节必不可少我会要求 Agent 在报告最后附上审计盲区声明——哪些文件因为上下文长度限制没有详细追踪、哪些逻辑因为依赖关系不完整无法判断、哪些问题需要安全团队现场确认。网易的硬性要求是在报告生成后由人工对高危及以上问题做逐条复核确保没有误报或漏报。这个机制非常重要它保证了 skill 的输出不会因为过度自信而误导开发人员。4. 常见问题与排查技巧实录4.1 Agent 在审计过程中的典型问题这个 skill 跑了一周我总结出了几个高频问题这里直接列给读者。问题一Agent 过度依赖工具输出忽略逻辑分析。静态扫描工具会产生大量告警Agent 有时会直接把工具告警当成最终结论把低危甚至误报的问题标成高危。比如 Bandit 对eval()函数默认报 B307 高风险但在某些场景下这个 eval 处理的输入根本不涉及用户可控数据。处理办法是在规则里明确写了对每个工具告警必须做上下文验证需要给出为什么可被利用的分析过程不能直接采信工具结果。问题二上下文窗口太长追踪到一半就丢了信息。一个大项目往往有几十上百个文件Agent 很可能在追踪某个数据流时把前面查到的关键信息冲掉了。解决办法是引入审计笔记机制要求 Agent 在执行过程中边审边记把关键的数据流路径、可疑函数的调用位置、参数传递关系写下来每追踪完一个数据流就做一次小结。这样即使后来上下文刷新关键信息也不会丢。问题三对常见框架的安全机制不熟悉导致误判。比如 Spring Security 会自动拦截很多未授权请求Django 的 ORM 天然参数化查询Agent 如果不了解这些框架特性会把本来就安全的设计误报为漏洞。解决方法是在 references 目录补充了常见框架的安全特性说明同时在 SKILL.md 里加了框架误报检查这一步要求 Agent 在判定漏洞前先确认当前框架是否有对应安全机制。4.2 工具使用与配置中的常见坑坑一Bandit 的扫描根路径必须指向入口文件所在的目录否则可能漏掉整个包。这一点容易踩扫描 src 和扫描项目根目录的结果差异明显。我最终选择在脚本里固定使用项目根路径这样能保证完整覆盖。坑二Semgrep 的 auto 配置在部分环境中会导致请求超时或网络受限。社区规则集需要联网拉取在隔离网络环境下会失败。备选方案是先把规则集下载到本地然后使用--config指定本地目录。坑三gitleaks 默认的规则库对国内常见开发习惯存在较高的敏感信息误报。比如测试密钥、示例密钥也会被标出来。建议先跑一遍默认规则把误报规则排除掉然后根据团队实际情况自定义允许名单只保留真正需要拦截的密钥模式。坑四项目上下文过大导致 Cost 膨胀。大项目全量扫描可能一次消耗大量 token。一个可行的优化是分模块审计只选核心代码目录和高风险模块把非核心的配置文件、测试代码、文档目录排除在外。也可以通过 .gitignore 类似机制的排除清单来让 Agent 只关注重点目录。4.3 如何验证 Skill 审计结果的有效性验证一个安全审计 skill 是否真的有效我有一个简单可用的方法准备一个包含已知漏洞的历史项目漏洞清单提前标注好然后跑一遍 skill对比发现的漏洞数量和准确率。我自己的测试集里放了 20 个故意构造的漏洞分布在 SQL 注入、XSS、硬编码密钥、越权、反序列化、危险文件上传这些类别最终扫描加人工分析找回了 17 个漏掉了 1 个越权问题和 2 个需要复杂调用链才能触发的逻辑问题。这个结果符合预期——标准漏洞模式覆盖得比较全业务逻辑相关的问题依然需要人工参与。5. 经验总结做好安全审计 Skill 的三个核心原则5.1 规则要具体到能直接执行写审计规则时一个容易犯的错误是写得太过笼统。比如检查是否存在代码注入风险这句话Agent 理解起来其实无从下手。更合理的写法是把特征条件列清楚存在哪些形式的字符串拼接、哪些危险函数不能直接接收用户输入、数据流的追踪起点和终点分别是什么。只有规则具体到能直接照着操作Agent 才能稳定输出高质量的结果。5.2 流程要强约束但也要给判断空间Skill 的价值在于流程的确定性但这个确定不能变成死板。我对流程设置了一定的优先级信息收集和报告输出是硬性要求不可跳过但中间的深度分析部分Agent 可以根据实际情况调整追踪的深度比如某个接口审计下来确实不存在任何可疑输入点就可以跳过详细追踪进入下一项。给判断空间的意义在于避免 Agent 为了走流程而走流程、浪费时间在无关紧要的代码上。5.3 人工复核永远不能省自动化工具加 Agent 分析能解决 80% 的常规安全检查但最后 20% 的复杂问题还是需要安全工程师介入。我的建议是把 skill 定位成提高安全审计效率的加速器而不是替代安全人员的自动化机器。高危级的发现必须经过人工复核才能进入修复流程这样才能保证结果可靠也避免自动化扫描产生的误报浪费开发资源。6. 后续扩展方向目前这个 security-audit-skill 的基础版本已经能覆盖大多数常规项目的安全预检需求。后续我计划做几个方向的扩展。第一是增加 CICD 集成能力把 skill 的扫描和报告生成做成流水线的一环每次提交代码后自动触发增量安全扫描并把结果直接反馈到合并请求的评论里。这样安全问题能在开发阶段就被拦截而不是等到上线前集中审计。第二是扩展更多语言和框架的支持。目前对 Python、JavaScript/TypeScript、Java 和 Go 支持的比较深入后续准备补充 Ruby、PHP、C# 这些语言的安全扫描规则和常见漏洞模式。第三是丰富漏洞知识库。当前 references 目录维护了 OWASP Top 10 和 CWE Top 25后续会持续同步最新的漏洞公告和利用手法让审计知识同步到最新的威胁态势。最后说一句个人体会。这一周迭代下来最大的感受是做 Agent Skill 看起来是技术活本质上是方法论活。你对某个专业领域理解得越深写出来的 Skill 就越实用。安全审计如此其它领域的 skill 也是一样——先把人做事的流程想明白再考虑怎么把它固化下来。这个思路用在哪都通。