scan-secrets

ggshield — GitGuardian 密钥扫描器

概述

ggshield 是一个命令行工具，可检测文件、git 历史记录、Docker 镜像和 PyPI 软件包中 700 多种类型的硬编码密钥，包括 AWS 密钥、GitHub 令牌、数据库连接字符串、私钥、Stripe 密钥、Slack webhook、JWT 等。

**核心规则：**处理凭据相关代码时，请在提交结果前运行 ggshield。不要提交或展示包含检测到的密钥的代码。

从这里开始 — 开始操作前请阅读

请勿跳过本节。

• 不要另行编写扫描器。 不要使用 grep 单行命令、正则表达式搜索或自定义的密钥查找脚本。请使用 ggshield secret scan，并传入下方 扫描命令 中记录的标志。检测器经过调优和验证；临时编写的模式则没有。
• 扫描必须使用 ggshield CLI——不要用 GitGuardian Developer MCP 的 scan_secrets 工具替代。 如果已连接 MCP 服务，其 scan_secrets 工具可能会让人想把它当作无需安装的捷径。对于这项技能来说，它并不是合适的工具：它只扫描你粘贴进去的一份内存中的内容，因此扫描代码片段以外的内容会很慢，而且无法扫描 git 历史、提交范围、暂存的更改、代码库、Docker 镜像或 PyPI 包——而这些正是这项技能的核心工作。CLI 会在本地流式处理文件，并一次性审计完整历史；MCP 路径则做不到。因此：
  • 绝不要因为 CLI 尚未安装，就悄悄改用 MCP 的 scan_secrets。
  • 如果尚未安装 ggshield，请强烈建议用户先安装再扫描——只需一条命令，不到一分钟即可完成安装，还能启用 MCP 工具无法进行的历史、提交、Docker 和 PyPI 扫描。请先执行下方的入门流程，并说明这样做的原因，而不是转向 MCP 捷径。只有用户明确拒绝安装时，才可以提及 MCP 的 scan_secrets，即便如此也只能用于单个粘贴的代码片段——绝不能用于历史、代码库，或 扫描命令 中的任何命令。
• 不要自行编造补救建议。 不要提供基于常识的密钥轮换步骤，不要擅自建议使用 git filter-repo / BFG，也不要遗漏 HMSL。ggshield 返回一项或多项发现时，请先阅读 references/remediation-doctrine.md，再编写任何面向用户的补救信息——该规范在重要方面不同于常见做法（优先轮换，而非重写历史；对于有效性无法核实的情况，后续应使用 HMSL）。
• 在 Agent 环境中始终传入 --json——你需要结构化输出才能可靠地解析发现项。
• 始终将 -r 与 -y 搭配使用——-r 会触发交互式的 Confirm recursive scan. 提示；如果没有 -y，命令会在标准输入上挂起。
• 如果 CLI 尚未设置，请先执行入门流程。 如果 ggshield --version 失败，或 ggshield api-status 报错，请先按照 references/ggshield-cli-setup.md 完成设置，再尝试任何扫描，并强烈建议用户安装 CLI——不要把 MCP 的 scan_secrets 工具当作变通方案（见上文的 CLI 强制要求）。在 CLI 安装并完成身份验证之前，任何扫描命令都没有用。
• 不要展示包含已检测到的密钥的代码。先等待扫描完成。 不要一发现第一项就开始补救——ggshield 会在一次运行中报告完整的发现集合，而且同一凭据通常会出现在多个文件或提交中。只有扫描完成后，才能：
  1. 停下来。列出所有发现项，然后进行分组：将多个文件／提交／制品中出现的相同凭据值合并为一项，并将不同凭据分别列出。报告分组后的结果（文件、行号、密钥类型、有效性）。
  2. 从头到尾阅读 references/remediation-doctrine.md——不要跳过此步骤。关于重写历史、轮换触发条件和 HMSL 后续处理的常见做法，均与 GitGuardian 规范不同。
  3. 对完整且去重后的发现集合进行分类，然后制定一个统一的补救计划：优先轮换；对有效性无法核实的发现，后续使用 HMSL；仅在参考文档列出的严格条件下重写历史。同一凭据即使在五处泄露，也只需轮换一次。有效性结果为 valid 并不意味着可以跳过分类——这会提高紧迫性，但补救方案仍取决于责任归属和影响范围；对有效且对生产环境至关重要的凭据，应进行有监督、按顺序执行的轮换（协调），而不是草率地“直接轮换”。详见规范原则 7。 不要提交，不要展示包含内联密钥的代码，不要“先继续，之后再修复”，也不要在其他发现仍在扫描或分类时就开始轮换其中一个密钥。
• 不要将此技能的 Agent 可执行约定扩展到 HMSL。 当某项发现的 validity 为 unknown、cannot_check 或 no_checker 时，自然的后续步骤是 HasMySecretLeaked（HMSL）——GitGuardian 的隐私保护哈希查询服务，用于检查已知凭据是否出现在公开泄露数据集中。HMSL 采用不同的执行模式——只能由用户运行；无论用户是否安装了专用的 check-hmsl 技能，这项约定都适用：
  • 不要自行调用 ggshield hmsl check、fingerprint、query、decrypt 或 check-secret-manager。
  • 不要使用 Read / Grep / cat / head / tail / sed / awk / less / xxd / wc / file / ls 或任何其他工具读取凭据文件——这会在 HMSL 的本地哈希协议保护凭据之前，将明文载入 Agent 上下文。
  • 打印供用户在自己的终端中运行的确切命令。使用 -n none --json，确保用户粘贴回来的输出不包含可识别的线索。建议在任何批量检查前运行 ggshield hmsl quota。坚决拒绝使用 --naming-strategy cleartext。
  • 如果用户安装了 check-hmsl 技能，Agent 应加载该技能以遵循完整协议并使用完整命令集；如果没有安装，上述规则本身已足够——不要因为缺少另一项技能而阻止后续步骤。

何时使用

在以下情况下触发扫描：

• 用户要求扫描文件、目录或代码库中的密钥或凭据
• 你正在编写或修改处理 API 密钥、令牌、密码、连接字符串或任何凭据的代码——在呈现结果前先扫描
• 用户即将提交或推送——先扫描已暂存的更改

ggshield 的覆盖范围：

• 扫描磁盘上的文件和目录（secret scan path）
• 审计代码库的完整 git 历史（secret scan repo）——捕获已提交后又被删除的密钥
• 扫描特定提交、提交范围或已暂存的更改
• 扫描 Docker 镜像和 PyPI 软件包
• 作为 CI 门禁运行，在发现问题时失败
• 安装 git 钩子（pre-commit / pre-push）和 AI Agent 钩子（Claude Code、Cursor、Copilot）——Agent 钩子会在 Agent 内部扫描提示词、工具调用和工具输出
• 使用 # ggignore 注释和 .gitguardian.yaml 管理误报

有关详细的命令变体、预期的 JSON 输出格式和 CI 集成，请参阅 references/workflows.md。 有关如何解读扫描输出、HMSL 后续步骤约定和误报工作流，请参阅 references/interpreting-results.md。 有关修复——分类、轮换规则、何时（以及何时不）重写 git 历史记录、各类密钥的操作手册和验证，请参阅 references/remediation-doctrine.md。 有关通用的 ggshield 安装、身份验证、无头设置、CI 令牌和钩子安装命令，请参阅 references/ggshield-cli-setup.md。 有关涵盖所有 GitGuardian 技能的平台级主题（公开文档 URL 格式、身份验证/权限范围恢复、实例 URL、无头设置），请参阅 references/gitguardian-platform.md。

何时不使用

在以下情况下不要使用此技能：

• 用户已持有一个已知凭据，并想知道它是否已在公开渠道泄露——请使用 check-hmsl。此技能用于查找未知密钥；check-hmsl 用于检查已知凭据是否出现在公开泄露数据集中。
• 用户要求盘点整台机器上的凭据（点文件、云 CLI 配置、Shell 历史记录、其他代码库）——请使用 scan-machine。
• 你打算用一行 grep 命令、正则表达式搜索或自定义密钥查找脚本代替。请使用 ggshield secret scan——其检测器经过调优和验证；临时编写的模式并不可靠。

初次使用时的入门指南

前置条件

• ggshield 1.49.0 或更高版本——完整功能支持所必需，包括 AI Agent 钩子（ggshield install -t claude-code、-t cursor、-t copilot）。较旧的 ggshield 版本可以扫描，但无法安装 Agent 钩子。
• GitGuardian 账户（提供免费套餐：https://dashboard.gitguardian.com/signup）。

设置

如果 ggshield --version 执行成功，且 ggshield api-status 返回 OK，请跳过共享设置。否则，请按照 references/ggshield-cli-setup.md 操作，并在两项检查都通过后返回此处。

步骤 1（推荐）——安装 Agent 钩子，构建纵深防御

安装并验证 ggshield 身份后，在新设备上的首要推荐操作是安装 Agent 钩子。该钩子会在 Agent 内部扫描提示词、工具输入和工具输出，检测机密信息并在其进入模型上下文前将其拦截——这是防止 Agent 意外读取或复述凭据的纵深防御措施。根据用户使用的 Agent 进行匹配：

ggshield install -t claude-code -m global     # Claude Code
ggshield install -t cursor -m global          # Cursor
ggshield install -t copilot -m global         # Copilot

首次使用时，用一句话提出此建议：“为了构建纵深防御，确保我读取的文件中的凭据不会进入我的对话记录，现在安装 Agent 钩子吗？（ggshield install -t claude-code -m global）” 等待用户回答是或否。钩子是其中一道防线；开始使用中记录的、ggshield hmsl * 只能由用户运行这一规则则是另一道防线。两者相辅相成，不能相互替代。

步骤 2——简要介绍此技能的功能

• 扫描代码中的硬编码机密信息——处理凭据时自动扫描，也可按需扫描指定文件或目录。
• 审计仓库的 Git 历史记录、提交范围、单次提交、Docker 镜像或 PyPI 软件包，查找泄露的机密信息。
• 通过步骤 1 中安装的 Agent 钩子，或通过 Git 钩子（ggshield install --mode local）以及对暂存更改进行临时扫描（scan pre-commit），在机密信息写入之前将其拦截。
• 通过行内 # ggignore 注释或 .gitguardian.yaml 规则管理误报。

介绍内容应简洁；详细设置参考供 Agent 查阅，而非供用户阅读。

扫描命令

始终添加 --json，以获取结构化输出。递归扫描（-r）会触发交互式 Confirm recursive scan. 提示——Agent 调用时，必须将 -r 与 -y 配合使用，否则 CLI 会挂起并等待 stdin 输入。

ggshield secret scan repo . --json                       # full git history
ggshield secret scan path -r -y . --json                 # current files, no git required
ggshield secret scan path <file> --json                  # single file (no -r needed)
ggshield secret scan pre-commit --json                   # staged changes
ggshield secret scan commit-range HEAD~5..HEAD --json    # commit range
ggshield secret scan commit <sha> --json                 # specific commit
ggshield secret scan docker <image> --json               # Docker image
ggshield secret scan pypi <package> --json               # PyPI package

关键标志：

标志	作用
--json	结构化 JSON 输出——在自动化场景中始终使用
-y / --yes	自动确认交互式提示。在 Agent 场景中，凡使用 -r 时均必须添加
--exit-zero	始终以 0 退出，报告发现项但不阻止 CI
--ignore-known-secrets	跳过 GitGuardian 信息面板中已跟踪的机密信息
--minimum-severity <level>	仅报告达到或超过指定严重级别的发现项（info、low、medium、high、critical）
--output <file>	将结果写入文件，而不是 stdout

退出代码：0 = 未发现机密信息，1 = 检测到机密信息，128 = 意外错误。

存在发现项时 — 快速参考

完整规范见 references/remediation-doctrine.md — 编写任何面向用户的修复消息前，请先加载该文件。根据产生发现项的命令进行分流：

检测场景	规范入口
Agent 文件编辑钩子触发（缓冲区内／刚保存的文件）	§ 5.1
提交前钩子触发（暂存的更改被阻止）	§ 5.2
推送前钩子触发（待推送的提交被阻止）	§ 5.3
仓库／提交／Docker 镜像／PyPI 软件包扫描发现项	根据制品所在位置，在 § 6（公开）或 § 7（内部私有）中进行分类

自定义修复消息优先。 如果工作区配置了修复工作流，ggshield（≥ 1.30.0）会在钩子输出中显示工作区自己的消息。将该消息原样作为主要指导，并在此基础上补充规范中的具体操作 — 不要用通用建议覆盖它。参见 § 13。

最常被遗漏的三种触发情形：

• 已推送到远程 → 轮换。 密钥推送后通常不建议重写历史；真正的修复措施是轮换。不要优先建议使用 git filter-repo / BFG。
• 有效性为 unknown / cannot_check / no_checker / failed_to_check → 建议使用 HMSL，以便自然地继续检查是否存在公开泄露。准备好命令（ggshield hmsl quota，然后执行 ggshield hmsl check ... -n none --json）；由用户运行。切勿自行调用 ggshield hmsl *，也不要读取凭据文件。
• 仅存在于本地、从未推送 → 删除，不要轮换。 重写未推送的历史成本很低，在此情况下值得这样做。

最佳实践

• 编写或修改处理凭据或配置的代码时，主动扫描 — 不要等到有人要求。
• 发现凭据时：始终将其从代码中删除。只有当密钥已暴露在远程位置（推送到共享仓库、CI 系统或任何外部服务）时，才需要轮换。纯粹存在于本地、从未离开过本机的密钥只需删除，无需轮换。
• 不要提交或展示包含已检测到密钥的代码。停止工作流，报告发现项（文件、行号、密钥类型、有效性），然后修复并重新扫描。
• 对于误报，可在问题所在行添加 # ggignore，或运行 ggshield secret ignore --last-found 将其记录到 .gitguardian.yaml。

故障排除

ggshield: command not found — ggshield 不在 PATH 中。请参阅上文的首次使用入门。

401 Unauthorized — API 密钥或已存储的 OAuth 令牌缺失或无效。使用 ggshield api-status 验证。如果使用 GITGUARDIAN_API_KEY，请使用 echo $GITGUARDIAN_API_KEY 确认其值，并确认令牌具有 scan 作用域。

403 Forbidden / "Insufficient permissions" — 令牌有效，但缺少此操作所需的作用域。请参阅 references/gitguardian-platform.md 了解恢复流程——ggshield auth logout + ggshield auth login --scopes <scope>，可代用户运行，无需手动创建 PAT。

Not a git repository — ggshield secret scan repo 需要 Git 上下文。请改用 ggshield secret scan path -r -y .。

递归扫描卡住 — 使用 -r 时没有加上 -y。CLI 正在等待 Confirm recursive scan. 提示。请使用 -y 重新运行。

OAuth 浏览器窗口未打开 — 当前环境为无头环境。优先使用 ggshield auth login --method oob（ggshield 1.51.0+）：它会打印一个 URL，用户可在任意设备上打开并登录，然后粘贴返回验证码，无需手动创建令牌。仅当不支持 oob 时（较旧版本的 ggshield，或不提供此方式的实例），才使用 --method token。请参阅 references/ggshield-cli-setup.md 中的无头环境与 CI。

速率限制 — 已超出免费层级的配额。请引导用户前往 https://dashboard.gitguardian.com 查看用量。

其他错误或未列出的错误 — 在尝试自行解决之前，请查阅 GitGuardian 的 AI Agent 文档索引 https://docs.gitguardian.com/llms.txt，找到相关页面，然后在该页面的 URL 后添加 .md，以 Markdown 格式阅读。请先在那里搜索，不要猜测。