keyguard

Examine codebases, projetos GCP e pipelines de CI em busca de credenciais expostas da API do Google — antes que sejam exploradas.

O problema: O Google habilitou retroativamente o acesso à API Gemini em chaves de API existentes (Maps, Places, etc.) que foram projetadas para serem públicas e incorporadas em código do lado do cliente. Quando alguém da sua equipe ativa o Gemini no mesmo projeto GCP, essas chaves já públicas se tornam silenciosamente credenciais do Gemini — expondo seu projeto a uso não autorizado de IA e incidentes de faturamento de mais de US$ 80 mil (contexto).

O que o keyguard faz:

• keyguard scan — encontra strings de credenciais em arquivos de código e histórico do git usando regex + detecção de entropia
• keyguard audit — conecta-se a projetos GCP ativos e sinaliza chaves de API que têm acesso ao Gemini agora
• keyguard ci — examina logs e variáveis do GitHub Actions, CircleCI e GitLab CI em busca de credenciais vazadas

Instalação

pip install keyguard-scan

Ou clone e instale em modo de desenvolvimento:

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

Início Rápido

# Scan current directory and git history
keyguard scan .

# Audit your live GCP projects
keyguard audit

# Scan CI platforms
keyguard ci

Comandos

keyguard scan

Examina arquivos de código e o histórico do git em busca de credenciais expostas usando regex + filtragem de entropia de Shannon. Placeholders de baixa entropia como "REPLACE_ME" ou "XXXXXXXX" são ignorados automaticamente.

# Scan a directory (files + full git history)
keyguard scan .

# Files only, skip git history
keyguard scan . --no-git-history

# Export to JSON and SARIF
keyguard scan . --output json --output sarif --out-file report

# Show actual key values (not redacted)
keyguard scan . --no-redact

# Use a custom config file
keyguard scan . --config /path/to/.keyguard.toml

Códigos de saída: 0 = limpo, 1 = resultados, 2 = erro

keyguard audit

Conecta-se a projetos GCP ativos por meio das APIs Cloud Resource Manager, Service Usage e API Keys. Sinaliza chaves que não têm restrições (acesso silencioso ao Gemini) ou que explicitamente permitem generativelanguage.googleapis.com enquanto o Gemini está ativado no projeto.

A autenticação usa Application Default Credentials por padrão — execute gcloud auth application-default login primeiro.

# Audit all accessible GCP projects
keyguard audit

# Audit specific project(s)
keyguard audit --project my-project-id --project another-project

# Use a service account key file
keyguard audit --gcp-credentials /path/to/key.json

# Export JSON findings
keyguard audit --output json --out-file gcp-findings.json

Resultados:

• CRITICAL — chave não tem restrições de API + Gemini está ativado (o cenário de atualização silenciosa de Maps para Gemini)
• HIGH — chave permite explicitamente generativelanguage.googleapis.com (intencional, mas possivelmente incorporada em código do cliente)

keyguard ci

Examina logs e variáveis armazenadas de plataformas de CI em busca de credenciais expostas. Suporta GitHub Actions, CircleCI e GitLab CI.

# Scan all configured platforms
keyguard ci

# Scan one platform only
keyguard ci --platform github

# Narrow to a specific repo
keyguard ci --repo my-org/api-service

# Export JSON findings
keyguard ci --output json --out-file ci-findings.json

O que ele examina:

• GitHub Actions — variáveis de repositório em texto simples + logs de execução de workflows
• CircleCI — nomes de variáveis de ambiente (valores são mascarados pelo CircleCI) + logs de etapas de jobs de pipeline
• GitLab CI — variáveis de projeto (texto simples) + traces de jobs de pipeline

keyguard watch

Reexamina arquivos a cada alteração. Útil durante o desenvolvimento.

keyguard watch .

keyguard rules list

Lista todas as regras de detecção ativas.

keyguard rules list

keyguard config check

Valida um arquivo de configuração .keyguard.toml.

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

Configuração

Crie um .keyguard.toml na raiz do seu projeto:

[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 platform authentication and scope
[ci]
github_token    = "ghp_xxxxxxxxxxxxxxxxxxxx"
circleci_token  = "CCIPAT_xxxxxxxxxxxxxxxx"
gitlab_token    = "glpat-xxxxxxxxxxxxxxxxxxxx"
gitlab_url      = "https://gitlab.com"   # override for self-hosted GitLab
max_runs        = 10                     # recent runs/pipelines per repo

[ci.github]
orgs  = ["my-org"]
repos = ["my-org/specific-repo"]         # optional: scan specific repos only

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

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

Detecção

O Keyguard usa uma abordagem de regex + entropia de Shannon. Cada regra define:

• Um padrão que corresponde à estrutura da credencial (ex.: AIza[0-9A-Za-z\-_]{35} para chaves de API do Google)
• Um limite mínimo de entropia que filtra placeholders de baixa entropia

As regras internas detectam:

Você pode adicionar regras personalizadas em .keyguard.toml:

[[rules.extra]]
id = "my-internal-token"
description = "Internal service token"
pattern = "tok-[0-9a-f]{32}"
entropy_min = 3.5
severity = "high"
tags = ["internal"]

Integração com 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          # full history for git scan
      - run: pip install keyguard-scan
      - run: keyguard scan .

Pre-commit hook

# .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

Formatos de Saída

Terminal (padrão) — tabela colorida agrupada por severidade.

JSON — array de resultados legível por máquina:

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

SARIF — integra-se com a aba de Segurança do GitHub e outras ferramentas SAST:

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

Webhook do Slack — envia um resumo quando resultados são detectados:

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

Desenvolvimento

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

143 testes, 0 falhas.

Estrutura do projeto:

keyguard/
  scanner/      # file + git history scanners
  engine/       # regex + entropy detection (rules, matcher)
  output/       # terminal, JSON/SARIF, webhook
  auditor/      # GCP API client + audit logic
  ci/           # GitHub Actions, CircleCI, GitLab CI scanners
  cli.py        # Click CLI entry point
  config.py     # .keyguard.toml loader

Roadmap

• v1 — Scanner de arquivos (código fonte + histórico do git)
• v2 — Auditor de API GCP (auditoria de projetos ativos via APIs GCP)
• v3 — Integração com plataformas CI (GitHub Actions, CircleCI, GitLab CI)

Licença

MIT