gitguardian/ggshieldОбнаруживайте и проверяйте более 500 типов жёстко заданных секретов с помощью расширенных проверок. Используйте его как pre-commit hook, GitHub Action или CLI для проактивного обнаружения секретов и обеспечения безопасности.
# [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 вызывает запрос Keychain для `ggshield-py`** — второго бинарного файла, который теперь считывает ваш сохранённый токен в рамках наших улучшений производительности. Нажмите **Always Allow**; больше он не спросит.
`ggshield` — это CLI-приложение, которое запускается в вашей локальной среде или в среде CI и помогает обнаруживать более 500 типов секретов.
`ggshield` использует наш [публичный API](https://api.gitguardian.com/docs) через [py-gitguardian](https://github.com/GitGuardian/py-gitguardian) для сканирования и обнаружения потенциальных уязвимостей в файлах и другом текстовом содержимом.
При сканированиях с помощью `ggshield` сохраняются только метаданные, такие как время вызова, размер запроса и режим сканирования, поэтому секреты не будут отображаться на вашей панели управления, а **ваши файлы и секреты не будут сохранены**.
# Содержание
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Установка](#installation)
- [Скрипт установки (рекомендуется)](#install-script-recommended)
- [macOS](#macos)
- [Homebrew](#homebrew)
- [Автономный пакет .pkg](#standalone-pkg-package)
- [Linux](#linux)
- [Пакеты Deb и RPM](#deb-and-rpm-packages)
- [Windows](#windows)
- [Chocolatey](#chocolatey)
- [Установщик MSI](#msi-installer)
- [Автономный архив .zip](#standalone-zip-archive)
- [Все операционные системы](#all-operating-systems)
- [Использование pipx](#using-pipx)
- [Использование pip](#using-pip)
- [Первоначальная настройка](#initial-setup)
- [Использование `ggshield auth login`](#using-ggshield-auth-login)
- [Ручная настройка](#manual-setup)
- [Начало работы](#getting-started)
- [Секреты](#secrets)
- [Миграция устаревшего файла конфигурации](#migrating-a-legacy-configuration-file)
- [Интеграции](#integrations)
- [ИИ-ассистенты для программирования](#ai-coding-assistants)
- [Узнать больше](#learn-more)
- [Вывод](#output)
- [Связанные проекты с открытым исходным кодом](#related-open-source-projects)
- [Лицензия](#license)
<!-- 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` (установить
плагин). Для рабочего пространства EU или самостоятельно размещённого экземпляра задайте
переменную окружения `GITGUARDIAN_INSTANCE` (или передайте `--instance <URL>`)
перед запуском.
Полный список параметров, другие способы установки и инструкции по удалению см. в
[`scripts/install/README.md`](https://github.com/gitguardian/ggshield/blob/main/scripts/install/README.md).
Приведённые ниже способы устанавливают CLI вручную.
## macOS
### Homebrew
Вы можете установить `ggshield` с помощью Homebrew:
```shell
brew install ggshield
```
Обновление выполняется средствами Homebrew.
### Автономный пакет .pkg
В качестве альтернативы вы можете скачать и установить автономный пакет .pkg со [страницы релизов `ggshield`](https://github.com/GitGuardian/ggshield/releases).
Этот пакет _не_ требует установки 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
Скачайте установщик MSI со [страницы релизов `ggshield`](https://github.com/GitGuardian/ggshield/releases) и установите его:
```powershell
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
```
### Автономный архив .zip
Мы предоставляем автономный архив .zip на [странице релизов `ggshield`](https://github.com/GitGuardian/ggshield/releases).
Распакуйте архив на диск, затем добавьте каталог, содержащий файл `ggshield.exe`, в `%PATH%`.
Этот архив _не_ требует установки Python, но новые версии придётся скачивать вручную.
## Все операционные системы
`ggshield` можно установить во всех поддерживаемых операционных системах через его [пакет PyPI](https://pypi.org/project/ggshield).
Требуется **поддерживаемая версия Python (не EOL)** (кроме автономных пакетов) и git.
Если вы не используете наши упакованные версии `ggshield`, учтите, что мы следуем [циклу выпуска Python](https://devguide.python.org/versions/) и не поддерживаем версии, достигшие EOL.
### Использование pipx
Рекомендуемый способ установки `ggshield` из PyPI — использовать [pipx](https://pypa.github.io/pipx/), который установит его в изолированное окружение:
```shell
pipx install ggshield
```
Чтобы обновить установку, выполните:
```shell
pipx upgrade ggshield
```
### Использование pip
Вы также можете установить `ggshield` из PyPI с помощью pip, но это не рекомендуется, поскольку установка не изолирована, поэтому другие приложения или пакеты, установленные таким образом, могут повлиять на вашу установку `ggshield`. Этот способ также не сработает, если ваша установка Python объявлена как externally managed (например, при использовании системного Python в таких операционных системах, как Debian 12):
```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`, чтобы настроить ИИ- и git-хуки,
разместить honeytokens и зарегистрировать машину на странице Endpoints перед первым
сканированием. Регистрация включает текущего пользователя или всех целевых пользователей honeytoken при
запуске от имени root. Она выполняется по мере возможности, занимает не более пяти секунд и не влияет
на код возврата команды.
Сканирования `ggshield secret scan pre-commit`, `pre-push` и `ai-hook` также отправляют
имя хоста машины, по которому GitGuardian регистрирует пользователей этих хуков.
Другие команды сканирования его не отправляют, как и нативный ИИ-хук, который запускают автономные и
платформенно-зависимые установки через `pip`.
В CI ggshield не регистрирует машину и не отправляет имя хоста. Чтобы отключить и то, и другое в других местах, задайте `endpoint_registration: false` в `.gitguardian.yaml` или установите
`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` как [Git-хук pre-commit, pre-push или pre-receive](https://docs.gitguardian.com/ggshield-docs/integrations/overview#git-hooks-prevent-secrets-from-reaching-your-vcs).
## ИИ-ассистенты для программирования
`ggshield` может [сканировать взаимодействия](https://docs.gitguardian.com/ggshield-docs/integrations/ai-coding-tools/secret-scanning-for-ai-coding-tools) между вами и вашим ИИ-ассистентом для программирования в реальном времени, блокируя действия, содержащие секреты, до их выполнения.
Вы можете установить хуки с помощью команды `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.