mcpField
G
GitGuardian ggshield

GitGuardian ggshield

官方Agent-ready
docs.gitguardian.com开发者工具2.0kggshield今天更新
代码仓库访问官网

关于 GitGuardian ggshield

ggshield 扫描代码库、提交和文件以找出意外泄露的密钥和凭证。它可作为预提交钩子运行，防止含有密钥的代码被提交，并集成到 CI 管道和 Docker 镜像扫描中。

主要功能

  1. 01在代码库和提交历史中扫描泄露的密钥
  2. 02在代码提交前拦截和阻止密钥泄露
  3. 03扫描 Docker 镜像和 CI 管道中的敏感信息

适用场景

  1. 01在开发工作流中自动检测凭证泄露
  2. 02防止密钥被意外提交到版本控制
  3. 03扫描容器镜像和持续集成环境以查找敏感数据

安装

选择你的系统或包管理器，复制命令到终端运行。

$
pipx install ggshield

安装完成后运行ggshield --version确认安装成功。

命令示例

常用命令按使用顺序排列。

01
ggshield auth login
02
ggshield secret scan repo .
03
ggshield secret scan pre-commit

详细介绍

ggshield：使用 GitGuardian 保护代码

PyPI Docker Image Version (latest semver) License GitHub stars GitHub Workflow Status Codecov

重要

macOS：升级到 1.54.0 会触发针对 ggshield-py 的钥匙串提示。这是一个新增的辅助二进制文件，它现在会读取您保存的令牌，以实现性能优化。请点击 始终允许；之后不会再出现提示。

ggshield 是一款命令行应用，可在本地环境或 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。

macOS

Homebrew

您可以使用 Homebrew 安装 ggshield：

brew install ggshield

Homebrew 会负责处理升级。

独立 .pkg 软件包

您也可以从 ggshield 发布页面下载并安装独立的 .pkg 软件包。

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

Linux

Deb 和 RPM 软件包

Deb 和 RPM 软件包可在 Cloudsmith 上获取。

设置说明：

升级由软件包管理器处理。

Windows

Chocolatey

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

choco install ggshield
MSI 安装程序

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

msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
独立 .zip 存档

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

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

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

所有操作系统

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

它需要受支持版本的 Python（未到 EOL）（独立软件包除外）和 git。

如果你不使用我们打包的 ggshield 版本，请注意，我们遵循 Python 发布周期，不支持已到 EOL 的版本。

使用 pipx

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

pipx install ggshield

要升级安装，请运行：

pipx upgrade ggshield
使用 pip

你也可以使用 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 钩子、植入 honeytoken，并在首次扫描前于 Endpoints 页面注册此机器。注册内容包括当前用户；以 root 身份运行时，则包括所有 honeytoken 目标用户。注册会尽力完成，耗时最多五秒，且不会影响命令的退出代码。

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 环境变量中，以完成设置。

开始使用

Secrets

现在可以使用 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 --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 和 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），否则过长的行会被截断，以适应终端的大小。

相关开源项目

许可证

ggshield 采用 MIT 许可证。

评论

支持 Markdown