1. 为什么安全审计需要“技能化”
1.1 安全审计的痛点：不是扫描器不够，而是流程太碎
先交代一下背景。最近我在负责一个后端代码仓库的安全审计工作，前后折腾了两周，最大的感受不是扫描工具不够强，而是整个审计流程碎得让人头疼。
一般的安全审计大概包括这么几件事：先要把项目依赖拉出来，对照漏洞库查一遍；然后跑静态代码扫描，看有没有SQL注入、命令注入、敏感信息硬编码这类问题；还要顺带检查一下配置文件有没有把密码写死、密钥有没有被提交到仓库里；最后把所有结果整理成一份能交给开发团队去修的报告。
每件事都有对应的现成工具，比如依赖检查用trivy，静态扫描用semgrep，密钥检测用gitleaks。但工具之间的协作完全靠人工。跑完一个工具，拿到一堆输出，你还得手工去过滤误报、判断真伪、归类优先级，然后把这些结论翻译成开发团队能看懂的修复建议。
传统做法是写一堆shell脚本把这些命令串起来，但脚本的问题是“死”的。它不知道当前仓库是什么语言、什么框架、有没有历史遗留问题需要排除，也不会根据扫描结果动态调整后续动作。说白了，脚本只能机械执行，不能“想”。
1.2 skill与agent的分工：skill是“会做的事情”，agent是“调度的脑”
后来我接触到AI编程助手里的skill机制，思路一下子打开了。这里的skill不是传统意义上的“技能树”，而是给AI Agent用的、结构化封装好的能力模块，里面通常包含说明文档、脚本、规则模板和示例输出。Agent可以在需要的时候自动加载这个skill，按照skill里定义的流程去执行任务。
很多人分不清skill和agent的区别，我打个比方。Agent像一个项目的负责人，它负责理解你的需求、拆解任务、调度资源、检查结果。Skill则像是负责人手下的施工班组操作手册，里面清楚写了“遇到什么情况该用什么工具、按什么顺序执行、输出什么格式”。没有skill的Agent，就像一个很聪明但没有任何工地经验的实习生，你让它去检查脚手架安全，它能跟你聊一堆安全理论，但不知道实际该看哪里、量什么、记录什么。
反过来说，如果把安全审计的完整方法论固化成一个skill，Agent就能按手册干活：先收集依赖，再跑静态扫描，然后查密钥泄露，最后汇总出报告。整个过程Agent负责调度和判断，skill负责提供专业能力。
1.3 为什么选security-audit作为第一个skill
我之所以把security-audit作为第一个吃螃蟹的项目，有三个原因。
第一，安全审计的流程边界很清晰。从输入（一个代码仓库）到输出（一份审计报告），中间每一步做什么都是约定俗成的，非常适合固化成标准流程。相比如“做个新功能”这种开放性问题，“审一遍这个仓库的安全性”是有限边界任务，模型和skill都不容易跑偏。
第二，这个领域已经有大量成熟的命令行工具。trivy、semgrep、gitleaks、bandit这些工具输出稳定、文档齐全，skill里只需要封装调用逻辑和结果解析逻辑，不需要从零造轮子。
第三，安全问题天然适合大模型做二次分析。扫描器擅长“发现异常”，但不擅长“判断这是不是一个真问题”。比如semgrep报了一个“可能存在的SQL注入”，到底能不能被实际利用，需要结合上下文判断。大模型恰好擅长这种推理。scan器负责筛，模型负责断，skill负责把两者串起来，这个组合非常舒服。
一句话总结我的思路：把安全审计专家的执行流程和判断标准，封装成Agent能读懂、能调用、能复用的技能包。
2. security-audit-skill的核心设计
2.1 skill的目录结构：别小看文件摆放这件事
Skill的目录结构是第一个要设计好的东西。我见过不少人写的skill，功能逻辑没问题，但目录乱成一锅粥，Agent根本不知道先读哪个文件，后跑哪个脚本。结构化、命名清晰，是skill能被正确加载的前提。
我用的目录结构如下：
security-audit/ ├── SKILL.md ├── scripts/ │ ├── audit_sast.py │ ├── audit_secrets.py │ ├── collect_deps.py │ └── report_builder.py ├── rules/ │ ├── custom_sast_rules.yaml │ └── audit_policy.json └── templates/ └── report_template.md几个关键点说明一下。
SKILL.md是整个skill的入口和说明书，Agent会优先读取这个文件来理解skill的用途和调用方式。scripts目录放所有可执行脚本，每个脚本职责单一，比如collect_deps.py只负责收集依赖清单，audit_sast.py只负责跑静态扫描。rules目录放自定义规则和策略配置，我自己加的semgrep规则会放在这里，和工具默认规则区分开。templates目录放报告模板，保证每次输出的审计报告结构一致，这个对有报告洁癖的人来说很解压。
目录结构设计的一个核心原则是：让Agent在看到SKILL.md之后，不需要问人就能知道“下一步执行哪个脚本”。所以脚本命名要直观，不要出现a.py、b.py这种只有自己能看懂的命名。
2.2 SKILL.md怎么组织：让大模型知道什么时候该用、怎么用
SKILL.md不是给人类看的开发文档，而是给大模型看的“使用说明书”。这两者的写法有本质区别。人类文档追求严谨完整，模型说明书追求“意图匹配清晰+调用链明确”。
我的SKILL.md结构大致是：
# Security Audit Skill ## 适用场景 - 对代码仓库进行安全审计，包括依赖漏洞、代码缺陷、密钥泄露等 - 适用语言：Python、JavaScript、TypeScript、Java、Go - 不适用的场景：不负责修复代码漏洞，只负责发现与建议 ## 依赖工具 - trivy（依赖漏洞扫描） - semgrep（静态代码分析） - gitleaks（密钥泄露检测） - 需要提前安装并确保在PATH中可用 ## 审计流程 1. 先运行 scripts/collect_deps.py 收集依赖清单 2. 再运行 scripts/audit_sast.py 执行静态代码扫描 3. 然后运行 scripts/audit_secrets.py 检查密钥泄露 4. 最后运行 scripts/report_builder.py 汇总生成审计报告 ## 注意事项 - 所有脚本默认在仓库根目录执行，绝对不要扫描node_modules或.venv目录 - 扫描结果会输出为JSON文件，存放在 .audit-cache/ 目录下 - 如果已有前一天的结果缓存，审计脚本会跳过未修改的文件（增量模式） - 输出报告必须包含修复建议，禁止只报问题不给方案注意看，这个文件里有几个关键信息：适用场景（什么时候该用）、依赖工具（需要什么环境）、审计流程（怎么执行）、注意事项（有什么坑）。这些内容的顺序和权重很有讲究。
适用场景一定要写得具体，不然会出现“用户问一处代码注释的黑客段子，Agent也想去跑安全审计”这种尴尬情况。我一开始就是因为在SKILL.md里没写清楚适用场景，结果Agent在我让它处理任何代码问题时都先跑一遍安全扫描，简直灾难。
注意事项是给模型划红线。比如规定不要扫描依赖目录，否则一次审计能给你扫出几千个第三方库漏洞，报告根本没法看。增量模式也很重要，不然每次全量扫描，仓库大了之后一次审计要跑十几分钟。
2.3 规则与策略：把经验固化成代码
Skill除了流程，还要把安全专家的判断经验固化下来。这部分我放在rules目录里。
拿semgrep来说，官方规则库很全，但很多规则在你的项目里根本不适用。比如一个内部管理后台项目，不太可能受到公开互联网攻击，很多关于SSRF的规则实际威胁等级就偏低。所以我没有直接全量启用所有规则，而是基于项目自身情况挑了一批高危规则，再自己补几条针对性的自定义规则。
我写了一个自定义规则文件，截取一段Python相关的：
rules: - id: python-eval-usage patterns: - pattern: eval($ARG) message: "检测到eval()动态执行代码，请确认参数来源。如果参数来自用户输入，存在代码注入风险，建议改用ast.literal_eval替代。" languages: - python severity: WARNING你可能觉得这条规则很简单，但它很实用。eval()在Python里一直是个危险函数，安全审计时看到就要重点确认。用semgrep规则把这类问题自动抓出来，比我以前用grep搜eval，再一个个看上下文要高效得多。
还有安全策略配置文件audit_policy.json，用来定义审计的优先级和阈值：
{ "severity_weights": { "critical": 10, "high": 7, "medium": 4, "low": 1 }, "threshold": 15, "block_on": ["critical", "high"], "ignore_paths": ["tests/", "docs/", "examples/"] }这个文件的作用是给后面的流程决策用的。比如阈值设在15，如果一次审计累计的高危问题超过这个数，脚本就会在报告开头加上一句“本次扫描发现问题过多，建议暂停发版，优先处理安全问题”。这些都是把专家经验固化成机器可执行的策略。
2.4 脚本层的设计：稳定、可解释、容错
脚本是skill的手脚。设计脚本时我最看重三个词：稳定、可解释、容错。
稳定是指脚本在仓库根目录下执行时，不管目标是Python项目还是Node项目，都能正常工作。实现方式是所有脚本内部先做一次项目类型检测，根据包管理器的不同走不同分支。
可解释是指脚本的输出必须是结构化的，最好全程使用JSON。为什么？因为Agent读JSON比读大段日志效率高得多。一个脚本的输出如果是“扫描发现3个高危问题，具体如下”这种自然语言，模型还要再解析一遍，容易出错。JSON直接给模型，它一眼就能看懂每个字段的含义。
容错是指脚本不能因为某个小异常就崩掉。比如gitleaks报错说当前仓库没初始化git，脚本不会直接退出，而是记录一条warning然后继续跑semgrep。我把这个容错逻辑放到了脚本的核心循环里，任何一步失败都只影响当前步骤，不影响整体审计流程。
results = {} try: results["deps"] = run_dependency_scan() except Exception as e: results["deps"] = {"error": str(e), "issues": []} try: results["sast"] = run_sast_scan() except Exception as e: results["sast"] = {"error": str(e), "issues": []} try: results["secrets"] = run_secrets_scan() except Exception as e: results["secrets"] = {"error": str(e), "issues": []}虽然代码看起来很简单，但这几个try-except是防止“一处报错全盘崩溃”的关键。很多时候安全审计跑在别人的仓库上，你永远不知道会遇到什么奇葩环境，容错设计能救命。
3. 实操落地：从零写一个能用的security-audit-skill
3.1 环境准备：工具不在多，够用就行
先说环境依赖。因为skill的核心是调用外部命令行工具，所以先把工具装齐。
# Python生态，用来跑脚本逻辑 sudo apt-get install -y python3-pip # 依赖漏洞扫描器 sudo apt-get install -y trivy # 静态代码分析工具 python3 -m pip install semgrep # 密钥泄露检测工具 sudo apt-get install -y gitleaks # JSON处理工具（脚本内部会用到） sudo apt-get install -y jq安装完之后，验证一下工具是否都在PATH里：
which trivy semgrep gitleaks jq如果每个命令都返回了路径，说明环境就绪。这里有个小提醒：semgrep的版本迭代很快，规则写法有细微差别，建议在虚拟环境里安装，别直接装到系统Python里，不然以后升级容易把系统环境搞乱。
3.2 编写SKILL.md内容样例
我复制一份当时项目里实际用的SKILL.md，你可以直接参考这个结构来写自己的版本：
# Security Audit Skill ## 适用场景 这个skill用于对代码仓库进行安全审计。它会检查依赖漏洞、静态代码缺陷、密钥泄露三类问题，并根据发现的问题生成带修复建议的审计报告。 ## 触发条件 - 用户要求“安全审计”或“安全检查”或“security audit” - 用户提到“扫描一下代码有没有漏洞”“检查依赖是否安全”等类似表达 - 注意：如果用户只是想了解安全审计的概念，而不是要求实际扫一个仓库，不要使用本skill ## 依赖工具 trivy、semgrep、gitleaks、python3、jq，工具缺失时先提示安装再执行 ## 使用流程 1. 确认当前目录是仓库根目录 2. 执行 python3 scripts/collect_deps.py 收集依赖 3. 执行 python3 scripts/audit_sast.py 执行静态代码扫描 4. 执行 python3 scripts/audit_secrets.py 执行密钥泄露扫描 5. 执行 python3 scripts/report_builder.py 汇总生成报告 6. 把报告内容呈现给用户，重点说明高危及以上问题 ## 输出要求 - 必须包含问题描述、文件位置、危险等级、修复建议 - 如果没有发现问题，也要明确说明“未发现明显风险” - 报告生成后，按照严重程度从高到低排序呈现 ## 注意事项 - 不要扫描 node_modules、.venv、vendor 等第三方目录 - 扫描过程中如果某个工具失败，不要停止，继续跑其他工具 - 不要把原始扫描日志全部贴给用户，先汇总再展示 - 缓存目录 .audit-cache/ 属于临时文件，报告生成后可以清理注意这里面的触发条件写了两层：什么时候“应该用”，什么时候“不应该用”。这是很多skill作者容易忽略的。光是“用什么”不够，还要让模型知道“别乱用”。
3.3 核心脚本的调用链
脚本调用链这块，我直接说明每个脚本的核心逻辑，方便你照着实现。
collect_deps.py的逻辑是：先检测仓库里存在哪个包管理文件。如果发现requirements.txt，就用trivy的requirements模式扫描Python依赖；如果发现package-lock.json，就用trivy的node模式；如果发现go.mod，就走gomod模式。然后输出一个JSON文件，记录每个依赖的版本和已知漏洞。
audit_sast.py的逻辑是：调用semgrep，加载初始规则集，加上rules/custom_sast_rules.yaml里的自定义规则，扫描当前目录下的代码文件。扫描完成后解析semgrep输出的JSON，过滤掉ignore_paths中配置的目录，把剩余问题汇总成结构化列表。
audit_secrets.py的逻辑是：用gitleaks的dir模式扫描整个仓库，检测是否有密钥、密码、token等敏感信息被硬编码在代码里。检测到结果后，脚本会做一步去重和排除处理，比如排除测试文件中的假密钥。
report_builder.py的逻辑是：读取前三个脚本生成的JSON结果，按严重程度排序，套用report_template.md模板，生成最终的Markdown报告。报告里每一条问题都给出了文件路径、行号、问题描述和修复建议。
整个调用链设计成四个脚本串行，而不是一个大脚本一次性做完所有事。好处是：每一步的输出都是中间产物，可缓存、可复查、可单独调试。如果semgrep扫描结果有问题，你只需要重跑audit_sast.py，不用把前面依赖扫描也重新跑一遍。
3.4 在AI编程助手中注册与调用
Skill写好之后，怎么让Agent识别到它？不同工具的配置方式不一样，但大方向是统一的：把skill目录放到指定的配置目录，然后在对话中触发。
以我用的环境为例，在配置文件里注册skill目录，指向我本地的security-audit/目录。注册成功后，对话中只要提到类似“对当前项目做一次安全审计”，Agent就会主动读取SKILL.md，按流程开始执行。
调用效果大概是这样的：Agent先调用collect_deps.py，我看到终端开始跑trivy扫描；然后接着跑semgrep，输出的问题列表会实时显示；最后gitleaks扫描完毕，Agent把汇总报告呈现在我面前。整个流程大概两三分钟，比我手动逐个跑工具再自己写报告快了不止一个量级。
有一个使用上的小技巧：如果你只想让Agent审某个子目录，可以直接说“只审计api/目录，不审计前端代码”。因为SKILL.md里的ignore_paths是全局配置，线程粒度的控制需要用自然语言约束，Agent会结合你的要求调整semgrep的扫描路径参数。
3.5 输出示例与人工复核
一份合格的审计报告长什么样？我截取一个实际跑出来的片段给你感受一下：
# 安全审计报告 扫描目标：/data/projects/order-service 扫描时间：2025-01-12 14:32:05 ## 高危问题 ### SQL注入风险 - 文件：src/repository/order.py:78 - 问题描述：使用f-string拼接SQL查询语句，参数直接嵌入SQL，存在注入风险 - 修复建议：使用ORM参数化查询，或使用?占位符，禁止直接拼接字符串 ### 敏感密钥泄露 - 文件：config/production.yaml:23 - 问题描述：检测到疑似阿里云AccessKey Secret，格式匹配 - 修复建议：立即吊销该密钥，改用环境变量或密钥管理服务存储报告呈现的时候，Agent还会做一道人工复核的工序，它会把semgrep报出的问题里那些明显误报先过滤掉，比如一个测试文件里故意写的“eval”示例，实际上根本没有外部输入，Agent会在报告里备注“该问题疑似误报，原因：测试代码，无用户输入路径”。
这一步是纯脚本做不到的，也是为什么skill要跟大模型配合而不是纯靠脚本跑的原因。
4. 常见问题与排查实录
4.1 skill没有被Agent识别
这是最常见的坑。我把skill目录放在指定配置目录下之后，一开始怎么触发都不生效，Agent对我的“安全审计”请求完全无感，只跟我聊安全概念，不调用任何脚本。
排查了一圈发现是两个原因造成的。第一，目录名不对。我把目录命名成了security_audit（下划线），但Agent只会识别连字符格式的skill目录名。改回security-audit之后马上就被识别了。第二，SKILL.md开头没写好。我一开始写的是“This document describes...”，Agent读了之后把它当普通文档，没有识别成skill定义。后来改成“# Security Audit Skill”这种明确的标题格式，问题解决。
如果你也遇到类似情况，优先检查这两点，大概率能解决。
4.2 误报太多，报告没法看
用semgrep默认规则集扫一个中型项目，第一次生成的报告有300多个问题，其中大部分是低危和中危，真正需要立即处理的高危问题其实只有十几个。
误报多的时候，不要轻易把规则集去掉，那样会把真正的问题也漏了。我建议的做法是：先跑一次全量扫描，把结果保存一份，然后不看低危问题，只看高危和严重的问题。同时针对那些频繁误报的规则，在audit_policy.json的ignore_paths里加上对应目录，或者直接在semgrep的自定义规则配置里把某条规则标记为disabled。
另外，要做baseline。第一次审计时把所有存量问题标记为“已知问题”，后续审计只关注新增问题。这个逻辑我在SKILL.md里通过缓存目录实现了，增量模式跑起来之后，报告的噪声一下子少了很多。
4.3 上下文被撑爆，Agent处理不过来
还有一个很实际的问题：扫描出来的原始结果可能是几千行JSON，如果Agent把所有内容都塞进上下文窗口，会直接把对话撑爆。Agent的处理能力再强，给它几千个问题它也只能走马观花。
我在report_builder.py的脚本里做了摘要逻辑：如果某个类型的问题超过20条，只输出前5条明细，然后加一行“该类型另有N条类似问题，已汇总为附件”。这样Agent拿到的上下文是浓缩过的，既能看到问题全貌，又不会淹没在海量细节里。
这个优化做完之后，生成报告的速度明显快了，Agent的回复质量也更高，因为它能把精力放在分析高危问题上，而不是花时间逐条阅读几千条低危提示。
4.4 扫描太慢，跑一次要等很久
我第一个版本是全量扫描，一个代码量中等的仓库跑下来需要十几分钟，简直不能忍。排查发现瓶颈在trivy，每次都要重新拉取漏洞数据库，而且还连带扫描了所有依赖目录。
优化方案有三个，我都用上了。第一，给trivy配置数据库缓存路径，不让它每次都下载。第二，扫描前先用collect_deps.py生成依赖清单，然后直接指定trivy只扫描这个清单文件，不扫整个目录。第三，把增量扫描的逻辑打开，基于git的mtime判断哪些文件改过，没改过的直接跳过。三个优化叠加，一次审计从十几分钟降到了两分钟左右，基本可用了。
| 优化项 | 做法 | 效果 |
|---|---|---|
| 数据库缓存 | 设置TRIVY_CACHE_DIR，持久化漏洞库 | 减少重复下载 |
| 依赖清单扫描 | 先收集依赖清单再喂给trivy | 减少无关扫描 |
| 增量模式 | 只扫变更文件 | 大幅缩短全量时间 |
4.5 自定义规则逻辑正确但semgrep不执行
写自定义规则的时候遇到过一个诡异问题：规则文件语法检查通过，但semgrep就是一条都匹配不到。后来发现是规则文件里的languages字段写错了。我写的是python，但那个仓库其实是Python 3项目，semgrep期望的语言标识是python，没问题；真正的问题是YAML文件里有一个字段值包含了未转义的双引号，导致规则被静默跳过。
排查方法：先用semgrep --validate规则文件检查有没有报错，再单独用一条极简规则测试，确认semgrep能正常匹配，最后再逐步调试复杂规则。别嫌麻烦，这种问题排查起来比你想的更耗时间。
5. 进阶：把这个skill做成团队标准审计流水线
5.1 与CI/CD结合，审计自动化
Skill在本地能用起来之后，更大的价值是推进到CI/CD流水线里，让每次代码提交自动跑安全审计。
我用GitHub Actions做了一个示例配置，核心逻辑是：代码推送到main分支或提交Pull Request时，自动检出代码，安装工具，跑security-audit skill，把结果作为PR评论发布。
name: Security Audit on: pull_request: branches: [ main ] jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Install tools run: | pip install semgrep apt-get update && apt-get install -y gitleaks trivy jq - name: Run security audit skill run: | python3 scripts/collect_deps.py python3 scripts/audit_sast.py python3 scripts/audit_secrets.py python3 scripts/report_builder.py - name: Post report to PR run: | cat .audit-cache/report.md >> $GITHUB_STEP_SUMMARY配合前面提到的baseline机制，增量扫描在CI场景特别重要。没有baseline的话，一个老仓库每次PR都会被历史问题刷屏，开发人员很快会对审计报告免疫，流水线就形同虚设了。
5.2 多Agent协作场景：审计与修复的闭环
Skill封装的不只是“扫描”这一件事，更是一个完整的协作协议。
在我们的团队里，我把审计流程做成了两个Agent协作的模式。安全Agent持有security-audit-skill，负责扫描和出报告；开发Agent负责根据报告修复代码。两个Agent之间通过“问题清单文件”协作，安全Agent输出的每个issue都带了一个唯一的编号，修复时按编号追踪。
这个做法的好处是，审计报告不只是一份记录，而是一份可执行的任务清单。开发Agent拿到报告后，可以针对高危问题逐条修复，修完再跑一遍同一份skill，看对应编号的问题是否消失。整个流程形成了一个闭环，而不是单向的一次性审计。
要做到这一点，skill里的report_builder.py会在每个issue后面增加一个“验证命令”字段，告诉Agent修复后怎么验证。比如SQL注入那条，验证命令就是“重新执行semgrep，确认该告警消失”。
5.3 后续扩展思路：从代码审计到全面安全检查
目前这个security-audit-skill覆盖了依赖漏洞、静态代码缺陷和密钥泄露三个维度，这已经覆盖了绝大多数应用层安全问题。但还是可以继续扩展，我有几个已经验证可行的方向。
一个是容器镜像扫描。如果你的服务是容器化部署，可以在skill里增加一个镜像扫描步骤，用trivy的image模式直接扫镜像文件，把基础镜像的漏洞也纳入审计范围。一个是IaC配置审计，用tfsec或checkov扫描Terraform、CloudFormation这类基础设施代码，检查是否有暴露高风险端口、开启了公共访问权限之类的配置问题。
还有一个方向是规则库的持续更新。目前skill里的自定义规则是我手动维护的，semgrep的社区规则库也在持续更新，我设置了一个每周任务，自动拉取最新规则，跟自定义规则合并后再跑一遍离线测试，确保规则更新不会导致大量误报。这些功能都做完之后，这个skill就不再只是一个工具脚本集合，而是一个小型的团队安全基础设施了。
最后分享一点自己的体会
安全审计这个事，以前总让人觉得是专家才能干的活。我做了这个skill之后最大的感受是：专家经验可以被结构化和工具化，然后在Agent的调度下发挥出规模化的价值。锦上添花的是，当你把规则、策略、流程都固化下来之后，团队的审计水平会明显向最好的那一次审计对齐，而不是每次依赖不同人的经验发挥。
如果你也想做一个类似的skill，我的建议是不要一开始就追求大而全。先从一个最简单的SKILL.md配一个脚本开始，跑通“Agent识别skill-调用脚本-输出报告”这条链路，然后再逐步加规则、加工具、加增量优化。步子大了容易扯到蛋，先小步快跑，把一个垂直场景做到极致，比做一个什么都沾一点但什么都不精的“全家桶”实用得多。
