Repo Security Audit 用户指南
Repo Security Audit 是一个仓库安全审计 skill，用来检查源码风险、硬编码凭据、Git 历史泄露和依赖漏洞。 它会生成 HTML 报告，并按 P0 到 P3 标出上线前必须处理的事项。
开发、测试、交付、上线审批和安全复核人员。
上线前使用“上线前扫描”，覆盖当前代码和最近 Git 历史。
一份自包含 HTML 报告，必要时可保留 JSON 和 SARIF。
功能说明
这个 skill 的核心问题是：这个仓库能不能上线，哪些问题必须立即修，哪些可以延后处理。
- 源码规则扫描：检查危险配置、token 进入 URL、常见 source 到 sink 风险和框架反模式。
- 凭据扫描：检查当前文件和 Git 历史中的 API key、token、secret、高熵字符串。
- 依赖漏洞扫描：通过依赖名和版本识别公开漏洞，并结合运行时引用做优先级判断。
- 语义复审：对高风险文件做人工智能复审，补充自动规则不容易发现的授权、流程和 XSS 风险。
- 报告输出：生成 HTML 报告，说明定位、风险原因、验真伪方法、常见误报和修复优先级。
使用前准备
正式扫描前建议先做预检。扫描器越完整，报告覆盖率越高；离线模式隐私更强，但能力会下降。
建议安装完整扫描器
最佳实践是让 AI 先跑预检。如果缺少 Semgrep、gitleaks 或 osv-scanner，正式上线前建议选择“安装完整扫描器并继续”。
扫描器各自负责什么
Semgrep 负责源码规则，gitleaks 负责凭据和历史泄露，osv-scanner 负责依赖漏洞。
离线模式的边界
离线扫描不会联网、不会查 OSV、不会安装工具、不会调用外部模型。适合敏感仓库，但依赖漏洞和语义复审覆盖会降低。
历史凭据先吊销
如果报告提示 Git 历史里有真实 token，先吊销或轮换凭据，再考虑清理 Git 历史。
推荐流程
你不需要记命令细节。告诉 AI 目标和扫描方式，AI 应先预检，再按模式执行扫描。
预检扫描器
AI 会检查 PATH 中是否已有 Semgrep、gitleaks、osv-scanner。缺少工具时，应先让你选择安装、降级或离线扫描。
选择扫描方式
日常自查用“当前代码扫描”；上线前用“上线前扫描”；交付、开源、发布前用“完整历史扫描”。
生成安全报告
扫描完成后，AI 应给出 HTML 报告路径，并总结 P0/P1 是否阻断上线。
处理 P0 和 P1
P0/P1 需要人工确认真伪和可触达性。真实凭据要先吊销，依赖漏洞要确认是否在运行时代码中使用。
扫描方式和 AI 话术
给用户看时，优先使用“怎么对 AI 说”。参数只是给维护者核对。
当前代码扫描
只检查当前工作树，不扫 Git 历史。适合改完代码后快速确认当前文件是否还有风险。
用 repo-security-audit 扫一下。
模式：当前代码扫描，只看当前工作树，不扫 Git 历史。
不要 build。--history none --quick上线前扫描
检查当前代码和最近 Git 历史。适合判断是否存在上线阻断项。
用 repo-security-audit 做上线前安全扫描。
模式：上线前扫描，检查当前代码和最近 Git 历史。
如果缺少扫描器，先告诉我缺什么，再让我选择安装、降级或离线扫描。
不要 build。--history recent完整历史扫描
检查当前代码和完整 Git 历史。适合发布、交付、开源、安全审计前使用。
用 repo-security-audit 做发布前完整安全扫描。
模式：完整历史扫描，当前代码和完整 Git 历史都要扫。
重点关注历史凭据、依赖漏洞、P0/P1 阻断项。
不要 build。--history full离线扫描
零外发扫描。适合源码、依赖信息或高风险片段不能离开本机的仓库。
用 repo-security-audit 扫一下。
模式：离线扫描，零外发。
不要访问网络，不查 OSV，不安装工具，不调用外部模型。
不要 build。--offlineCI 扫描
保留机器可读产物，并在 P0/P1 出现时让流水线失败。
用 repo-security-audit 跑 CI 安全扫描。
模式：CI 扫描，保留 HTML、JSON、SARIF。
如果出现 P0 或 P1，让命令返回失败码。
不要 build。--artifacts --fail-on p1模式和参数对照
这张表给维护者确认。普通用户只需要选择扫描方式，不需要记参数。
| 扫描方式 | 适用场景 | 关键参数 |
|---|---|---|
| 当前代码扫描 | 日常自查，只看当前工作树。 | --history none --quick |
| 上线前扫描 | 上线前默认检查，覆盖当前代码和最近历史。 | --history recent |
| 完整历史扫描 | 发布、交付、开源前的严格检查。 | --history full |
| 离线扫描 | 敏感仓库，要求零外发。 | --offline |
| CI 扫描 | 需要 JSON/SARIF 和流水线失败门禁。 | --artifacts --fail-on p1 |
报告解读
先看 P0 和 P1。P3 数量多不一定代表风险大，很多 P3 是第三方库、构建产物或需要人工确认的低优先级信号。
阻断上线。真实凭据泄露、可触达高危链路、必须马上处理。
强烈建议短期处理。运行时高危依赖、token 进 URL 等。
建议排期。语义风险、用途未知的高危依赖、需要补验证的问题。
信息加固。构建产物、第三方库、误报可能性较高的命中。
常见问题
第一次给团队成员使用时，可以直接让他们阅读这一节。
为什么报告里会出现已经删除的文件？
因为上线前扫描会检查最近 Git 历史。文件删除后仍存在于 Git 对象中，如果旧版本里有凭据，仓库访问者仍可能拿到。
扫描器一定要安装吗？
不是必须，但正式上线前建议安装。完整扫描器覆盖源码规则、凭据扫描和依赖漏洞；降级扫描只能提供较基础的结果。
离线扫描是不是最推荐？
离线扫描隐私最强，但覆盖率较低。只有在源码、依赖名或高风险片段不能外发时，才建议默认使用离线模式。
发现历史凭据后应该先做什么？
先吊销或轮换凭据，再考虑清理 Git 历史。清理历史不能保证旧值没有被人看过，所以不能替代凭据轮换。