ggshield：使用 GitGuardian 保护您的代码

ggshield 是一个 CLI 应用程序，可在您的本地环境或 CI 环境中运行，帮助您检测 500 多种类型的密钥。

ggshield 通过 py-gitguardian 使用我们的公共 API 来扫描和检测文件及其他文本内容中的潜在漏洞。

使用 ggshield 扫描时，仅存储调用时间、请求大小和扫描模式等元数据，因此密钥不会显示在您的仪表板上，您的文件和密钥也不会被存储。

安装

安装脚本（推荐）

安装 ggshield 的最快方式。

Linux / macOS：

curl -sSfL \
  https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash

Windows (PowerShell)：

irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex

或者，如果您更喜欢 curl（Windows 10+ 自带）：

curl.exe -sSL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -

该脚本接受 --instance 和 --plugin（安装插件）等选项。对于 EU 工作区或自托管实例，请在运行前设置 GITGUARDIAN_INSTANCE 环境变量（或传递 --instance <URL>）。

请参阅 scripts/install/README.md 了解完整选项列表、其他安装方法以及如何卸载。

下面的方法将手动安装 CLI。

macOS

Homebrew

您可以使用 Homebrew 安装 ggshield：

brew install ggshield

升级由 Homebrew 自动处理。

独立 .pkg 包

或者，您可以从 ggshield 发布页下载并安装独立的 .pkg 包。

此软件包不需要安装 Python，但您需要手动下载新版本。

Linux

Deb 和 RPM 包

Deb 和 RPM 包可在 Cloudsmith 上获取。

设置说明：

升级由包管理器自动处理。

Windows

Chocolatey

ggshield 可通过 Chocolatey 包管理器获取：

choco install ggshield

MSI 安装程序

从 ggshield 发布页下载 MSI 安装程序并安装：

msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi

独立 .zip 存档

我们在 ggshield 发布页提供独立的 .zip 存档。

将存档解压到您的磁盘上，然后将包含 ggshield.exe 文件的目录添加到 %PATH%。

此存档不需要安装 Python，但您需要手动下载新版本。

所有操作系统

ggshield 可通过其 PyPI 包在所有支持的操作系统上安装。

它需要一个受支持的 Python 版本（未结束生命周期）（独立包除外）和 git。

如果您不使用我们的 ggshield 打包版本，请注意我们遵循 Python 发布周期，不支持已结束生命周期的版本。

使用 pipx

从 PyPI 安装 ggshield 的推荐方式是使用 pipx，它会将其安装在隔离的环境中：

pipx install ggshield

要升级您的安装，请运行：

pipx upgrade ggshield

使用 pip

您也可以使用 pip 从 PyPI 安装 ggshield，但不建议这样做，因为安装不是隔离的，因此以这种方式安装的其他应用程序或包可能会影响您的 ggshield 安装。如果您的 Python 安装被声明为外部管理（例如在使用系统 Python 的操作系统如 Debian 12 上），此方法也将无法工作：

pip install --user ggshield

要升级您的安装，请运行：

pip install --user --upgrade ggshield

初始设置

使用 `ggshield auth login`

使用 ggshield 需要针对 GitGuardian 服务器进行身份验证。为此，请使用 ggshield auth login 命令。该命令会自动配置个人访问令牌并将其设置在本地工作站上。

您可以通过 ggshield auth login 文档了解更多信息。

手动设置

您也可以手动创建个人访问令牌，并将其存储在 GITGUARDIAN_API_KEY 环境变量中以完成设置。

快速入门

密钥

您现在可以使用 ggshield 搜索密钥：

在文件中：ggshield secret scan path -r .
在仓库中：ggshield secret scan repo .
在 Docker 镜像中（必须安装 docker 命令）：ggshield secret scan docker ubuntu:22.04
在 Pypi 包中（必须安装 pip 命令）：ggshield secret scan pypi flask
以及更多，请查看 ggshield secret scan --help 输出以了解详情。

迁移旧版配置文件

如果 ggshield 报告您的 .gitguardian.yaml（或 .gitguardian.yml）配置文件使用了已弃用的格式，请使用以下命令将其迁移到最新版本：

ggshield config migrate

默认情况下，它会在当前目录中查找配置文件，因此请从包含该文件的目录运行。要从任意位置运行，请显式指定 ggshield 的配置文件路径：

ggshield --config-path path/to/.gitguardian.yaml config migrate

文件的上一版本将作为 .old 备份保留在其旁边。

集成

您可以将 ggshield 集成到您的 CI/CD 工作流中。

为了更早地捕获错误，可以将 ggshield 用作 pre-commit、pre-push 或 pre-receive Git 钩子。

AI 编码助手

ggshield 可以实时扫描您与 AI 编码助手之间的交互，在包含密钥的操作执行前阻止它们。

您可以使用 ggshield install 命令安装钩子。

支持的工具：Cursor、Claude Code、Copilot Chat 和 Codex。

了解更多

有关更多信息，请查看文档

输出

如果未发现密钥，退出码将为 0：

ggshield secret scan pre-commit

如果在暂存代码或 CI 中发现密钥，您将收到一条警报，提示发现密钥的文件名以及补丁，显示密钥在文件中的位置：

ggshield secret scan pre-commit

2 incidents have been found in file production.rb

11 | config.paperclip_defaults = {
12 |     :s3_credentials => {
13 |     :bucket => "XXX",
14 |     :access_key_id => "XXXXXXXXXXXXXXXXXXXX",
                            |_____AWS Keys_____|

15 |     :secret_access_key => "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
                                |_______________AWS Keys_______________|

16 |     }
17 | }

过长的行会被截断以匹配终端大小，除非使用详细模式（-v 或 --verbose）。

许可证

ggshield 采用 MIT 许可证。

ggshield v1.53.0

分类