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。
您可以使用 Homebrew 安装 ggshield：
brew install ggshield
升级由 Homebrew 自动处理。
或者，您可以从 ggshield 发布页 下载并安装独立的 .pkg 包。
此软件包不需要安装 Python，但您需要手动下载新版本。
Deb 和 RPM 包可在 Cloudsmith 上获取。
设置说明：
升级由包管理器自动处理。
ggshield 可通过 Chocolatey 包管理器 获取：
choco install ggshield
从 ggshield 发布页 下载 MSI 安装程序并安装：
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
我们在 ggshield 发布页 提供独立的 .zip 存档。
将存档解压到您的磁盘上，然后将包含 ggshield.exe 文件的目录添加到 %PATH%。
此存档不需要安装 Python，但您需要手动下载新版本。
ggshield 可通过其 PyPI 包 在所有支持的操作系统上安装。
它需要一个受支持的 Python 版本（未结束生命周期）（独立包除外）和 git。
如果您不使用我们的 ggshield 打包版本，请注意我们遵循 Python 发布周期，不支持已结束生命周期的版本。
从 PyPI 安装 ggshield 的推荐方式是使用 pipx，它会将其安装在隔离的环境中：
pipx install ggshield
要升级您的安装，请运行：
pipx upgrade ggshield
您也可以使用 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 命令）：ggshield secret scan docker ubuntu:22.04pip 命令）：ggshield secret scan pypi flaskggshield 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 钩子。
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 许可证。