Tailsnitch

Un auditor di sicurezza per le configurazioni Tailscale. Tailsnitch analizza la tua tailnet alla ricerca di 57 misconfigurazioni, controlli di accesso eccessivamente permissivi e violazioni delle best practice di sicurezza.

Avvio Rapido

# 1. Imposta le credenziali API Tailscale
export TS_API_KEY="tskey-api-..."

# 2. Esegui l'audit
tailsnitch

# 3. Mostra solo i risultati ad alta gravità
tailsnitch --severity high

# 4. Correggi alcuni problemi ~interattivamente~ modalità yolo
tailsnitch --fix

Installazione

Scarica il Binario Precompilato

Scarica l'ultima release da GitHub Releases.

Utenti macOS: Rimuovi l'attributo di quarantena dopo il download:

sudo xattr -rd com.apple.quarantine tailsnitch

Installa tramite Go

go install github.com/Adversis/tailsnitch@latest

Compila dal Codice Sorgente

git clone https://github.com/Adversis/tailsnitch.git
cd tailsnitch
go build -o tailsnitch .

Autenticazione

Tailsnitch supporta due metodi di autenticazione. OAuth è preferito quando entrambi sono configurati.

Opzione 1: Client OAuth (Consigliato)

I client OAuth forniscono accesso con ambiti definiti e verificabile che non scade quando i dipendenti lasciano l'azienda.

export TS_OAUTH_CLIENT_ID="..."
export TS_OAUTH_CLIENT_SECRET="tskey-client-..."

Crea un client OAuth su: https://login.tailscale.com/admin/settings/oauth

Ambiti richiesti per audit in sola lettura:

all:read copre tutto. Concessione degli ambiti singolarmente:

Qualsiasi ambito che tralasci influisce solo sui controlli che ne hanno bisogno: quei controlli segnalano di non aver potuto leggere l'impostazione anziché superare.

AUTH-005 e AUTH-006 leggono le identità federate della tailnet, che la console amministrativa chiama credenziali di trust. Arrivano dallo stesso elenco di chiavi delle chiavi di autenticazione, quindi ci si aspetta che auth_keys:read le copra. Ciò non è stato confermato su una tailnet live. Se l'elenco delle chiavi non può essere letto, entrambi i controlli segnalano "non valutato" anziché superare. Se un ambito mancante restituisce un errore o restituisce invece l'elenco con le identità filtrate non è confermato; se filtra silenziosamente, AUTH-005 segnalerebbe che non esistono credenziali di trust e AUTH-006 non troverebbe nulla da controllare.

Ambiti aggiuntivi per la modalità di correzione:

• devices:core - Elimina dispositivi, modifica tag (richiede selezione tag)
• auth_keys - Elimina chiavi di autenticazione

Tailnet Lock

DEV-010 e DEV-012 segnalano Tailnet Lock, che l'API Tailscale non espone come impostazione della tailnet. I dispositivi bloccati da esso sono visibili tramite l'API, ma determinare se il lock è abilitato richiede la CLI locale tailscale, che legge il daemon sulla macchina che esegue tailsnitch. Quando si esegue l'audit di un'altra tailnet con --tailnet, considera quella parte del risultato di conseguenza. Usa --tailscale-path se il binario si trova in una posizione non standard.

Opzione 2: Chiave API

Le chiavi API operano come l'utente che le ha create ed ereditano i permessi di quell'utente.

export TS_API_KEY="tskey-api-..."

Crea una chiave API su: https://login.tailscale.com/admin/settings/keys

Esempi di Utilizzo

Audit di Base

# Esegui audit completo
tailsnitch

# Mostra anche i controlli superati (verbose)
tailsnitch --verbose

# Output come JSON per l'elaborazione
tailsnitch --json

# Audita una tailnet specifica (quando il client OAuth ha accesso a più tailnet)
tailsnitch --tailnet mycompany.com

Filtra i Risultati

# Mostra solo problemi critici e ad alta gravità
tailsnitch --severity high

# Filtra per categoria
tailsnitch --category access    # Problemi ACL
tailsnitch --category auth      # Autenticazione e chiavi
tailsnitch --category device    # Sicurezza dispositivi
tailsnitch --category network   # Esposizione di rete
tailsnitch --category ssh       # Regole SSH
tailsnitch --category log       # Registrazione e amministrazione

# Esegui solo controlli specifici
tailsnitch --checks ACL-001,AUTH-001,DEV-010
tailsnitch --checks stale-devices,tailnet-lock-not-enabled

# Elenca tutti i controlli disponibili
tailsnitch --list-checks

Modalità di Correzione Interattiva

La modalità di correzione ti consente di rimediare ai problemi direttamente tramite l'API Tailscale:

# Modalità di correzione interattiva
tailsnitch --fix

# Anteprima di cosa verrebbe corretto (prova a secco)
tailsnitch --fix --dry-run

# Auto-selezione delle correzioni sicure (richiede comunque conferma)
tailsnitch --fix --auto

# Disabilita la registrazione audit delle azioni di correzione
tailsnitch --fix --no-audit-log

Elementi correggibili tramite API:

La modalità di correzione fornisce anche collegamenti diretti alla console amministrativa per i problemi che richiedono intervento manuale.

Esportazione Prove SOC 2

Genera report di prove per audit SOC 2 con mappature dei Criteri Comuni (CC):

# Esporta come JSON
tailsnitch --soc2 json > soc2-evidence.json

# Esporta come CSV (per fogli di calcolo)
tailsnitch --soc2 csv > soc2-evidence.csv

Il report SOC 2 include:

• Risultati dei test per risorsa (ogni dispositivo, chiave, regola ACL testata singolarmente)
• Mappature codici CC (CC6.1, CC6.2, CC6.3, CC6.6, CC7.1, CC7.2, ecc.)
• Stato Superato/Non Superato/N/D per ogni test di controllo
• Timestamp per la traccia di audit

Esempio di output CSV:

resource_type,resource_id,resource_name,check_id,check_title,cc_codes,status,details,tested_at
device,node123,prod-server,DEV-001,Tagged devices with key expiry disabled,CC6.1;CC6.3,PASS,Tags: [tag:server] key expiry enabled,2025-01-05T10:30:00Z
key,tskey-auth-xxx,tskey-auth-xxx,AUTH-001,Reusable auth keys exist,CC6.1;CC6.2;CC6.3,FAIL,Reusable key expires in 45 days,2025-01-05T10:30:00Z

Ignora Rischi Noti

Crea un file .tailsnitch-ignore per sopprimere i risultati per rischi noti e accettati:

# .tailsnitch-ignore
# Ignora controlli informativi
ACL-008  # Non usiamo intenzionalmente i gruppi
ACL-009  # Gli ACL legacy vanno bene per il nostro caso d'uso

# Ignora controlli medi specifici con giustificazione
DEV-006  # I dispositivi esterni sono appaltatori approvati
LOG-001  # I log di flusso richiedono il piano Enterprise

# Ignora un singolo elemento all'interno di un controllo, invece di silenziare l'intero controllo
ACL-011:tag:monitoring  # ampio di proposito; ogni altro tag viene comunque controllato
AUTH-001:tskey-auth-xxxx  # ruota automaticamente tramite CI, tracciato in TICKET-123

Una riga identifica o un intero controllo (ACL-011) o un singolo elemento al suo interno (CHECK-ID:item, diviso sul primo due punti - l'elemento stesso può contenere due punti). Una regola per singolo elemento sopprime solo quell'elemento: il controllo continua a essere eseguito e segnala comunque tutto il resto che trova. Sopprimere ogni elemento segnalato non trasforma mai un controllo non superato in uno superato - il risultato rimane, declassato a Informativo, quindi un risultato soppresso non viene mai letto come un controllo soddisfatto.

Posizioni dei file di ignore (controllate in ordine):

1. .tailsnitch-ignore nella directory corrente
2. ~/.tailsnitch-ignore nella home directory

Poiché la prima posizione è la directory di lavoro, un file di ignore può provenire da un repository anziché da te. Ogni esecuzione segnala quale file ha utilizzato e quanti risultati ed elementi ha soppresso, e --json registra questo nei campi ignore_file e ignored (CHECK-ID per un intero controllo, CHECK-ID:item per un singolo elemento soppresso). Usa --no-ignore per saltare il file.

# Usa un file di ignore specifico
tailsnitch --ignore-file /path/to/ignore

# Disabilita completamente l'elaborazione del file di ignore
tailsnitch --no-ignore

Esportazione ed Elaborazione JSON

# Esporta report completo
tailsnitch --json > audit.json

# Estrai controlli non superati come TSV
tailsnitch --json | jq -r '
  .suggestions
  | map(select(.pass == false))
  | .[]
  | [.id, .title, .severity, .remediation]
  | @tsv
' > findings.tsv

# Riepilogo per gravità
tailsnitch --json | jq '
  .suggestions
  | map(select(.pass == false))
  | group_by(.severity)
  | map({severity: .[0].severity, count: length})
'

# Elenca problemi critici/ad alta gravità con collegamenti amministrativi
tailsnitch --json | jq -r '
  .suggestions
  | map(select(.pass == false and (.severity == "CRITICAL" or .severity == "HIGH")))
  | .[]
  | "\(.id): \(.title)\n  Fix: \(.fix.admin_url // "manual")\n"
'

Riferimento Comandi

Controlli di Sicurezza

Tailsnitch esegue 57 controlli di sicurezza in 7 categorie. Vedi docs/CHECKS.md per la documentazione dettagliata di ogni controllo.

Gravità Critica

Gravità Alta

Gravità Media

Informativo

Controlli per configurazione di registrazione, impostazioni DNS, ruoli utente ed elementi di verifica manuale.

Gravità che dipende dal risultato

Diversi controlli valutano ciò che trovano anziché avere una gravità fissa. Tre meritano di essere menzionati:

• ACL-011 segnala la portata di ogni tag come Informativo. Fallisce solo quando un tag che una chiave di autenticazione può assegnare raggiunge una destinazione wildcard, una sottorete instradata o l'egress del nodo di uscita: Alta se una chiave riutilizzabile assegna quel tag, Media se solo una chiave monouso lo fa. Un conteggio di dispositivi non determina mai la gravità.
• AUTH-005 segnala Medio quando la tailnet non ha alcuna credenziale di trust, e Basso quando le credenziali di trust esistono ma una chiave riutilizzabile crea ancora tag che nessuna di esse copre.
• AUTH-006 segnala Alto per un soggetto che è solo un wildcard, e Basso per un wildcard più ristretto o un audience mancante.

Esempio di Output

+=====================================================================+
|                    TAILSNITCH SECURITY AUDIT                        |
|            Tailnet: example.com                                     |
|            Version: 1.0.0 (build: abc123)                           |
+=====================================================================+

  Using ignore file: .tailsnitch-ignore (3 rules)

=== ACCESS CONTROLS ===================================================

[CRITICAL] ACL-001: Default 'allow all' policy active
  Your ACL policy omits the 'acls' field. Tailscale applies a
  default 'allow all' policy, granting all devices full access.

  Remediation:
  Define explicit ACL rules following least privilege principle.

  Source: https://tailscale.com/docs/reference/examples/acls
----------------------------------------------------------------------

=== AUTHENTICATION & KEYS =============================================

[HIGH] AUTH-001: Reusable auth keys exist
  Found 2 reusable auth key(s). These can be reused to add
  multiple devices if compromised.

  Details:
    - Key tskey-auth-xxx (expires in 45 days)
    - Key tskey-auth-yyy (expires in 89 days)

  Remediation:
  Store reusable keys in a secrets manager. Prefer one-off keys.

  Source: https://tailscale.com/docs/features/access-control/auth-keys
----------------------------------------------------------------------

SUMMARY
======================================================================
  Critical: 1  High: 3  Medium: 5  Low: 2  Info: 8
  Total findings: 19  |  Passed: 33

Controlli Tailnet Lock

I controlli Tailnet Lock (DEV-010, DEV-012) richiedono la CLI locale tailscale e vengono eseguiti sul daemon della macchina locale. Quando si audita una tailnet remota tramite --tailnet, questi controlli riflettono lo stato locale, non quello della tailnet auditata.

# Specifica un percorso binario tailscale personalizzato se necessario
tailsnitch --tailscale-path /opt/tailscale/bin/tailscale

Integrazione CI/CD

Esegui Tailsnitch nelle pipeline CI/CD per individuare regressioni di sicurezza:

# GitHub Actions example
- name: Audit Tailscale Security
  env:
    TS_OAUTH_CLIENT_ID: ${{ secrets.TS_OAUTH_CLIENT_ID }}
    TS_OAUTH_CLIENT_SECRET: ${{ secrets.TS_OAUTH_CLIENT_SECRET }}
  run: |
    tailsnitch --json > audit.json
    # Fail if critical or high severity issues exist
    if tailsnitch --severity high --json | jq -e '.summary.critical + .summary.high > 0' > /dev/null; then
      echo "Critical or high severity issues found!"
      tailsnitch --severity high
      exit 1
    fi

Riferimenti

• Tailscale Security Hardening Guide
• ACL Syntax Reference
• Tailscale SSH
• Audit Logging
• Tailnet Lock

Licenza

MIT

Contributi

Vedi CONTRIBUTING.md per le linee guida.