Секреты в репозитории: gitleaks в pre-commit и CI и что делать при утечке
Если ключ уже утёк — сначала это
Порядок действий важнее инструментов, поэтому начнём с конца.
- 1.Отзовите и перевыпустите ключ у провайдера. Сразу, до чистки истории и разборов. Публичные репозитории сканируются ботами постоянно, и ключ, попавший в публичный коммит, нужно считать скомпрометированным с момента пуша.
- 2.Обновите ключ во всех окружениях (секреты CI, переменные хостинга, менеджер секретов) и перезапустите сервисы.
- 3.Проверьте журнал использования ключа у провайдера: вызовы с незнакомых адресов, необычные объёмы, созданные ресурсы. Для облачных ключей — новые инстансы и пользователи IAM.
- 4.Только потом решайте, чистить ли историю. Переписать её можно через
git filter-repo, но клоны, форки, кэши CI и копии у сервисов-зеркал вы не контролируете. Удаление из истории — гигиена, а не устранение утечки. Если ключ отозван, он безвреден, где бы ни лежал.
Частая ошибка: удалить файл новым коммитом и считать проблему решённой. Значение остаётся в истории и находится одной командой git log -p.
Предотвращение: gitleaks локально
gitleaks ищет в коде и истории строки, похожие на ключи известных сервисов, и высокоэнтропийные значения по набору правил. Подключение через фреймворк pre-commit:
# .pre-commit-config.yaml
repos:
- repo: https://github.com/gitleaks/gitleaks
rev: v8.30.1 # конкретный тег; pre-commit autoupdate обновит его
hooks:
- id: gitleakspip install pre-commit # или brew install pre-commit pre-commit install # ставит хук в .git/hooks pre-commit run gitleaks --all-files
Хук проверяет только то, что вы коммитите, поэтому работает быстро. Но он локальный: его нет у коллеги, который не выполнил pre-commit install, и его отключает git commit --no-verify. Поэтому pre-commit — удобство для разработчика, а настоящий барьер — проверка в CI.
Разовая проверка всей истории существующего репозитория (в версиях 8.19 и новее команды называются git и dir; старые detect и protect сохранены для совместимости):
gitleaks git --redact -v .
Флаг --redact скрывает найденные значения в выводе — без него отчёт сам становится утечкой, если его скопировать в тикет.
Проверка в CI
# .github/workflows/secrets.yml
name: secrets
on: [pull_request, push]
permissions:
contents: read
jobs:
gitleaks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # полная история, иначе проверяется только последний коммит
- uses: gitleaks/gitleaks-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}Для репозиториев организаций gitleaks-action требует лицензионный ключ (бесплатный, выдаётся по запросу) в переменной GITLEAKS_LICENSE. Альтернатива без ключа — запускать сам бинарник или Docker-образ gitleaks в шаге run.
Сделайте эту задачу обязательной проверкой в правилах защиты ветки. Тогда секрет, пропущенный локально, остановится на PR, ещё до попадания в основную ветку.
Ложные срабатывания
Тестовые фикстуры, примеры ключей из документации и хеши в lock-файлах иногда похожи на секреты. Варианты:
- Комментарий
gitleaks:allowв строке — точечное исключение, видимое на ревью. - Файл
.gitleaksignoreс отпечатками (fingerprint) конкретных находок из отчёта. - Собственный
.gitleaks.toml, расширяющий стандартные правила и задающий исключения по путям.
Не исключайте целые каталоги вроде config/ — именно туда секреты и попадают.
GitHub push protection
На GitHub есть встроенный secret scanning с блокировкой пуша для известных форматов токенов. Для публичных репозиториев он доступен бесплатно, для приватных — в рамках платного GitHub Secret Protection. Он дополняет gitleaks: работает на стороне сервера и его нельзя пропустить флагом, но знает только форматы партнёров GitHub и не видит ваши собственные секреты произвольного вида.
Как не допускать утечек в принципе
.env*в.gitignoreс первого коммита, в репозитории только.env.exampleс пустыми значениями.- Ключи с минимальными правами и отдельные для каждого окружения: утечка тестового ключа не должна открывать продакшен.
- Секреты в CI — через встроенное хранилище секретов, никогда в YAML.
- Внимание к логам: значения переменных окружения, распечатанные при отладке сборки, остаются в логах CI.
Чего не делать
- Не «шифровать» ключ base64 перед коммитом. Сканеры это не всегда поймают, а атакующий раскодирует за секунду.
- Не откладывать ротацию до выяснения, воспользовался ли кто-то ключом. Выяснение занимает часы, ротация — минуты.
- Не переписывать историю общей ветки молча. Коллеги с локальными копиями вернут старые коммиты при следующем пуше; согласуйте и попросите переклонировать репозиторий.