# [ggshield](https://github.com/GitGuardian/ggshield)：使用 GitGuardian 保护你的代码
[](https://pypi.org/project/ggshield/)
[](https://hub.docker.com/r/gitguardian/ggshield)
[](LICENSE)
[](https://github.com/GitGuardian/ggshield/stargazers)
[](https://github.com/GitGuardian/ggshield/actions)
[](https://codecov.io/gh/GitGuardian/ggshield/)
> [!IMPORTANT]
> **macOS：升级到 1.54.0 会触发针对 `ggshield-py` 的钥匙串提示**，这是我们性能改进的一部分，该第二个二进制文件现在会读取你保存的令牌。点击 **始终允许**；之后不会再询问。
`ggshield` 是一个 CLI 应用程序，可在你的本地环境或 CI 环境中运行，帮助你检测 500 多种类型的密钥。
`ggshield` 通过 [py-gitguardian](https://github.com/GitGuardian/py-gitguardian) 使用我们的[公共 API](https://api.gitguardian.com/docs) 来扫描和检测文件及其他文本内容中的潜在漏洞。
使用 `ggshield` 进行扫描时，仅会存储调用时间、请求大小和扫描模式等元数据，因此密钥不会显示在你的仪表板上，并且**你的文件和密钥不会被存储**。
# 目录
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [安装](#安装)
- [安装脚本（推荐）](#安装脚本推荐)
- [macOS](#macos)
- [Homebrew](#homebrew)
- [独立 .pkg 包](#独立-pkg-包)
- [Linux](#linux)
- [Deb 和 RPM 包](#deb-和-rpm-包)
- [Windows](#windows)
- [Chocolatey](#chocolatey)
- [MSI 安装程序](#msi-安装程序)
- [独立 .zip 归档文件](#独立-zip-归档文件)
- [所有操作系统](#所有操作系统)
- [使用 pipx](#使用-pipx)
- [使用 pip](#使用-pip)
- [初始设置](#初始设置)
- [使用 `ggshield auth login`](#使用-ggshield-auth-login)
- [手动设置](#手动设置)
- [快速开始](#快速开始)
- [密钥](#密钥)
- [迁移旧版配置文件](#迁移旧版配置文件)
- [集成](#集成)
- [AI 编码助手](#ai-编码助手)
- [了解更多](#了解更多)
- [输出](#输出)
- [相关开源项目](#相关开源项目)
- [许可证](#许可证)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# 安装
<!--
Any change made in this section must be replicated in the "Step 1: Install
ggshield" section of the "Getting started" page of ggshield public
documentation.
-->
## 安装脚本（推荐）
安装 `ggshield` 的最快方式。
Linux / macOS：
```shell
curl -sSfL \
https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash
```
Windows（PowerShell）：
```powershell
irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex
```
或者，如果你更喜欢 `curl`（Windows 10+ 自带）：
```powershell
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`](https://github.com/gitguardian/ggshield/blob/main/scripts/install/README.md)。
以下方法则是手动安装 CLI。
## macOS
### Homebrew
你可以使用 Homebrew 安装 `ggshield`：
```shell
brew install ggshield
```
升级由 Homebrew 处理。
### 独立 .pkg 包
或者，你可以从 [`ggshield` 发布页面](https://github.com/GitGuardian/ggshield/releases)下载并安装独立的 .pkg 包。
此包_不需要_安装 Python，但你必须手动下载新版本。
## Linux
### Deb 和 RPM 包
Deb 和 RPM 包可在 [Cloudsmith](https://cloudsmith.io/~gitguardian/repos/ggshield/packages/) 上获取。
设置说明：
- [Deb 包](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-deb)
- [RPM 包](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-rpm)
升级由包管理器处理。
## Windows
### Chocolatey
`ggshield` 可通过 [Chocolatey 包管理器](https://chocolatey.org/packages/ggshield)获取：
```shell
choco install ggshield
```
### MSI 安装程序
从 [`ggshield` 发布页面](https://github.com/GitGuardian/ggshield/releases)下载 MSI 安装程序并安装：
```powershell
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
```
### 独立 .zip 归档文件
我们在 [`ggshield` 发布页面](https://github.com/GitGuardian/ggshield/releases)提供独立的 .zip 归档文件。
将归档文件解压到磁盘上，然后将包含 `ggshield.exe` 文件的目录添加到 `%PATH%`。
此归档文件_不需要_安装 Python，但你必须手动下载新版本。
## 所有操作系统
`ggshield` 可以通过其 [PyPI 包](https://pypi.org/project/ggshield)安装到所有受支持的操作系统上。
它需要**受支持的 Python 版本（未 EOL）**（独立包除外）以及 git。
如果你不使用我们打包的 `ggshield` 版本，请注意我们遵循 [Python 发布周期](https://devguide.python.org/versions/)，不支持已达到 EOL 的版本。
### 使用 pipx
从 PyPI 安装 `ggshield` 的推荐方式是使用 [pipx](https://pypa.github.io/pipx/)，它会将其安装到隔离环境中：
```shell
pipx install ggshield
```
要升级你的安装，请运行：
```shell
pipx upgrade ggshield
```
### 使用 pip
你也可以使用 pip 从 PyPI 安装 `ggshield`，但不推荐这样做，因为安装不是隔离的，因此以这种方式安装的其他应用程序或包可能会影响你的 `ggshield` 安装。如果你的 Python 安装被声明为外部管理（例如在 Debian 12 等操作系统上使用系统 Python 时），此方法也将无法工作：
```shell
pip install --user ggshield
```
要升级你的安装，请运行：
```shell
pip install --user --upgrade ggshield
```
# 初始设置
## 使用 `ggshield auth login`
要使用 `ggshield`，你需要向 GitGuardian 服务器进行身份验证。为此，请使用 `ggshield auth login` 命令。此命令会自动配置个人访问令牌并在本地工作站上进行配置。
你可以从 [`ggshield auth login` 文档](https://docs.gitguardian.com/internal-repositories-monitoring/ggshield/reference/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 镜像中（`docker` 命令必须可用）：`ggshield secret scan docker ubuntu:22.04`
- 在 Pypi 包中（`pip` 命令必须可用）：`ggshield secret scan pypi flask`
- 以及更多，请查看 `ggshield secret scan --help` 输出以了解详情。
## 迁移旧版配置文件
如果 `ggshield` 报告你的 `.gitguardian.yaml`（或 `.gitguardian.yml`）配置文件使用了已弃用的格式，请使用以下命令将其迁移到最新版本：
```shell
ggshield config migrate
```
默认情况下，这会在当前目录中查找配置文件，因此请从包含该文件的目录运行它。要从任何位置运行它，请显式地将 `ggshield` 指向该文件：
```shell
ggshield --config-path path/to/.gitguardian.yaml config migrate
```
该文件的先前版本会作为 `.old` 备份保留在其旁边。
# 集成
你可以将 `ggshield` 集成到你的 [CI/CD 工作流](https://docs.gitguardian.com/ggshield-docs/integrations/overview#cicd-integrations-secrets-detection-in-your-cicd-workflow)中。
为了更早地捕获错误，请将 `ggshield` 用作 [pre-commit、pre-push 或 pre-receive Git 钩子](https://docs.gitguardian.com/ggshield-docs/integrations/overview#git-hooks-prevent-secrets-from-reaching-your-vcs)。
## AI 编码助手
`ggshield` 可以[实时扫描](https://docs.gitguardian.com/ggshield-docs/integrations/ai-coding-tools/secret-scanning-for-ai-coding-tools)你与 AI 编码助手之间的交互，在执行包含密钥的操作之前将其阻止。
你可以使用 `ggshield install` 命令安装这些钩子。
支持的工具：**Cursor**、**Claude Code**、**Copilot Chat**、**Codex** 和
**Mistral Vibe 2.21+**。
# 了解更多
有关更多信息，请查看[文档](https://docs.gitguardian.com/ggshield-docs/getting-started)
# 输出
如果未找到任何密钥，退出代码将为 0：
```bash
ggshield secret scan pre-commit
```
如果在你的暂存代码或 CI 中发现密钥，你将收到一个警报，其中包含发现密钥的文件名，以及一个提供密钥在文件中位置的补丁：
```shell
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`）。
# 相关开源项目
- [truffleHog](https://github.com/dxa4481/truffleHog)
- [gitleaks](https://github.com/zricethezav/gitleaks)
- [gitrob](https://github.com/michenriksen/gitrob)
- [git-hound](https://github.com/tillson/git-hound)
- [AWS git-secrets](https://github.com/awslabs/git-secrets)
- [detect-secrets](https://github.com/Yelp/detect-secrets)
# 许可证
`ggshield` 采用 MIT 许可证。
