keyguard

Сканируйте кодовые базы, проекты GCP и CI-пайплайны на предмет раскрытых учётных данных Google API — до того, как их используют злоумышленники.

Проблема: Google ретроактивно включил доступ к Gemini API для существующих ключей API (Maps, Places и т.д.), которые были разработаны для публичного использования и встраивания в клиентский код. Когда кто-то из вашей команды включает Gemini в том же проекте GCP, эти уже опубликованные ключи бесшумно становятся учётными данными Gemini — что приводит к несанкционированному использованию AI и инцидентам с выставлением счетов на $80k+ (контекст).

Что делает keyguard:

keyguard scan — находит строки учётных данных в исходных файлах и истории git с помощью регулярных выражений и детекции энтропии
keyguard audit — подключается к живым проектам GCP и помечает ключи API, которые имеют доступ к Gemini прямо сейчас
keyguard ci — сканирует логи и переменные GitHub Actions, CircleCI и GitLab CI на предмет утёкших учётных данных

Установка

pip install keyguard-scan

Или клонируйте и установите в режиме разработки:

git clone https://github.com/arzaan789/keyguard.git
cd keyguard
pip install -e ".[dev]"

Быстрый старт

# Сканировать текущую директорию и историю git
keyguard scan .

# Аудит ваших живых проектов GCP
keyguard audit

# Сканировать CI-платформы
keyguard ci

Команды

`keyguard scan`

Сканирует исходные файлы и историю git на наличие раскрытых учётных данных, используя регулярные выражения и фильтрацию по энтропии Шеннона. Низкоэнтропийные заполнители вроде "REPLACE_ME" или "XXXXXXXX" автоматически игнорируются.

# Сканировать директорию (файлы + полная история git)
keyguard scan .

# Только файлы, без истории git
keyguard scan . --no-git-history

# Экспорт в JSON и SARIF
keyguard scan . --output json --output sarif --out-file report

# Показывать фактические значения ключей (не скрытые)
keyguard scan . --no-redact

# Использовать собственный конфигурационный файл
keyguard scan . --config /path/to/.keyguard.toml

Коды выхода: 0 = чисто, 1 = найдено, 2 = ошибка

`keyguard audit`

Подключается к живым проектам GCP через Cloud Resource Manager, Service Usage и API Keys APIs. Помечает ключи, которые не имеют ограничений (бесшумный доступ к Gemini) или которые явно разрешают generativelanguage.googleapis.com при включённом Gemini в проекте.

Аутентификация по умолчанию использует Application Default Credentials — сначала выполните gcloud auth application-default login.

# Аудит всех доступных проектов GCP
keyguard audit

# Аудит конкретного проекта(ов)
keyguard audit --project my-project-id --project another-project

# Использовать файл ключа сервисного аккаунта
keyguard audit --gcp-credentials /path/to/key.json

# Экспорт результатов в JSON
keyguard audit --output json --out-file gcp-findings.json

Результаты:

CRITICAL — у ключа нет ограничений API + Gemini включён (сценарий бесшумного обновления Maps→Gemini)
HIGH — ключ явно разрешает generativelanguage.googleapis.com (намеренно, но потенциально встроен в клиентский код)

`keyguard ci`

Сканирует логи CI-платформ и сохранённые переменные на предмет раскрытых учётных данных. Поддерживает GitHub Actions, CircleCI и GitLab CI.

# Сканировать все настроенные платформы
keyguard ci

# Сканировать только одну платформу
keyguard ci --platform github

# Сузить до конкретного репозитория
keyguard ci --repo my-org/api-service

# Экспорт результатов в JSON
keyguard ci --output json --out-file ci-findings.json

Что сканируется:

GitHub Actions — текстовые переменные репозитория + логи задач воркфлоу
CircleCI — имена переменных окружения (значения маскируются CircleCI) + логи шагов пайплайнов
GitLab CI — переменные проекта (текстовые) + трассировки задач пайплайнов

`keyguard watch`

Повторно сканирует файлы при каждом изменении. Полезно во время разработки.

keyguard watch .

`keyguard rules list`

Выводит список всех активных правил детекции.

keyguard rules list

`keyguard config check`

Проверяет конфигурационный файл .keyguard.toml.

keyguard config check
keyguard config check --config /path/to/.keyguard.toml

Конфигурация

Создайте .keyguard.toml в корне проекта:

[scan]
paths = ["."]
exclude = ["tests/fixtures/", "**/*.example"]
scan_git_history = true

[output]
format = ["terminal", "json"]
redact = true

[notify]
slack_webhook = "https://hooks.slack.com/services/..."

[rules]
disabled = []

# Аутентификация и область действия для CI
[ci]
github_token    = "ghp_xxxxxxxxxxxxxxxxxxxx"
circleci_token  = "CCIPAT_xxxxxxxxxxxxxxxx"
gitlab_token    = "glpat-xxxxxxxxxxxxxxxxxxxx"
gitlab_url      = "https://gitlab.com"   # переопределение для self-hosted GitLab
max_runs        = 10                     # последние запуски/пайплайны на репозиторий

[ci.github]
orgs  = ["my-org"]
repos = ["my-org/specific-repo"]         # опционально: сканировать только конкретные репозитории

[ci.circleci]
orgs = ["my-org"]

[ci.gitlab]
groups = ["my-group"]

Детекция

Keyguard использует подход регулярные выражения + энтропия Шеннона. Каждое правило определяет:

Шаблон, соответствующий структуре учётных данных (например, AIza[0-9A-Za-z\-_]{35} для ключей Google API)
Минимальный порог энтропии, который отсеивает низкоэнтропийные заполнители

Встроенные правила обнаруживают:

Идентификатор правила	Что находит
`google-api-key`	Ключи Google API (`AIza...`) — включая ключи Maps, которым бесшумно предоставлен доступ к Gemini

Вы можете добавить собственные правила в .keyguard.toml:

[[rules.extra]]
id = "my-internal-token"
description = "Внутренний токен сервиса"
pattern = "tok-[0-9a-f]{32}"
entropy_min = 3.5
severity = "high"
tags = ["internal"]

Интеграция с CI

GitHub Actions

name: keyguard scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # полная история для сканирования git
      - run: pip install keyguard-scan
      - run: keyguard scan .

Pre-commit хук

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: keyguard
        name: keyguard credential scan
        entry: keyguard scan --no-git-history
        language: system
        pass_filenames: false

Docker

docker run --rm -v $(pwd):/repo ghcr.io/arzaan789/keyguard scan /repo

Форматы вывода

Терминал (по умолчанию) — цветная таблица, сгруппированная по уровню серьёзности.

JSON — массив результатов, читаемый машиной:

keyguard scan . --output json --out-file findings.json

SARIF — интегрируется с вкладкой Безопасность GitHub и другими инструментами SAST:

keyguard scan . --output sarif --out-file findings.sarif

Slack webhook — отправляет сводку при обнаружении результатов:

[notify]
slack_webhook = "https://hooks.slack.com/services/..."

Разработка

git clone https://github.com/arzaan789/keyguard.git
cd keyguard
pip install -e ".[dev]"
pytest

143 теста, 0 ошибок.

Структура проекта:

keyguard/
  scanner/      # сканеры файлов и истории git
  engine/       # детекция по регулярным выражениям и энтропии (правила, сопоставитель)
  output/       # терминал, JSON/SARIF, webhook
  auditor/      # клиент GCP API и логика аудита
  ci/           # сканеры GitHub Actions, CircleCI, GitLab CI
  cli.py        # точка входа CLI (Click)
  config.py     # загрузчик .keyguard.toml

План развития

v1 — Сканер файлов (исходный код + история git)
v2 — Аудитор GCP API (аудит живых проектов через GCP API)
v3 — Интеграция с CI-платформами (GitHub Actions, CircleCI, GitLab CI)

Лицензия

MIT

keyguard

Популярное

keyguard

Установка

Быстрый старт

Команды

keyguard scan

keyguard audit

keyguard ci

keyguard watch

keyguard rules list

keyguard config check

Конфигурация

Детекция

Интеграция с CI

GitHub Actions

Pre-commit хук

Docker

Форматы вывода

Разработка

План развития

Лицензия

`keyguard scan`

`keyguard audit`

`keyguard ci`

`keyguard watch`

`keyguard rules list`

`keyguard config check`