1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | scan-secrets（GitGuardian Agent Skills 套件之一） |
| 作者/维护者 | GitGuardian SA（官方组织） |
| 来源链接 | https://github.com/GitGuardian/agent-skills/tree/main/skills/scan-secrets |
| 许可证 | MIT（GitHub API 获取） |
| GitHub Stars | 4（GitHub API；该数字为整个 agent-skills 仓库整体，仓库内共打包 6 个技能，不代表 scan-secrets 单个技能自身热度） |
| Forks | 2（GitHub API） |
| 最新版本 | v0.5.0，发布于 2026-07-06（GitHub Releases） |
| 安装方式 | Claude Code / Codex 插件市场一条命令；VS Code Copilot 命令面板；npx skills add（Cursor 等 50+ 客户端）；Kiro Powers 面板 |
2. 功能介绍与亮点
scan-secrets 基于 GitGuardian 的 ggshield CLI，检测 700+ 类型的硬编码密钥（AWS 密钥、GitHub Token、数据库连接串、私钥、Stripe Key、Slack Webhook、JWT 等），覆盖范围包括：
- 单个文件/目录、暂存改动、指定 commit 或 commit 区间
- 完整 Git 历史（能找出已被删除但仍留在历史记录里的密钥）
- Docker 镜像与 PyPI 包
亮点：
- 官方出品：由密钥泄露检测领域的知名厂商 GitGuardian 直接维护，而非社区二次封装
- 结构化交付：扫描结果强制以 JSON 输出，Agent 可直接解析、去重、分组处理，避免遗漏
- 修复方法论内置：附带专门的修复指导文档，规定“先轮换、后判断是否需要重写历史”的处置顺序，而非让 Agent 临场发挥
- 防止密钥明文进入对话上下文：对“检查已知凭据是否已泄露”这类操作，SKILL.md 明确要求交给用户在本地终端执行，Agent 不得读取凭据文件明文
- 同一仓库还打包了 5 个配套技能：生成蜜罐凭据（create-honeytokens）、安装预防性 Git/AI 助手钩子（install-hooks）、审计整台开发机（scan-machine）、批量核对已知凭据是否泄露（check-hmsl）、GitGuardian 仪表盘事件分诊（triage-incidents），一次安装即可按需分别触发
3. 适用场景
所属分类：安全与合规
- 团队日常用 Claude Code / Codex 写代码，希望在提交或推送前自动扫描
.env、CI 配置、部署脚本里的硬编码密钥 - 安全或合规人员需要审计仓库完整 Git 历史，找出历史提交中遗留的密钥
- 需要在开发机淘汰、转让或出售前，确认本机不残留任何有效凭据
4. 跨 Agent 兼容性
- Claude Code：原生支持 ✅ —— 官方插件市场一条命令安装（
/plugin marketplace add+/plugin install） - Codex：原生支持 ✅ —— README 明确给出 Codex CLI 插件市场安装步骤（需 Codex CLI ≥ 0.117.0）
- OpenClaw：未验证 —— README 未提及
- Hermes Agent：未验证 —— README 未提及；虽然其
npx skills add安装渠道号称支持 50+ 类 SKILL.md 兼容客户端，但未点名验证 Hermes Agent
5. 推荐理由
密钥泄露检测领域的知名厂商 GitGuardian 官方出品并开源，把生产级的 ggshield 扫描能力与经过验证的修复方法论，直接封装成 Agent 可调用的技能；对“密钥是否已泄露”这类高敏感操作专门设计了防止明文进入对话上下文的交接协议，安全设计成熟度明显高于一般社区技能。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 6 | GitGuardian 是密钥泄露检测领域的知名厂商，但该技能所在仓库创建仅约 2 个月，除官方发布公告与技术媒体转载外，独立第三方讨论尚有限 |
| 可用性 | 8 | Claude Code / Codex 均一条命令安装，文档含完整参考文件（安装引导、修复方法论、平台通用说明），近两周内仍在持续发布迭代 |
| 安全性 | 8 | 见下方安全检查清单 |
安全检查清单：
① Shell 命令执行：调用本地 ggshield CLI 执行扫描，命令与参数在 SKILL.md 中逐条列出，范围限定为凭据扫描，未见越权系统操作
② 联网外发：凭据有效性校验会连接 GitGuardian 云端服务，该行为是“密钥是否已在公开泄露库中出现”功能本身所必需，文档中已透明说明
③ API Key/凭据存储：完整功能需要 GitGuardian 账号 Token（提供免费层）；SKILL.md 明确禁止 Agent 直接读取本地凭据文件明文，仅允许用户在自己终端执行相关命令
④ 可疑指令排查：抓取的 README 与多份 SKILL.md 中未发现要求执行未授权操作、访问无关文件或凭据的可疑文字；涉及全局/系统级改动（如安装全局钩子）均明确要求“先取得用户明确同意”
⑤ 作者信誉：GitGuardian SA，密钥安全领域知名厂商，GitHub 组织公开可查（903 关注者、36 个公开仓库）
⑥ License：MIT，清晰
⑦ 最近维护：最新 Tag v0.5.0 发布于 2026-07-06，近两周内仍有提交记录
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与 scan-secrets 的差异 |
|---|---|---|
| sail-skill（pillar-labs） | 面向 AI/Agent 系统自身的安全成熟度评估，内置 91 项风险目录，可生成 EU AI Act、ISO/IEC 42001 等合规检查清单 | 关注对象是“AI 系统的安全治理流程”，不扫描代码仓库里的硬编码密钥；License 为 CC BY-NC-SA（非商业性），企业商用场景需留意授权限制 |
| rl-protect-skills（ReversingLabs） | 面向开源依赖与第三方包的供应链风险扫描，检测恶意包、依赖漏洞与策略违规 | 关注对象是“引入的第三方依赖”而非“自身代码库里的硬编码密钥”，与 scan-secrets 是互补关系而非替代 |
三者分别覆盖“AI 系统治理合规”“第三方依赖供应链风险”“自身代码库硬编码密钥”三个不同风险面，可视团队实际需要组合使用。
8. 用户评价
该技能除 GitGuardian 官方博客发布公告及技术媒体转载报道外，目前在第三方平台尚无独立署名的用户评价。
9. 安装使用方式
- Claude Code：
/plugin marketplace add GitGuardian/agent-skills，再执行/plugin install gitguardian；推荐额外执行ggshield install -t claude-code -m global，为 Agent 的操作开启实时扫描防护（需ggshield≥ 1.49.0） - Codex CLI（≥ 0.117.0）：
codex plugin marketplace add GitGuardian/agent-skills，进入会话后执行/plugins，在插件列表中选择gitguardian安装 - VS Code + GitHub Copilot：命令面板运行 “Chat: Install Plugin From Source”，粘贴仓库地址
https://github.com/GitGuardian/agent-skills - Cursor 及其他 50+ 受支持客户端：
npx skills add gitguardian/agent-skills（基于 skills.sh） - Kiro：Powers → Add Power → Add power from GitHub URL，填入
https://github.com/GitGuardian/agent-skills/tree/main/kiro
安装后需另行安装并登录 ggshield CLI（免费 GitGuardian 账号即可），完成鉴权后在对话中提出扫描请求即会自动触发本技能，无需重启 Agent 客户端。
10. 注意事项
- 完整历史扫描、Docker 镜像扫描等能力依赖已安装并完成鉴权的
ggshieldCLI（≥ 1.49.0），未安装时技能会先引导完成安装设置 - 免费账号功能有限，批量核对已知凭据（HasMySecretLeaked）等部分能力可能需要企业版 Portal
- 安装“全局”级钩子会影响本机所有项目，属于系统级改动，SKILL.md 要求 Agent 先取得用户明确同意再执行
- 该仓库同时打包了另外 5 个关联技能（蜜罐凭据生成、钩子安装、整机审计、已知凭据查漏、事件分诊），按需安装对应子目录即可各自独立触发