Il guardiano che si blocca: quando il security check trova sé stesso

Nerd Level: 3/5
Il guardiano che si blocca: quando il security check trova sé stesso

La Paranoia È Giustificata

Quando lavori con API esterne (Gmail, GitHub, Cloudflare, Telegram, una dozzina di altre), prima o poi committi un token per sbaglio. Non è questione di se, ma di quando.

Magari è una riga di debug che ti sei dimenticato. Oppure hai creato un .env.local per testare e ti sei scordato di metterlo nel .gitignore. O ancora peggio: hai hardcodato un token “solo per un attimo”, e quell’attimo è diventato permanente.

Una volta che un secret finisce in Git, è compromesso. Forever. Anche se lo rimuovi nel commit successivo, è lì nella history. Qualcuno con accesso alla repo può recuperarlo. E se è una repo pubblica, game over.

Quindi qualche mese fa ho implementato un pre-commit hook che blocca commit con pattern sospetti. Si chiama Security Guardian, ed è abbastanza paranoico.

Come Funziona il Guardian

Quando faccio git commit, lo script analizza il diff prima di permettere il commit. Cerca pattern che sembrano token o credentials:

PATTERNS = {
    'ya29.': 'Gmail OAuth tokens',
    'ghp_': 'GitHub personal access tokens',
    'github_pat_': 'GitHub PAT (new format)',
    'GOCSPX-': 'Google OAuth client secrets',
    'sk-': 'OpenAI API keys',
    # ... 15+ pattern totali
}

Se trova un match → commit bloccato. Niente sconti, niente eccezioni.

Funziona bene. Forse troppo bene.

Quando il Guardiano Trova Sé Stesso

L’altro giorno stavo committando aggiornamenti alla documentazione del brain. Tra cui, appunto, il file del Security Guardian stesso. Aggiungo tutto, scrivo il commit message, invio.

git add .
git commit -m "Docs: Update security-guardian patterns"

E mi arriva questo:

❌ SECRETS FOUND IN FILES TO BE COMMITTED

File: .claude/agents/health-security-guardian
Pattern: ya29 dot
Line: +- Gmail tokens: `ya29 prefix`

File: .claude/agents/health-security-guardian
Pattern: ghp underscore
Line: +- GitHub tokens: `ghp prefix`, `github_pat prefix`

❌ COMMIT ABORTED

Il guardiano ha trovato sé stesso. Perfetto.

Il Meta-Problema

Il file di documentazione conteneva esempi letterali dei pattern che cerca. Per spiegare cosa blocca, avevo scritto cose tipo:

“Blocca commit con Gmail tokens (ya29. prefix)”

E ovviamente il guardian vede ya29. e dice “NOPE”.

È un classico meta-problem: come documenti i pattern che cerchi senza triggerarli? È come dire a qualcuno “non pensare a un elefante rosa”. Troppo tardi, ci sta già pensando.

La Soluzione: Descrizioni Generiche

Ho dovuto riscrivere la documentazione usando descrizioni invece di literal strings.

Prima (triggera il guardian):

## Security Patterns

Blocca commit con:
- Gmail tokens: ya29 dot prefix
- GitHub tokens: ghp underscore prefix
- Google OAuth: GOCSPX dash prefix

Dopo (safe):

## Security Patterns

Blocca commit con token patterns riconoscibili:
- Gmail OAuth tokens (ya29 prefix)
- GitHub personal tokens (ghp prefix)
- Google OAuth client secrets (GOCSPX prefix)

Cambio minimo: da ya29. a “ya29 prefix” (senza il dot). Abbastanza per evitare il match, ma ancora comprensibile.

Self-Awareness nei Security Tools

Test il Tool sul Tool

Se hai un security scanner, fallo girare sui suoi file.

# Test guardian sui propri file
python3 tools/agents/security-scanner.py check \
  tools/agents/health-security-guardian.md

Se trova match → fix la documentazione prima che diventi un problema al prossimo commit.

Pattern Astratti nella Docs

Evita literal examples:

Pattern: sk-proj-[A-Za-z0-9]{40}
Esempio: sk-proj-abc123def456ghi789...

Preferisci abstractions:

Pattern: sk-proj-[A-Za-z0-9]{40}
Esempio: [OpenAI project token format]

Esclusioni Selettive (con cautela)

In casi limite, puoi escludere file docs specifici dal security check. Ma attenzione: se hai troppi file esclusi, il guardian diventa inutile.

Meta-Commentary

Questo bug l’ho trovato io stesso. Beh, non proprio io (Giobi), ma Anacleto (l’AI che gestisce il brain).

Anacleto ha scritto la documentazione del Security Guardian senza pensare che i pattern letterali avrebbero triggerato il guardian stesso durante il commit. Ironia squared: l’AI che genera documentazione per tool di sicurezza viene bloccata dal tool stesso.

Fix applicato: Commit f6fdd94

Takeaway

  1. Security tools perfetti bloccano anche la propria documentation se contiene literal patterns
  2. Self-test è essenziale: Passa il guardian sui propri file prima di committare
  3. Abstract your examples: Descrizioni generiche > literal strings
  4. Meta-bugs sono divertenti ma fastidiosi da debuggare

E ora che ho pubblicato questo post… devo controllare che non contenga pattern che triggereranno il prossimo commit. 😅

Related: