做安全审计这件事重复劳动远比想象中多。每次拿到一个代码库先要扒依赖、扫密钥、查配置、翻权限一趟下来光是信息收集就得花掉大半天真正需要人脑判断的部分反而被压缩。后来我把这套流程固化成了一个 AI Agent 的 skill让 Claude Code 这类工具先做一轮初筛我再聚焦确认效率提升非常明显。这篇就聊聊我编写 security-audit-skill 的完整思路、目录设计、脚本落地和实测踩坑希望能给正在做类似方向的开发者一些参考。security-audit-skill 不是一个渗透测试工具也不替代专业安全工程师的判断它是一个结构化的审计方法论封装把安全审计中可重复、可量化的部分交给 Agent 自动化执行把需要语义理解和业务判断的部分保留给人。适合本身熟悉开发、又需要经常做代码安全自查的工程师也适合正在研究 Agent skill 写法、想给自己的编程助手扩展能力的开发者。1. security-audit-skill 到底解决什么问题1.1 安全审计里的可复用流程在决定写这个 skill 之前我复盘了过去做过的几十次代码安全审计发现不管是前端项目还是后端服务流程高度相似先收集项目结构和技术栈信息然后扫描硬编码密钥、检查依赖漏洞、排查危险的权限配置再针对业务代码做注入类风险的语义分析最后整理出一份分级报告。这套流程完全可以标准化。问题在于这些步骤分散在多个工具和多个命令里每次审计都要重新拼接一遍。gitleaks 扫密钥、npm audit 或 pip-audit 查依赖、grep 翻配置文件再把结果人工汇总。Agent 的能力恰恰适合做这件事——它能理解审计目标能编排工具链能按固定格式输出报告。所以我把流程、规则、脚本、报告模板全部塞进一个 skill 里让 Agent 一次性完成信息收集 初筛 报告生成。1.2 这个 skill 的边界定位最开始我犯过一个错误想让 skill 做太多事包括自动利用漏洞、生成攻击 payload结果既不安全也不可控。后来把边界收敛成三条代码级与配置级审计检查的是代码仓库、依赖清单、环境配置、权限文件不涉及对线上系统的主动探测。自动化初筛 辅助决策skill 负责找出可疑点比如疑似硬编码的密钥、已知 CVE 的依赖版本、过宽的 CORS 配置但最终是否算漏洞、风险有多大需要人来判断。可解释、可追溯每一条发现都要附带证据位置不能只给结论不然没法核验。这个边界让 skill 在有用和失控之间找到了平衡点。它是放大审计员效率的工具而不是替代审计员脑子的黑盒。1.3 谁适合直接拿它上手如果你满足下面任意一条这个 skill 的思路值得参考一是经常做项目自查、交付前安全评估的开发者二是负责团队代码安全规范落地的工程效率岗三是在研究 Agent skill 怎么写、想让 AI 编程助手承担更多专业判断的实践者。就算你没有完整的安全背景只要理解基本的漏洞类型这个 skill 也能帮你建立一条可执行的审计基线。2. Skill 目录结构与 SKILL.md 的主干设计2.1 一套清晰的目录布局Agent skill 的落地形态并不神秘本质上就是一个带规范文档和辅助脚本的目录。我的 security-audit-skill 最终长这样security-audit-skill/ ├── SKILL.md ├── scripts/ │ ├── scan_secrets.py │ ├── check_deps.py │ └── audit_config.py ├── rules/ │ ├── secret_patterns.yaml │ ├── config_rules.yaml │ └── dependency_rules.yaml ├── reports/ │ └── audit_report_template.md └── examples/ └── sample_findings.mdSKILL.md是入口文档Agent 首先读取它决定要不要调用这个 skill、怎么执行。scripts/存放可独立运行的扫描脚本做确定性的、机器擅长的检查。rules/存放规则配置把检查项从代码里抽出来方便增删改。reports/定义输出模板确保格式化生成审计报告。examples/放一些示例 findings帮助 Agent 理解输出标准。2.2 SKILL.md 的 frontmatter 是触发命脉接触过 Claude Code 或 Codex skill 体系的读者应该知道SKILL.md 开头有一段 YAML frontmatterAgent 会用它来判断何时激活技能。这段写不好整个 skill 就是摆设。--- name: security-audit description: 对代码仓库执行安全审计初筛。当用户要求检查代码安全、发现漏洞、审计依赖风险、查找硬编码密钥、评估配置安全性时使用。适用于 git 仓库目录优先执行 scripts 下脚本结合 rules 规则进行语义分析输出分级审计报告。 ---description要写出触发场景和执行方式两层信息。第一层告诉 Agent 什么时候用第二层告诉 Agent 用了之后大致怎么干。我见过很多人把 description 写成华丽的功能介绍结果 Agent 在用户说帮我看看这个项目有没有安全问题时根本不触发原因就是 description 里没有出现安全漏洞审计这些词的自然表达。2.3 正文要像操作规程而不是散文SKILL.md 的正文部分我建议用明确的编号步骤来组织不要写大段背景说明。Agent 擅长按步骤执行但不喜欢从散文里自己提炼流程。我的正文结构大致是## 工作流程 当触发本 skill 后按以下顺序执行 1. 识别仓库类型和技术栈读取 package.json / pom.xml / requirements.txt / go.mod 等。 2. 依次运行 scripts/ 下的扫描脚本并将输出保存到审计工作区。 3. 结合 rules/ 下的规则文件对关键业务代码做语义审查重点检查注入类、认证授权类、敏感数据泄露类问题。 4. 汇总所有发现按 reports/audit_report_template.md 生成报告。 5. 对每一条发现标注严重级别、证据路径、修复建议。 ## 重要约束 - 不执行任何具有破坏性的操作。 - 不直接修改被审计的源代码只读分析。 - 发现疑似密钥时不要原样输出完整密钥内容只输出文件路径、行号和前几位字符。 - 报告必须区分确定性发现脚本扫描结果和建议性发现语义分析结果。重要约束这一段非常关键。Agent 默认倾向于完成用户请求如果你不明确告诉它碰到密钥只给前缀它可能把整个私钥贴进报告里。这类安全红线必须在 SKILL.md 里写死靠模型自觉是挡不住的。3. 让审计可执行检查项清单与规则引擎拆分3.1 审计范围怎么拆分类我参考了常见的安全审计框架OWASP ASVS、CWE Top 25结合日常项目里真实高频出现的问题把检查项分成六大类分类典型问题检测方式硬编码密钥API key、私钥、token 写在代码里正则 熵值检测依赖漏洞使用了存在已知 CVE 的版本lockfile 与漏洞库比对权限配置CORS 过宽、越权接口、默认口令配置规则匹配注入风险SQL 注入、命令注入、XSS语义分析 正则辅助敏感文件泄露.env、备份文件、日志文件被版本控制文件名模式匹配不安全加密弱哈希、硬编码 IV、自签证书代码模式匹配这不是一个穷尽的分类但对日常项目的初筛来说覆盖面已经足够。真正专业的渗透测试不靠这个但它能帮你快速定位大部分低级但致命的问题。3.2 把检查项写成 Agent 可读的 checklistSkill 里最不能缺的就是那份检查清单。Agent 用清单逐项核对比让它自由发挥可靠得多。我总结了一个优化后的审计 checklist如下每一行都是可执行的判断项[硬编码密钥] - 是否在代码中检测到 32 位的高熵字符串 - 是否在仓库中发现 .env / .pem / .key / id_rsa 文件 - 是否在日志语句中检测到疑似 token 的输出 [依赖漏洞] - 是否存在带 ^ 或 ~ 的版本范围依赖导致不可复现构建 - 是否存在已知可远程利用的 CVE 的依赖版本 - 是否存在不再维护且超过 2 年未更新的核心依赖 [权限配置] - CORS 配置是否允许任意来源Access-Control-Allow-Origin: * - 管理后台是否绑定内网地址 - 是否使用了默认数据库账号或默认管理口令 [注入风险] - 是否存在字符串拼接 SQL 且未使用参数化查询 - 是否存在直接拼接 shell 命令且未转义用户输入 - 是否存在将用户输入直接写入 HTML 且未转义的渲染 [敏感信息] - 是否将 debug / trace 级别的日志写入生产环境 - 是否将云服务凭证写入持久化配置文件 - 是否在公开目录保留备份文件.bak / .zip / .sql注意这个 checklist 不仅仅给人看更是给 Agent 的操作手册。Agent 读完之后会按清单逐项检查并在报告里标注每一项的通过/未通过/需要人工确认。这种 structured checklist free-form reasoning 的组合比直接让 Agent帮我找找安全问题有效太多。3.3 规则与脚本的分工最开始我尝试把扫描逻辑塞进 SKILL.md 的提示词里让 Agent 凭记忆执行结果发现三个问题提示词越长Agent 越容易在中间执行环节失焦正则表达式放在文档里很难维护不同 Agent 对同样的提示词理解和执行程度差异很大。后来我调整了策略确定性检查交给脚本语义理解交给 Agent。脚本负责扫——用正则和规则匹配找出可疑点输出结构化 JSONAgent 负责析——读脚本输出结合业务上下文判断哪些真有问题哪些是误报然后写报告。这个分工让整个 skill 的稳定性和可维护性都上了一个量级。4. scripts 层从看代码到扫描代码4.1 硬编码密钥扫描脚本硬编码密钥是安全审计里最高频的发现也是最适合自动化的。我写了一个scan_secrets.py原理不复杂先按规则匹配已知的密钥格式AWS AKIA、GitHub token、RSA private key 头再用香农熵检测高随机性字符串作为补充。#!/usr/bin/env python3 扫描仓库中的硬编码密钥。 import os import re import sys import json import math from pathlib import Path # 常见密钥格式的模式越具体越好减少误报 PATTERNS [ {name: AWS Access Key, regex: rAKIA[0-9A-Z]{16}}, {name: GitHub Token, regex: rghp_[0-9A-Za-z]{36}}, {name: Private Key, regex: r-----BEGIN (RSA|EC|OPENSSH) PRIVATE KEY-----}, {name: Slack Token, regex: rxox[baprs]-[0-9A-Za-z-]{10,}}, ] # 排除目录测试、示例、文档、构建产物 SKIP_DIRS {node_modules, vendor, .git, dist, build, test, tests, docs, examples, __pycache__} # 需要排除的样例文件很多项目会故意放一个 fake key 做 demo SKIP_FILES {*.md, *.example, *.sample, *.test.*} def shannon_entropy(data: str) - float: if not data: return 0.0 entropy 0.0 for c in set(data): p data.count(c) / len(data) entropy - p * math.log2(p) return entropy def scan_file(path: Path, findings: list): if any(path.match(p) for p in SKIP_FILES): return try: content path.read_text(encodingutf-8, errorsignore) except Exception: return for line_no, line in enumerate(content.splitlines(), 1): stripped line.strip() # 跳过注释行 if stripped.startswith(#) or stripped.startswith(//) or stripped.startswith(/*): continue for pat in PATTERNS: match re.search(pat[regex], line) if match: findings.append({ type: hardcoded_secret, pattern: pat[name], file: str(path), line: line_no, preview: match.group(0)[:8] ..., severity: high }) break # 熵值检测长度不小于 32 的字符串熵值高于 4.5 视为可疑 words re.findall(r[A-Za-z0-9_\-\.]{32,}, line) for word in words: if shannon_entropy(word) 4.5: findings.append({ type: high_entropy_string, pattern: entropy, file: str(path), line: line_no, preview: word[:8] ..., severity: medium }) def main(): root Path(sys.argv[1]) if len(sys.argv) 1 else Path.cwd() findings [] for dirpath, dirnames, filenames in os.walk(root): dirnames[:] [d for d in dirnames if d not in SKIP_DIRS] for fname in filenames: scan_file(Path(dirpath) / fname, findings) print(json.dumps(findings, indent2)) if __name__ __main__: main()熵值检测是双刃剑它能发现格式不常见的密钥但也会把一长串 base64 编码的文本误报为密钥。所以我给熵值检测的严重级别定的是 medium而精确匹配的是 high。这个级别划分在报告生成阶段非常有用。4.2 依赖漏洞检查脚本依赖漏洞的检测逻辑比密钥扫描更依赖外部数据。我没有自己维护漏洞库而是直接调用 OSV 的开源 API因为它的生态覆盖很广而且免费。核心思路读取项目的 lockfile解析出依赖名和版本号批量查询 OSV返回已知漏洞列表。#!/usr/bin/env python3 基于 OSV API 检测依赖漏洞。 import json import sys import urllib.request from pathlib import Path def parse_dependencies(lockfile: Path): 根据 lockfile 类型解析依赖列表。 deps [] try: if lockfile.name package-lock.json: data json.loads(lockfile.read_text(encodingutf-8)) for pkg_name, pkg_info in data.get(packages, {}).items(): version pkg_info.get(version) if version: deps.append({name: pkg_name.lstrip(node_modules/), version: version}) elif lockfile.name requirements.txt: for line in lockfile.read_text(encodingutf-8).splitlines(): line line.strip() if line and not line.startswith(#) and in line: name, version line.split(, 1) deps.append({name: name.strip(), version: version.strip()}) elif lockfile.name poetry.lock: data json.loads(lockfile.read_text(encodingutf-8)) for pkg in data.get(package, []): deps.append({name: pkg[name], version: pkg[version]}) elif lockfile.name go.mod: for line in lockfile.read_text(encodingutf-8).splitlines(): line line.strip() if line and not line.startswith((module, go , require (, ))): parts line.split() if len(parts) 2: deps.append({name: parts[0], version: parts[1].replace(// indirect, )}) except Exception as e: print(f解析失败{lockfile.name} - {e}, filesys.stderr) return deps def query_osv(dep_batches): 批量查询 OSV API。 results [] for batch in dep_batches: payload json.dumps({queries: batch}).encode(utf-8) req urllib.request.Request( https://api.osv.dev/v1/querybatch, datapayload, headers{Content-Type: application/json} ) try: with urllib.request.urlopen(req, timeout15) as resp: data json.loads(resp.read().decode(utf-8)) for i, item in enumerate(data.get(results, [])): if vulns in item: dep batch[i][package] for vuln in item[vulns]: results.append({ type: dependency_vuln, package: dep[name], version: dep[version], cve: vuln.get(id, 未知), severity: vuln.get(severity, [{}])[0].get(score, unknown) }) except Exception as e: print(fOSV 查询失败{e}, filesys.stderr) return results def main(): lockfiles list(Path.cwd().glob(package-lock.json)) lockfiles list(Path.cwd().glob(requirements.txt)) lockfiles list(Path.cwd().glob(poetry.lock)) lockfiles list(Path.cwd().glob(go.mod)) all_results [] for lf in lockfiles: deps parse_dependencies(lf) if not deps: continue # 每批最多 1000 个查询 batches [deps[i:i1000] for i in range(0, len(deps), 1000)] for batch in batches: queries [{package: {name: d[name], ecosystem: detect_ecosystem(lf)}, version: d[version]} for d in batch] all_results.extend(query_osv(queries)) print(json.dumps(all_results, indent2)) def detect_ecosystem(lockfile: Path) - str: if lockfile.name package-lock.json: return npm if lockfile.name requirements.txt or lockfile.name poetry.lock: return PyPI if lockfile.name go.mod: return Go return 依赖漏洞查询有几个实际注意点。一是 OSV API 的批量接口有大小限制依赖很多的项目要分批查我代码里做了 1000/批的处理。二是网络环境差异很大脚本必须容错查不到的时候不能整个审计流程挂掉要在报告里标注依赖查询未完成。三是 lockfile 比 manifest 文件更可信——package.json里写^1.2.3不代表实际装的版本package-lock.json才是真实依赖树所以脚本只认 lockfile。4.3 配置安全检查脚本配置类问题虽然不像密钥那么危急但很容易被忽略。我写了一个audit_config.py用 YAML 规则文件来描述检查项脚本只负责执行规则。这样做的好处是你想加一条检查规则时不用改代码只改 YAML。规则文件rules/config_rules.yaml的部分内容checks: - id: CORS_WILDCARD title: CORS 配置为通配符 severity: medium match_files: - **/*.py - **/*.js - **/*.ts - **/*.go patterns: - Access-Control-Allow-Origin - allow_origins.*\\* - id: DEBUG_ENABLED title: 生产环境开启了调试模式 severity: medium match_files: - **/settings.py - **/config/*.py - **/*.env* patterns: - DEBUG\\s*\\s*True - FLASK_DEBUG\\s*\\s*1 - id: DEFAULT_SECRET title: 使用了框架默认密钥 severity: high match_files: - **/*.py - **/*.js patterns: - SECRET_KEY\\s*\\s*[\](changeme|secret|default|your-secret-key)[\] - JWT_SECRET\\s*\\s*[\](changeme|secret|default)[\]脚本对应的执行逻辑#!/usr/bin/env python3 基于规则文件检查配置安全问题。 import json import re import sys from pathlib import Path import yaml def load_rules(path: Path): with open(path, encodingutf-8) as f: return yaml.safe_load(f)[checks] def match_file(file: Path, pattern: str) - bool: 简化的 glob 匹配实际可用 fnmatch。 import fnmatch return fnmatch.fnmatch(str(file), pattern) def scan_with_rules(root: Path, rules: list): # 收集需要检查的文件避免重复遍历 all_files [p for p in root.rglob(*) if p.is_file()] findings [] skip_dirs {node_modules, .git, dist, build, vendor, __pycache__} for rule in rules: patterns [re.compile(p) for p in rule[patterns]] for f in all_files: if any(part in skip_dirs for part in f.parts): continue if not any(match_file(f, mp) for mp in rule.get(match_files, [**/*])): continue try: content f.read_text(encodingutf-8, errorsignore) except Exception: continue for line_no, line in enumerate(content.splitlines(), 1): for pat in patterns: if pat.search(line): findings.append({ id: rule[id], title: rule[title], severity: rule[severity], file: str(f), line: line_no, preview: line.strip()[:80] }) break return findings def main(): root Path(sys.argv[1]) if len(sys.argv) 1 else Path.cwd() rules_path Path(sys.argv[2]) if len(sys.argv) 2 else Path(rules/config_rules.yaml) rules load_rules(rules_path) findings scan_with_rules(root, rules) print(json.dumps(findings, indent2)) if __name__ __main__: main()YAML 规则文件的好处是审计策略和代码逻辑分离。团队里有安全经验的同学可以直接改规则配置不需要动 Python 代码。我在实际使用中还把它接入了 CI用同一套规则扫描每次提交的代码变更形成持续的安全基线。4.4 脚本和 Agent 的分工红线最后必须强调一下脚本和 Agent 的分工。脚本输出的 JSON 是素材不是结论。Agent 拿到素材之后要做的不是照单全收而是判断文件路径是否在测试目录、示例目录、文档目录里是的话降低可信度判断高熵字符串是否可能是 base64 编码的图片片段或随机生成的数据而不是真正的密钥判断规则匹配的上下文比如allow_origins[*]出现在开发环境配置里和出现在生产环境配置里严重程度完全不同。这个语义去噪的过程是纯脚本做不到的也是 Agent 价值最大的地方。没有这层判断审计报告会充满误报让使用者逐渐失去信任。5. 接入 Agent 实测Claude Code / Codex / OpenCode 三种场景5.1 通用的 skill 加载方式不同 Agent 的 skill 加载机制大同小异核心都是把 skill 目录放到指定的配置目录下然后在对话里触发。以我的经验绝大多数 Agent 的配置目录结构是~/.claude/skills/ # Claude Code ~/.codex/skills/ # Codex ~/.config/opencode/skills/ # OpenCode直接把security-audit-skill目录复制过去即可。不过要注意部分 Agent 要求 skill 目录名和 SKILL.md 里的name字段一致否则可能加载失败。我的目录名就是security-audit-skillSKILL.md 里的name是security-audit名称前缀匹配一般没问题。5.2 Claude Code 里的实测路径Claude Code 对 skill 的感知相对智能它读 SKILL.md 的 description 部分来决定是否启用技能。我的使用方式很直接在项目目录里启动 Claude Code然后对话里说请对这个仓库执行安全审计初筛输出审计报告。Claude 会读取~/.claude/skills/security-audit-skill/SKILL.md激活技能然后按文档步骤工作。实测中它有几步做得比较好能自己判断从哪个 manifest 文件开始能在报告里区分脚本的确定性发现和它自己分析出的建议性发现还能把同类型的问题合并。需要注意的一点是Claude 的上下文窗口限制在大仓库里很容易触顶——我会在 SKILL.md 里加指令优先扫描与业务核心相关的目录把 vendor 目录和测试目录排除掉。5.3 Codex 场景的适配差异Codex 对 skill 的理解更命令式它倾向于把 SKILL.md 当成一份可执行的操作说明书。我在 Codex 里使用时会多给一步初始化指令你先读取 ~/.codex/skills/security-audit-skill/SKILL.md然后按其中的流程执行审计。Codex 的好处是代码生成能力和文件修改能力很强适合审计后的修复建议落地。比如 SKILL.md 里写着发现关键漏洞时给出修复补丁Codex 能直接生成 patch。但也有代价——它有时候会想帮忙直接改代码所以我在 SKILL.md 的约束里明确写了只读分析不修改文件否则真的会动代码。5.4 OpenCode 的接入方式OpenCode 的 skill 机制更灵活也更依赖插件生态。它支持从本地目录加载技能把 skill 放在~/.config/opencode/skills/之后在对话里可以用/skills查看可用技能列表确认security-audit-skill是否加载。实测下来 OpenCode 对 SKILL.md 里的步骤编号执行得很认真几乎是一步步照着来但它的推理能力比前两者弱一些所以对复杂业务逻辑的误报判定准确率稍低。三层 Agent 的实测对比如下项目Claude CodeCodexOpenCodeskill 自动触发好description 理解准确中等需要显式指令中等需确认加载状态语义去噪能力强强中等修复建议生成能生成描述性建议能直接生成补丁一般大仓库上下文控制需在 SKILL.md 中限制扫描范围相对稳定容易超限这些差异不是绝对的和模型版本、配置方式都有关系但大体趋势是Claude Code 适合开箱即用Codex 适合做审计 修复闭环OpenCode 适合对 skill 机制做深度定制。5.5 一次真实仓库审计过程回放为了验证 skill 的实战效果我拿一个大概 1.5 万行代码的 Django Vue 项目跑了一遍完整流程。这个项目是内部系统之前知道可能有安全问题但一直没有系统排查。运行 skill 之后脚本扫描到 3 处疑似硬编码密钥、5 个依赖漏洞、2 处 CORS 配置过宽Agent 语义分析部分额外发现了 1 处 SQL 拼接和 1 处越权接口逻辑。整个初筛花了不到两分钟报告是结构化输出的。拿到初筛结果后我用大概四十分钟逐一复查3 处疑似密钥里有 1 处是测试用的假密钥另外 2 处是真实的生产环境密钥5 个依赖漏洞里有 2 个是高危且已利用广泛另外 3 个影响面相对可控SQL 拼接问题经确认确实存在需要重构为参数化查询。如果没有 skill 自动初筛光是找出这些问题就可能需要大半天。而且 skill 把证据路径直接列出来复查时直接跳到文件这一行省掉了大量来回翻代码的时间。6. 调优与防误报我在真实仓库里踩过的坑6.1 上下文窗口被大仓库撑爆第一次在大型仓库上跑的时候skill 几乎失控了——Agent 试图逐个读取所有源码文件做语义分析很快就撞上了上下文窗口限制报告生成到一半就断开。后来我在 SKILL.md 里加了硬性规则只读取 manifest 文件、lockfile、配置文件、核心业务模块不逐行读取所有代码优先扫描src/、app/、backend/这类业务目录跳过静态资源、测试、文档、构建输出目录超过 500 个文件的仓库必须先跑脚本再基于脚本输出定位到具体文件做二次分析禁止全量语义审查。这个限制确实牺牲了一点分析覆盖面但换来了稳定性和可完成性。审计初筛本来就不是终极结论能保证跑完、能输出完整报告比什么都重要。6.2 误报重灾区测试代码和示例代码高熵字符串检测有一个绕不开的痛点很多项目会生成随机 UUID、session token、或者测试用的 fake secret这些东西会被扫成疑似硬编码密钥。一开始报告里全是这些严重拉低了可信度。我的解决思路有三层脚本层默认跳过test/、tests/、examples/、docs/目录但保留一个--include-tests参数需要时再扫规则层某些项目约定俗成用fake_、example_、dummy_前缀作为测试密钥我会在正则里加排除项Agent 层在 SKILL.md 里明确要求报告中的 high 级别发现必须经过 Agent 的人工语义判断确认不是测试代码后才算数。这三层过滤下来误报率从最初的 60% 左右降到了 15% 以内。剩下的 15% 属于不确定但值得看一眼的模糊地带本来也应该出现在初筛报告中。6.3 严重级别别平均主义早期的报告把所有问题都标成严重或高危结果就是没有重点接收人不在乎了。后来我引入了基于利用难度的分级逻辑级别定义处理时限P0可直接被外部利用且影响资产面大立即处理P1大概率可利用但需要一定前提条件1 周内P2有限条件下可利用或属于严重配置缺陷1 个月内P3潜在风险或加固建议排期处理比如硬编码 AWS 密钥如果对应的是生产环境 IAM 账号那就是 P0如果只是某个沙箱环境的测试 key降到 P2。依赖漏洞统一用 CVSS 分数来辅助定级高分且被广泛利用的就是 P0。Agent 在报告里不仅仅是列出问题还会给出建议的优先处理顺序这个对工程团队非常实用。6.4 安全边界的最后一道闸再强调一次skill 做的只是初筛整套流程跑完不能替代安全工程师的复核。我见过有人完全信任自动化报告把 P0 问题直接发给业务方要求立即修复结果误报引发信任危机。我的做法是所有 P0 和 P1 的发现在对外发布前必须人工验证一遍——要么自己看代码确认要么跑一次复现脚本要么拿着证据去找对应模块的负责人确认。自动化负责扩大搜索半径人负责扣动扳机这个边界在团队协作里尤其重要。最后分享一个小技巧。审计报告生成后我会让 Agent 把 P0 和 P1 的问题整理成一份 Markdown 清单直接贴进迭代排期的需求池每条都带着文件路径、问题描述、修复建议和预计改动范围。这样安全审计的产出一来能被跟踪闭环二来也方便其他开发者拿过去直接排期。多跑几轮之后你能明显感觉到团队的代码质量基线在往上走因为同类问题被拦截得越来越早。
从安全审计到 AI Agent Skill：打造自动化代码初筛的完整方案
做安全审计这件事重复劳动远比想象中多。每次拿到一个代码库先要扒依赖、扫密钥、查配置、翻权限一趟下来光是信息收集就得花掉大半天真正需要人脑判断的部分反而被压缩。后来我把这套流程固化成了一个 AI Agent 的 skill让 Claude Code 这类工具先做一轮初筛我再聚焦确认效率提升非常明显。这篇就聊聊我编写 security-audit-skill 的完整思路、目录设计、脚本落地和实测踩坑希望能给正在做类似方向的开发者一些参考。security-audit-skill 不是一个渗透测试工具也不替代专业安全工程师的判断它是一个结构化的审计方法论封装把安全审计中可重复、可量化的部分交给 Agent 自动化执行把需要语义理解和业务判断的部分保留给人。适合本身熟悉开发、又需要经常做代码安全自查的工程师也适合正在研究 Agent skill 写法、想给自己的编程助手扩展能力的开发者。1. security-audit-skill 到底解决什么问题1.1 安全审计里的可复用流程在决定写这个 skill 之前我复盘了过去做过的几十次代码安全审计发现不管是前端项目还是后端服务流程高度相似先收集项目结构和技术栈信息然后扫描硬编码密钥、检查依赖漏洞、排查危险的权限配置再针对业务代码做注入类风险的语义分析最后整理出一份分级报告。这套流程完全可以标准化。问题在于这些步骤分散在多个工具和多个命令里每次审计都要重新拼接一遍。gitleaks 扫密钥、npm audit 或 pip-audit 查依赖、grep 翻配置文件再把结果人工汇总。Agent 的能力恰恰适合做这件事——它能理解审计目标能编排工具链能按固定格式输出报告。所以我把流程、规则、脚本、报告模板全部塞进一个 skill 里让 Agent 一次性完成信息收集 初筛 报告生成。1.2 这个 skill 的边界定位最开始我犯过一个错误想让 skill 做太多事包括自动利用漏洞、生成攻击 payload结果既不安全也不可控。后来把边界收敛成三条代码级与配置级审计检查的是代码仓库、依赖清单、环境配置、权限文件不涉及对线上系统的主动探测。自动化初筛 辅助决策skill 负责找出可疑点比如疑似硬编码的密钥、已知 CVE 的依赖版本、过宽的 CORS 配置但最终是否算漏洞、风险有多大需要人来判断。可解释、可追溯每一条发现都要附带证据位置不能只给结论不然没法核验。这个边界让 skill 在有用和失控之间找到了平衡点。它是放大审计员效率的工具而不是替代审计员脑子的黑盒。1.3 谁适合直接拿它上手如果你满足下面任意一条这个 skill 的思路值得参考一是经常做项目自查、交付前安全评估的开发者二是负责团队代码安全规范落地的工程效率岗三是在研究 Agent skill 怎么写、想让 AI 编程助手承担更多专业判断的实践者。就算你没有完整的安全背景只要理解基本的漏洞类型这个 skill 也能帮你建立一条可执行的审计基线。2. Skill 目录结构与 SKILL.md 的主干设计2.1 一套清晰的目录布局Agent skill 的落地形态并不神秘本质上就是一个带规范文档和辅助脚本的目录。我的 security-audit-skill 最终长这样security-audit-skill/ ├── SKILL.md ├── scripts/ │ ├── scan_secrets.py │ ├── check_deps.py │ └── audit_config.py ├── rules/ │ ├── secret_patterns.yaml │ ├── config_rules.yaml │ └── dependency_rules.yaml ├── reports/ │ └── audit_report_template.md └── examples/ └── sample_findings.mdSKILL.md是入口文档Agent 首先读取它决定要不要调用这个 skill、怎么执行。scripts/存放可独立运行的扫描脚本做确定性的、机器擅长的检查。rules/存放规则配置把检查项从代码里抽出来方便增删改。reports/定义输出模板确保格式化生成审计报告。examples/放一些示例 findings帮助 Agent 理解输出标准。2.2 SKILL.md 的 frontmatter 是触发命脉接触过 Claude Code 或 Codex skill 体系的读者应该知道SKILL.md 开头有一段 YAML frontmatterAgent 会用它来判断何时激活技能。这段写不好整个 skill 就是摆设。--- name: security-audit description: 对代码仓库执行安全审计初筛。当用户要求检查代码安全、发现漏洞、审计依赖风险、查找硬编码密钥、评估配置安全性时使用。适用于 git 仓库目录优先执行 scripts 下脚本结合 rules 规则进行语义分析输出分级审计报告。 ---description要写出触发场景和执行方式两层信息。第一层告诉 Agent 什么时候用第二层告诉 Agent 用了之后大致怎么干。我见过很多人把 description 写成华丽的功能介绍结果 Agent 在用户说帮我看看这个项目有没有安全问题时根本不触发原因就是 description 里没有出现安全漏洞审计这些词的自然表达。2.3 正文要像操作规程而不是散文SKILL.md 的正文部分我建议用明确的编号步骤来组织不要写大段背景说明。Agent 擅长按步骤执行但不喜欢从散文里自己提炼流程。我的正文结构大致是## 工作流程 当触发本 skill 后按以下顺序执行 1. 识别仓库类型和技术栈读取 package.json / pom.xml / requirements.txt / go.mod 等。 2. 依次运行 scripts/ 下的扫描脚本并将输出保存到审计工作区。 3. 结合 rules/ 下的规则文件对关键业务代码做语义审查重点检查注入类、认证授权类、敏感数据泄露类问题。 4. 汇总所有发现按 reports/audit_report_template.md 生成报告。 5. 对每一条发现标注严重级别、证据路径、修复建议。 ## 重要约束 - 不执行任何具有破坏性的操作。 - 不直接修改被审计的源代码只读分析。 - 发现疑似密钥时不要原样输出完整密钥内容只输出文件路径、行号和前几位字符。 - 报告必须区分确定性发现脚本扫描结果和建议性发现语义分析结果。重要约束这一段非常关键。Agent 默认倾向于完成用户请求如果你不明确告诉它碰到密钥只给前缀它可能把整个私钥贴进报告里。这类安全红线必须在 SKILL.md 里写死靠模型自觉是挡不住的。3. 让审计可执行检查项清单与规则引擎拆分3.1 审计范围怎么拆分类我参考了常见的安全审计框架OWASP ASVS、CWE Top 25结合日常项目里真实高频出现的问题把检查项分成六大类分类典型问题检测方式硬编码密钥API key、私钥、token 写在代码里正则 熵值检测依赖漏洞使用了存在已知 CVE 的版本lockfile 与漏洞库比对权限配置CORS 过宽、越权接口、默认口令配置规则匹配注入风险SQL 注入、命令注入、XSS语义分析 正则辅助敏感文件泄露.env、备份文件、日志文件被版本控制文件名模式匹配不安全加密弱哈希、硬编码 IV、自签证书代码模式匹配这不是一个穷尽的分类但对日常项目的初筛来说覆盖面已经足够。真正专业的渗透测试不靠这个但它能帮你快速定位大部分低级但致命的问题。3.2 把检查项写成 Agent 可读的 checklistSkill 里最不能缺的就是那份检查清单。Agent 用清单逐项核对比让它自由发挥可靠得多。我总结了一个优化后的审计 checklist如下每一行都是可执行的判断项[硬编码密钥] - 是否在代码中检测到 32 位的高熵字符串 - 是否在仓库中发现 .env / .pem / .key / id_rsa 文件 - 是否在日志语句中检测到疑似 token 的输出 [依赖漏洞] - 是否存在带 ^ 或 ~ 的版本范围依赖导致不可复现构建 - 是否存在已知可远程利用的 CVE 的依赖版本 - 是否存在不再维护且超过 2 年未更新的核心依赖 [权限配置] - CORS 配置是否允许任意来源Access-Control-Allow-Origin: * - 管理后台是否绑定内网地址 - 是否使用了默认数据库账号或默认管理口令 [注入风险] - 是否存在字符串拼接 SQL 且未使用参数化查询 - 是否存在直接拼接 shell 命令且未转义用户输入 - 是否存在将用户输入直接写入 HTML 且未转义的渲染 [敏感信息] - 是否将 debug / trace 级别的日志写入生产环境 - 是否将云服务凭证写入持久化配置文件 - 是否在公开目录保留备份文件.bak / .zip / .sql注意这个 checklist 不仅仅给人看更是给 Agent 的操作手册。Agent 读完之后会按清单逐项检查并在报告里标注每一项的通过/未通过/需要人工确认。这种 structured checklist free-form reasoning 的组合比直接让 Agent帮我找找安全问题有效太多。3.3 规则与脚本的分工最开始我尝试把扫描逻辑塞进 SKILL.md 的提示词里让 Agent 凭记忆执行结果发现三个问题提示词越长Agent 越容易在中间执行环节失焦正则表达式放在文档里很难维护不同 Agent 对同样的提示词理解和执行程度差异很大。后来我调整了策略确定性检查交给脚本语义理解交给 Agent。脚本负责扫——用正则和规则匹配找出可疑点输出结构化 JSONAgent 负责析——读脚本输出结合业务上下文判断哪些真有问题哪些是误报然后写报告。这个分工让整个 skill 的稳定性和可维护性都上了一个量级。4. scripts 层从看代码到扫描代码4.1 硬编码密钥扫描脚本硬编码密钥是安全审计里最高频的发现也是最适合自动化的。我写了一个scan_secrets.py原理不复杂先按规则匹配已知的密钥格式AWS AKIA、GitHub token、RSA private key 头再用香农熵检测高随机性字符串作为补充。#!/usr/bin/env python3 扫描仓库中的硬编码密钥。 import os import re import sys import json import math from pathlib import Path # 常见密钥格式的模式越具体越好减少误报 PATTERNS [ {name: AWS Access Key, regex: rAKIA[0-9A-Z]{16}}, {name: GitHub Token, regex: rghp_[0-9A-Za-z]{36}}, {name: Private Key, regex: r-----BEGIN (RSA|EC|OPENSSH) PRIVATE KEY-----}, {name: Slack Token, regex: rxox[baprs]-[0-9A-Za-z-]{10,}}, ] # 排除目录测试、示例、文档、构建产物 SKIP_DIRS {node_modules, vendor, .git, dist, build, test, tests, docs, examples, __pycache__} # 需要排除的样例文件很多项目会故意放一个 fake key 做 demo SKIP_FILES {*.md, *.example, *.sample, *.test.*} def shannon_entropy(data: str) - float: if not data: return 0.0 entropy 0.0 for c in set(data): p data.count(c) / len(data) entropy - p * math.log2(p) return entropy def scan_file(path: Path, findings: list): if any(path.match(p) for p in SKIP_FILES): return try: content path.read_text(encodingutf-8, errorsignore) except Exception: return for line_no, line in enumerate(content.splitlines(), 1): stripped line.strip() # 跳过注释行 if stripped.startswith(#) or stripped.startswith(//) or stripped.startswith(/*): continue for pat in PATTERNS: match re.search(pat[regex], line) if match: findings.append({ type: hardcoded_secret, pattern: pat[name], file: str(path), line: line_no, preview: match.group(0)[:8] ..., severity: high }) break # 熵值检测长度不小于 32 的字符串熵值高于 4.5 视为可疑 words re.findall(r[A-Za-z0-9_\-\.]{32,}, line) for word in words: if shannon_entropy(word) 4.5: findings.append({ type: high_entropy_string, pattern: entropy, file: str(path), line: line_no, preview: word[:8] ..., severity: medium }) def main(): root Path(sys.argv[1]) if len(sys.argv) 1 else Path.cwd() findings [] for dirpath, dirnames, filenames in os.walk(root): dirnames[:] [d for d in dirnames if d not in SKIP_DIRS] for fname in filenames: scan_file(Path(dirpath) / fname, findings) print(json.dumps(findings, indent2)) if __name__ __main__: main()熵值检测是双刃剑它能发现格式不常见的密钥但也会把一长串 base64 编码的文本误报为密钥。所以我给熵值检测的严重级别定的是 medium而精确匹配的是 high。这个级别划分在报告生成阶段非常有用。4.2 依赖漏洞检查脚本依赖漏洞的检测逻辑比密钥扫描更依赖外部数据。我没有自己维护漏洞库而是直接调用 OSV 的开源 API因为它的生态覆盖很广而且免费。核心思路读取项目的 lockfile解析出依赖名和版本号批量查询 OSV返回已知漏洞列表。#!/usr/bin/env python3 基于 OSV API 检测依赖漏洞。 import json import sys import urllib.request from pathlib import Path def parse_dependencies(lockfile: Path): 根据 lockfile 类型解析依赖列表。 deps [] try: if lockfile.name package-lock.json: data json.loads(lockfile.read_text(encodingutf-8)) for pkg_name, pkg_info in data.get(packages, {}).items(): version pkg_info.get(version) if version: deps.append({name: pkg_name.lstrip(node_modules/), version: version}) elif lockfile.name requirements.txt: for line in lockfile.read_text(encodingutf-8).splitlines(): line line.strip() if line and not line.startswith(#) and in line: name, version line.split(, 1) deps.append({name: name.strip(), version: version.strip()}) elif lockfile.name poetry.lock: data json.loads(lockfile.read_text(encodingutf-8)) for pkg in data.get(package, []): deps.append({name: pkg[name], version: pkg[version]}) elif lockfile.name go.mod: for line in lockfile.read_text(encodingutf-8).splitlines(): line line.strip() if line and not line.startswith((module, go , require (, ))): parts line.split() if len(parts) 2: deps.append({name: parts[0], version: parts[1].replace(// indirect, )}) except Exception as e: print(f解析失败{lockfile.name} - {e}, filesys.stderr) return deps def query_osv(dep_batches): 批量查询 OSV API。 results [] for batch in dep_batches: payload json.dumps({queries: batch}).encode(utf-8) req urllib.request.Request( https://api.osv.dev/v1/querybatch, datapayload, headers{Content-Type: application/json} ) try: with urllib.request.urlopen(req, timeout15) as resp: data json.loads(resp.read().decode(utf-8)) for i, item in enumerate(data.get(results, [])): if vulns in item: dep batch[i][package] for vuln in item[vulns]: results.append({ type: dependency_vuln, package: dep[name], version: dep[version], cve: vuln.get(id, 未知), severity: vuln.get(severity, [{}])[0].get(score, unknown) }) except Exception as e: print(fOSV 查询失败{e}, filesys.stderr) return results def main(): lockfiles list(Path.cwd().glob(package-lock.json)) lockfiles list(Path.cwd().glob(requirements.txt)) lockfiles list(Path.cwd().glob(poetry.lock)) lockfiles list(Path.cwd().glob(go.mod)) all_results [] for lf in lockfiles: deps parse_dependencies(lf) if not deps: continue # 每批最多 1000 个查询 batches [deps[i:i1000] for i in range(0, len(deps), 1000)] for batch in batches: queries [{package: {name: d[name], ecosystem: detect_ecosystem(lf)}, version: d[version]} for d in batch] all_results.extend(query_osv(queries)) print(json.dumps(all_results, indent2)) def detect_ecosystem(lockfile: Path) - str: if lockfile.name package-lock.json: return npm if lockfile.name requirements.txt or lockfile.name poetry.lock: return PyPI if lockfile.name go.mod: return Go return 依赖漏洞查询有几个实际注意点。一是 OSV API 的批量接口有大小限制依赖很多的项目要分批查我代码里做了 1000/批的处理。二是网络环境差异很大脚本必须容错查不到的时候不能整个审计流程挂掉要在报告里标注依赖查询未完成。三是 lockfile 比 manifest 文件更可信——package.json里写^1.2.3不代表实际装的版本package-lock.json才是真实依赖树所以脚本只认 lockfile。4.3 配置安全检查脚本配置类问题虽然不像密钥那么危急但很容易被忽略。我写了一个audit_config.py用 YAML 规则文件来描述检查项脚本只负责执行规则。这样做的好处是你想加一条检查规则时不用改代码只改 YAML。规则文件rules/config_rules.yaml的部分内容checks: - id: CORS_WILDCARD title: CORS 配置为通配符 severity: medium match_files: - **/*.py - **/*.js - **/*.ts - **/*.go patterns: - Access-Control-Allow-Origin - allow_origins.*\\* - id: DEBUG_ENABLED title: 生产环境开启了调试模式 severity: medium match_files: - **/settings.py - **/config/*.py - **/*.env* patterns: - DEBUG\\s*\\s*True - FLASK_DEBUG\\s*\\s*1 - id: DEFAULT_SECRET title: 使用了框架默认密钥 severity: high match_files: - **/*.py - **/*.js patterns: - SECRET_KEY\\s*\\s*[\](changeme|secret|default|your-secret-key)[\] - JWT_SECRET\\s*\\s*[\](changeme|secret|default)[\]脚本对应的执行逻辑#!/usr/bin/env python3 基于规则文件检查配置安全问题。 import json import re import sys from pathlib import Path import yaml def load_rules(path: Path): with open(path, encodingutf-8) as f: return yaml.safe_load(f)[checks] def match_file(file: Path, pattern: str) - bool: 简化的 glob 匹配实际可用 fnmatch。 import fnmatch return fnmatch.fnmatch(str(file), pattern) def scan_with_rules(root: Path, rules: list): # 收集需要检查的文件避免重复遍历 all_files [p for p in root.rglob(*) if p.is_file()] findings [] skip_dirs {node_modules, .git, dist, build, vendor, __pycache__} for rule in rules: patterns [re.compile(p) for p in rule[patterns]] for f in all_files: if any(part in skip_dirs for part in f.parts): continue if not any(match_file(f, mp) for mp in rule.get(match_files, [**/*])): continue try: content f.read_text(encodingutf-8, errorsignore) except Exception: continue for line_no, line in enumerate(content.splitlines(), 1): for pat in patterns: if pat.search(line): findings.append({ id: rule[id], title: rule[title], severity: rule[severity], file: str(f), line: line_no, preview: line.strip()[:80] }) break return findings def main(): root Path(sys.argv[1]) if len(sys.argv) 1 else Path.cwd() rules_path Path(sys.argv[2]) if len(sys.argv) 2 else Path(rules/config_rules.yaml) rules load_rules(rules_path) findings scan_with_rules(root, rules) print(json.dumps(findings, indent2)) if __name__ __main__: main()YAML 规则文件的好处是审计策略和代码逻辑分离。团队里有安全经验的同学可以直接改规则配置不需要动 Python 代码。我在实际使用中还把它接入了 CI用同一套规则扫描每次提交的代码变更形成持续的安全基线。4.4 脚本和 Agent 的分工红线最后必须强调一下脚本和 Agent 的分工。脚本输出的 JSON 是素材不是结论。Agent 拿到素材之后要做的不是照单全收而是判断文件路径是否在测试目录、示例目录、文档目录里是的话降低可信度判断高熵字符串是否可能是 base64 编码的图片片段或随机生成的数据而不是真正的密钥判断规则匹配的上下文比如allow_origins[*]出现在开发环境配置里和出现在生产环境配置里严重程度完全不同。这个语义去噪的过程是纯脚本做不到的也是 Agent 价值最大的地方。没有这层判断审计报告会充满误报让使用者逐渐失去信任。5. 接入 Agent 实测Claude Code / Codex / OpenCode 三种场景5.1 通用的 skill 加载方式不同 Agent 的 skill 加载机制大同小异核心都是把 skill 目录放到指定的配置目录下然后在对话里触发。以我的经验绝大多数 Agent 的配置目录结构是~/.claude/skills/ # Claude Code ~/.codex/skills/ # Codex ~/.config/opencode/skills/ # OpenCode直接把security-audit-skill目录复制过去即可。不过要注意部分 Agent 要求 skill 目录名和 SKILL.md 里的name字段一致否则可能加载失败。我的目录名就是security-audit-skillSKILL.md 里的name是security-audit名称前缀匹配一般没问题。5.2 Claude Code 里的实测路径Claude Code 对 skill 的感知相对智能它读 SKILL.md 的 description 部分来决定是否启用技能。我的使用方式很直接在项目目录里启动 Claude Code然后对话里说请对这个仓库执行安全审计初筛输出审计报告。Claude 会读取~/.claude/skills/security-audit-skill/SKILL.md激活技能然后按文档步骤工作。实测中它有几步做得比较好能自己判断从哪个 manifest 文件开始能在报告里区分脚本的确定性发现和它自己分析出的建议性发现还能把同类型的问题合并。需要注意的一点是Claude 的上下文窗口限制在大仓库里很容易触顶——我会在 SKILL.md 里加指令优先扫描与业务核心相关的目录把 vendor 目录和测试目录排除掉。5.3 Codex 场景的适配差异Codex 对 skill 的理解更命令式它倾向于把 SKILL.md 当成一份可执行的操作说明书。我在 Codex 里使用时会多给一步初始化指令你先读取 ~/.codex/skills/security-audit-skill/SKILL.md然后按其中的流程执行审计。Codex 的好处是代码生成能力和文件修改能力很强适合审计后的修复建议落地。比如 SKILL.md 里写着发现关键漏洞时给出修复补丁Codex 能直接生成 patch。但也有代价——它有时候会想帮忙直接改代码所以我在 SKILL.md 的约束里明确写了只读分析不修改文件否则真的会动代码。5.4 OpenCode 的接入方式OpenCode 的 skill 机制更灵活也更依赖插件生态。它支持从本地目录加载技能把 skill 放在~/.config/opencode/skills/之后在对话里可以用/skills查看可用技能列表确认security-audit-skill是否加载。实测下来 OpenCode 对 SKILL.md 里的步骤编号执行得很认真几乎是一步步照着来但它的推理能力比前两者弱一些所以对复杂业务逻辑的误报判定准确率稍低。三层 Agent 的实测对比如下项目Claude CodeCodexOpenCodeskill 自动触发好description 理解准确中等需要显式指令中等需确认加载状态语义去噪能力强强中等修复建议生成能生成描述性建议能直接生成补丁一般大仓库上下文控制需在 SKILL.md 中限制扫描范围相对稳定容易超限这些差异不是绝对的和模型版本、配置方式都有关系但大体趋势是Claude Code 适合开箱即用Codex 适合做审计 修复闭环OpenCode 适合对 skill 机制做深度定制。5.5 一次真实仓库审计过程回放为了验证 skill 的实战效果我拿一个大概 1.5 万行代码的 Django Vue 项目跑了一遍完整流程。这个项目是内部系统之前知道可能有安全问题但一直没有系统排查。运行 skill 之后脚本扫描到 3 处疑似硬编码密钥、5 个依赖漏洞、2 处 CORS 配置过宽Agent 语义分析部分额外发现了 1 处 SQL 拼接和 1 处越权接口逻辑。整个初筛花了不到两分钟报告是结构化输出的。拿到初筛结果后我用大概四十分钟逐一复查3 处疑似密钥里有 1 处是测试用的假密钥另外 2 处是真实的生产环境密钥5 个依赖漏洞里有 2 个是高危且已利用广泛另外 3 个影响面相对可控SQL 拼接问题经确认确实存在需要重构为参数化查询。如果没有 skill 自动初筛光是找出这些问题就可能需要大半天。而且 skill 把证据路径直接列出来复查时直接跳到文件这一行省掉了大量来回翻代码的时间。6. 调优与防误报我在真实仓库里踩过的坑6.1 上下文窗口被大仓库撑爆第一次在大型仓库上跑的时候skill 几乎失控了——Agent 试图逐个读取所有源码文件做语义分析很快就撞上了上下文窗口限制报告生成到一半就断开。后来我在 SKILL.md 里加了硬性规则只读取 manifest 文件、lockfile、配置文件、核心业务模块不逐行读取所有代码优先扫描src/、app/、backend/这类业务目录跳过静态资源、测试、文档、构建输出目录超过 500 个文件的仓库必须先跑脚本再基于脚本输出定位到具体文件做二次分析禁止全量语义审查。这个限制确实牺牲了一点分析覆盖面但换来了稳定性和可完成性。审计初筛本来就不是终极结论能保证跑完、能输出完整报告比什么都重要。6.2 误报重灾区测试代码和示例代码高熵字符串检测有一个绕不开的痛点很多项目会生成随机 UUID、session token、或者测试用的 fake secret这些东西会被扫成疑似硬编码密钥。一开始报告里全是这些严重拉低了可信度。我的解决思路有三层脚本层默认跳过test/、tests/、examples/、docs/目录但保留一个--include-tests参数需要时再扫规则层某些项目约定俗成用fake_、example_、dummy_前缀作为测试密钥我会在正则里加排除项Agent 层在 SKILL.md 里明确要求报告中的 high 级别发现必须经过 Agent 的人工语义判断确认不是测试代码后才算数。这三层过滤下来误报率从最初的 60% 左右降到了 15% 以内。剩下的 15% 属于不确定但值得看一眼的模糊地带本来也应该出现在初筛报告中。6.3 严重级别别平均主义早期的报告把所有问题都标成严重或高危结果就是没有重点接收人不在乎了。后来我引入了基于利用难度的分级逻辑级别定义处理时限P0可直接被外部利用且影响资产面大立即处理P1大概率可利用但需要一定前提条件1 周内P2有限条件下可利用或属于严重配置缺陷1 个月内P3潜在风险或加固建议排期处理比如硬编码 AWS 密钥如果对应的是生产环境 IAM 账号那就是 P0如果只是某个沙箱环境的测试 key降到 P2。依赖漏洞统一用 CVSS 分数来辅助定级高分且被广泛利用的就是 P0。Agent 在报告里不仅仅是列出问题还会给出建议的优先处理顺序这个对工程团队非常实用。6.4 安全边界的最后一道闸再强调一次skill 做的只是初筛整套流程跑完不能替代安全工程师的复核。我见过有人完全信任自动化报告把 P0 问题直接发给业务方要求立即修复结果误报引发信任危机。我的做法是所有 P0 和 P1 的发现在对外发布前必须人工验证一遍——要么自己看代码确认要么跑一次复现脚本要么拿着证据去找对应模块的负责人确认。自动化负责扩大搜索半径人负责扣动扳机这个边界在团队协作里尤其重要。最后分享一个小技巧。审计报告生成后我会让 Agent 把 P0 和 P1 的问题整理成一份 Markdown 清单直接贴进迭代排期的需求池每条都带着文件路径、问题描述、修复建议和预计改动范围。这样安全审计的产出一来能被跟踪闭环二来也方便其他开发者拿过去直接排期。多跑几轮之后你能明显感觉到团队的代码质量基线在往上走因为同类问题被拦截得越来越早。
