[!IMPORTANT] macOS：升级到 1.54.0 会触发针对
ggshield-py的钥匙串提示，这是我们性能改进的一部分，该第二个二进制文件现在会读取你保存的令牌。点击 始终允许；之后不会再询问。
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（安装插件）等选项。对于欧盟工作区或自托管实例，请在运行前设置 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 版本（未 EOL）（独立包除外）以及 git。
如果你不使用我们打包的 ggshield 版本，请注意我们遵循 Python 发布周期，不支持已达到 EOL 的版本。
从 PyPI 安装 ggshield 的推荐方式是使用 pipx，它会将其安装到隔离环境中：
pipx install ggshield
要升级你的安装，请运行：
pipx upgrade ggshield
你也可以使用 pip 从 PyPI 安装 ggshield，但不推荐这样做，因为安装不是隔离的，因此以这种方式安装的其他应用程序或包可能会影响你的 ggshield 安装。如果你的 Python 安装被声明为外部管理（例如在 Debian 12 等操作系统上使用系统 Python 时），此方法也将无法工作：
pip install --user ggshield
要升级你的安装，请运行：
pip install --user --upgrade ggshield
ggshield auth login要使用 ggshield，你需要向 GitGuardian 服务器进行身份验证。为此，请使用 ggshield auth login 命令。此命令会自动配置个人访问令牌并在本地工作站上进行配置。
你可以从 ggshield auth login 文档了解更多信息。
身份验证后，运行 ggshield machine setup 以配置 AI 和 git 钩子、植入蜜令牌，并在首次扫描前在 Endpoints 页面上注册该机器。注册包括当前用户，或在以 root 身份运行时包括所有蜜令牌目标用户。这是尽力而为的，最多需要五秒钟，并且不会影响命令的退出代码。
ggshield secret scan pre-commit、pre-push 和 ai-hook 的扫描还会发送机器主机名，GitGuardian 据此注册这些钩子的用户。其他扫描命令不会发送它，独立安装和平台特定的 pip 安装所运行的原生 AI 钩子也不会发送它。
在 CI 上，ggshield 既不注册机器也不发送主机名。要在其他地方关闭这两者，请在 .gitguardian.yaml 中设置 endpoint_registration: false，或将 GGSHIELD_NO_ENDPOINT_REGISTRATION 设置为非空值。
你也可以手动创建个人访问令牌，并将其存储在 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 和 Mistral Vibe 2.21+。
有关更多信息，请查看文档
如果未找到任何密钥，退出代码将为 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）。