keyguard

Scansiona codebase, progetti GCP e pipeline CI per credenziali API di Google esposte — prima che vengano sfruttate.

Il problema: Google ha abilitato retroattivamente l'accesso all'API Gemini su chiavi API esistenti (Maps, Places, ecc.) progettate per essere pubbliche e incorporate nel codice lato client. Quando qualcuno del tuo team abilita Gemini nello stesso progetto GCP, quelle chiavi già pubbliche diventano silenziosamente credenziali Gemini — esponendo il tuo progetto a utilizzi non autorizzati dell'AI e a incidenti di fatturazione da oltre $80k (contesto).

Cosa fa keyguard:

• keyguard scan — trova stringhe di credenziali nei file sorgente e nella cronologia Git utilizzando regex + rilevamento dell'entropia
• keyguard audit — si connette ai progetti GCP live e segnala le chiavi API che hanno accesso a Gemini in questo momento
• keyguard ci — scansiona log e variabili di GitHub Actions, CircleCI e GitLab CI per credenziali trapelate

Install

pip install keyguard-scan

Oppure clona e installa in modalità sviluppo:

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

Quick Start

# Scansiona la directory corrente e la cronologia Git
keyguard scan .

# Controlla i tuoi progetti GCP live
keyguard audit

# Scansiona le piattaforme CI
keyguard ci

Comandi

keyguard scan

Scansiona file sorgente e cronologia Git per credenziali esposte usando regex + filtro dell'entropia di Shannon. I placeholder a bassa entropia come "REPLACE_ME" o "XXXXXXXX" vengono automaticamente ignorati.

# Scansiona una directory (file + cronologia Git completa)
keyguard scan .

# Solo file, salta la cronologia Git
keyguard scan . --no-git-history

# Esporta in JSON e SARIF
keyguard scan . --output json --output sarif --out-file report

# Mostra i valori effettivi delle chiavi (non oscurati)
keyguard scan . --no-redact

# Usa un file di configurazione personalizzato
keyguard scan . --config /path/to/.keyguard.toml

Codici di uscita: 0 = pulito, 1 = rilevamenti, 2 = errore

keyguard audit

Si connette ai progetti GCP live tramite le API Cloud Resource Manager, Service Usage e API Keys. Segnala le chiavi che sono senza restrizioni (accesso silenzioso a Gemini) o che consentono esplicitamente generativelanguage.googleapis.com mentre Gemini è abilitato sul progetto.

L'autenticazione utilizza per impostazione predefinita le Application Default Credentials — esegui prima gcloud auth application-default login.

# Controlla tutti i progetti GCP accessibili
keyguard audit

# Controlla progetti specifici
keyguard audit --project my-project-id --project another-project

# Usa un file di chiave dell'account di servizio
keyguard audit --gcp-credentials /path/to/key.json

# Esporta rilevamenti in JSON
keyguard audit --output json --out-file gcp-findings.json

Rilevamenti:

• CRITICAL — chiave senza restrizioni API + Gemini abilitato (lo scenario di upgrade silenzioso Maps→Gemini)
• HIGH — chiave che permette esplicitamente generativelanguage.googleapis.com (intenzionale ma potenzialmente incorporata nel codice client)

keyguard ci

Scansiona log e variabili memorizzate delle piattaforme CI per credenziali esposte. Supporta GitHub Actions, CircleCI e GitLab CI.

# Scansiona tutte le piattaforme configurate
keyguard ci

# Scansiona solo una piattaforma
keyguard ci --platform github

# Limita a un repository specifico
keyguard ci --repo my-org/api-service

# Esporta rilevamenti in JSON
keyguard ci --output json --out-file ci-findings.json

Cosa scansiona:

• GitHub Actions — variabili di repository in testo semplice + log dei job di esecuzione dei workflow
• CircleCI — nomi di variabili d'ambiente (i valori sono mascherati da CircleCI) + log degli step delle pipeline
• GitLab CI — variabili di progetto (in testo semplice) + tracce dei job delle pipeline

keyguard watch

Riesegue la scansione a ogni modifica dei file. Utile durante lo sviluppo.

keyguard watch .

keyguard rules list

Elenca tutte le regole di rilevamento attive.

keyguard rules list

keyguard config check

Valida un file di configurazione .keyguard.toml.

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

Configurazione

Crea un file .keyguard.toml nella root del progetto:

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

# Autenticazione e ambito delle piattaforme CI
[ci]
github_token    = "ghp_xxxxxxxxxxxxxxxxxxxx"
circleci_token  = "CCIPAT_xxxxxxxxxxxxxxxx"
gitlab_token    = "glpat-xxxxxxxxxxxxxxxxxxxx"
gitlab_url      = "https://gitlab.com"   # override per GitLab self-hosted
max_runs        = 10                     # esecuzioni/pipeline recenti per repo

[ci.github]
orgs  = ["my-org"]
repos = ["my-org/specific-repo"]         # opzionale: scansiona solo repo specifici

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

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

Rilevamento

Keyguard utilizza un approccio regex + entropia di Shannon. Ogni regola definisce:

• Un pattern che corrisponde alla struttura della credenziale (es. AIza[0-9A-Za-z\-_]{35} per le chiavi API di Google)
• Una soglia minima di entropia che filtra i placeholder a bassa entropia

Le regole integrate rilevano:

Puoi aggiungere regole personalizzate in .keyguard.toml:

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

Integrazione 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          # cronologia completa per la scansione Git
      - 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

Formati di output

Terminale (predefinito) — tabella colorata raggruppata per gravità.

JSON — array di rilevamenti leggibili dalla macchina:

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

SARIF — si integra con la scheda Sicurezza di GitHub e altri strumenti SAST:

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

Webhook Slack — invia un riepilogo quando vengono rilevati problemi:

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

Sviluppo

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

143 test, 0 fallimenti.

Struttura del progetto:

keyguard/
  scanner/      # scanner di file + cronologia Git
  engine/       # rilevamento regex + entropia (regole, matcher)
  output/       # terminale, JSON/SARIF, webhook
  auditor/      # client API GCP + logica di audit
  ci/           # scanner per GitHub Actions, CircleCI, GitLab CI
  cli.py        # punto di ingresso CLI Click
  config.py     # caricatore di .keyguard.toml

Roadmap

• v1 — Scanner di file (codice sorgente + cronologia Git)
• v2 — Auditor API GCP (audit live dei progetti tramite API GCP)
• v3 — Integrazione piattaforme CI (GitHub Actions, CircleCI, GitLab CI)

Licenza

MIT