keyguard

Escanea bases de código, proyectos de GCP y pipelines de CI en busca de credenciales expuestas de la API de Google, antes de que sean explotadas.

El problema: Google habilitó retroactivamente el acceso a la API de Gemini en claves API existentes (Maps, Places, etc.) que fueron diseñadas para ser públicas y estar incrustadas en código del lado del cliente. Cuando alguien de tu equipo activa Gemini en el mismo proyecto de GCP, esas claves ya públicas se convierten silenciosamente en credenciales de Gemini, exponiendo tu proyecto a usos no autorizados de IA e incidentes de facturación de más de $80k (contexto).

Lo que hace keyguard:

• keyguard scan — encuentra cadenas de credenciales en archivos de código y el historial de git usando regex + detección de entropía
• keyguard audit — se conecta a proyectos activos de GCP y marca las claves API que tienen acceso a Gemini en este momento
• keyguard ci — escanea los registros y variables de GitHub Actions, CircleCI y GitLab CI en busca de credenciales filtradas

---

Instalación

pip install keyguard-scan

O clona e instala en modo de desarrollo:

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

---

Inicio rápido

# Escanear el directorio actual y el historial de git
keyguard scan .

# Auditar tus proyectos activos de GCP
keyguard audit

# Escanear plataformas de CI
keyguard ci

---

Comandos

keyguard scan

Escanea archivos de código y el historial de git en busca de credenciales expuestas usando regex + filtrado de entropía de Shannon. Los marcadores de posición de baja entropía como "REPLACE_ME" o "XXXXXXXX" se ignoran automáticamente.

# Escanear un directorio (archivos + historial completo de git)
keyguard scan .

# Solo archivos, omitir historial de git
keyguard scan . --no-git-history

# Exportar a JSON y SARIF
keyguard scan . --output json --output sarif --out-file report

# Mostrar valores reales de las claves (sin ocultar)
keyguard scan . --no-redact

# Usar un archivo de configuración personalizado
keyguard scan . --config /path/to/.keyguard.toml

Códigos de salida: 0 = limpio, 1 = hallazgos, 2 = error

keyguard audit

Se conecta a proyectos activos de GCP a través de las APIs de Cloud Resource Manager, Service Usage y API Keys. Marca las claves que no tienen restricciones (acceso silencioso a Gemini) o que permiten explícitamente generativelanguage.googleapis.com mientras Gemini está habilitado en el proyecto.

La autenticación utiliza Application Default Credentials por defecto; ejecuta gcloud auth application-default login primero.

# Auditar todos los proyectos de GCP accesibles
keyguard audit

# Auditar proyecto(s) específico(s)
keyguard audit --project my-project-id --project another-project

# Usar un archivo de clave de cuenta de servicio
keyguard audit --gcp-credentials /path/to/key.json

# Exportar hallazgos en JSON
keyguard audit --output json --out-file gcp-findings.json

Hallazgos:

• CRITICAL — la clave no tiene restricciones de API + Gemini está habilitado (el escenario de actualización silenciosa de Maps a Gemini)
• HIGH — la clave permite explícitamente generativelanguage.googleapis.com (intencional pero posiblemente incrustada en código de cliente)

keyguard ci

Escanea los registros y variables almacenadas de las plataformas de CI en busca de credenciales expuestas. Compatible con GitHub Actions, CircleCI y GitLab CI.

# Escanear todas las plataformas configuradas
keyguard ci

# Escanear solo una plataforma
keyguard ci --platform github

# Limitar a un repositorio específico
keyguard ci --repo my-org/api-service

# Exportar hallazgos en JSON
keyguard ci --output json --out-file ci-findings.json

Qué escanea:

• GitHub Actions — variables de repositorio en texto plano + registros de ejecuciones de flujos de trabajo
• CircleCI — nombres de variables de entorno (los valores están ocultos por CircleCI) + registros de pasos de pipelines
• GitLab CI — variables de proyecto (texto plano) + trazas de pipelines

keyguard watch

Vuelve a escanear archivos en cada cambio. Útil durante el desarrollo.

keyguard watch .

keyguard rules list

Lista todas las reglas de detección activas.

keyguard rules list

keyguard config check

Valida un archivo de configuración .keyguard.toml.

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

---

Configuración

Crea un archivo .keyguard.toml en la raíz de tu proyecto:

[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 = []

# Autenticación y alcance de la plataforma de CI
[ci]
github_token    = "ghp_xxxxxxxxxxxxxxxxxxxx"
circleci_token  = "CCIPAT_xxxxxxxxxxxxxxxx"
gitlab_token    = "glpat-xxxxxxxxxxxxxxxxxxxx"
gitlab_url      = "https://gitlab.com"   # anular para GitLab autoalojado
max_runs        = 10                     # ejecuciones/pipelines recientes por repositorio

[ci.github]
orgs  = ["my-org"]
repos = ["my-org/specific-repo"]         # opcional: escanear solo repositorios específicos

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

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

---

Detección

Keyguard utiliza un enfoque de regex + entropía de Shannon. Cada regla define:

• Un patrón que coincide con la estructura de la credencial (ej., AIza[0-9A-Za-z\-_]{35} para claves API de Google)
• Un umbral mínimo de entropía que filtra los marcadores de posición de baja entropía

Las reglas integradas detectan:

ID de regla	Qué encuentra
google-api-key	Claves API de Google (AIza...) — incluyendo claves de Maps a las que se les otorgó silenciosamente acceso a Gemini
gcp-service-account-key	Claves privadas RSA de cuentas de servicio de GCP
google-oauth-client-secret	Secretos de cliente OAuth2 de Google (GOCSPX-...)

Puedes agregar reglas personalizadas en .keyguard.toml:

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

---

Integración con 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          # historial completo para el escaneo de git
      - run: pip install keyguard-scan
      - run: keyguard scan .

Hook de 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

---

Formatos de salida

Terminal (predeterminado) — tabla coloreada agrupada por gravedad.

JSON — array de hallazgos legible por máquina:

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

SARIF — se integra con la pestaña de Seguridad de GitHub y otras herramientas SAST:

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

Webhook de Slack — publica un resumen cuando se detectan hallazgos:

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

---

Desarrollo

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

143 tests, 0 fallos.