exfil-scan

Scansiona gli output LLM e i contenuti generati dall'IA per individuare segnali di esfiltrazione di dati prima che raggiungano gli utenti, i log o i sistemi a valle.

1) Perché esiste exfil-scan

Le applicazioni LLM moderne elaborano di routine prompt sensibili, documenti interni, risposte API e dati utente. Questo crea un nuovo confine di sicurezza: il livello di output.

La famiglia di attacchi EchoLeak (incluso CVE-2025-32711) ha dimostrato come payload nascosti o offuscati possano essere incorporati nel testo generato e utilizzati per esfiltrare dati tramite strumenti, collegamenti o catene di parsing.

Gli scanner tradizionali si concentrano su file, dipendenze e traffico runtime. Non ispezionano l'output del modello generato in modo specificamente progettato.

exfil-scan fornisce un "antivirus per risposte LLM":

• ispeziona testo semplice, JSON, markdown e log
• identifica sei classi di pattern di esfiltrazione sospetti
• riporta i risultati con gravità e posizione
• si integra facilmente nei flussi di lavoro CI/CD e di sviluppo locale

2) Cosa rileva

3) Caratteristiche principali

• Tre profili di sensibilità: low, medium, high
• Supporto per override della configurazione YAML
• Input da stdin, singolo file o directory
• Output in text, json, markdown o html
• Codici di uscita stabili per l'automazione
• API Python pulita per l'integrazione in altri strumenti

4) Installazione

Installazione dal sorgente

git clone https://github.com/your-org/exfil-scan.git
cd exfil-scan
pip install -e .

Installazione pip standard (quando pubblicato)

pip install exfil-scan

Installazione per lo sviluppo

pip install -e ".[dev]"
pytest

5) Avvio rapido

Scansione dell'output LLM tramite pipe

echo 'api_key: sk-ABCDEFGHIJKLMNOPQRSTUVWXYZ123456' | exfil-scan

Scansione di un singolo file

exfil-scan --input output.txt

Scansione ricorsiva di una directory

exfil-scan --directory ./model-logs --recursive

6) Riferimento opzioni CLI

Note:

• Usa --input oppure --directory, non entrambi.
• Se non viene fornito alcun percorso, lo strumento legge da stdin.
• Se vengono rilevati problemi, il processo termina con codice 1.

7) Esempi di utilizzo per formato di output

Output in testo semplice

exfil-scan --input suspicious.txt --format text

Stile previsto:

exfil-scan report
=================
Scanned targets: 1
Total findings: 2

1. [HIGH] metadata_leaks/known_token_format:openai_key
   Location: suspicious.txt:1:10
   Description: Matched known credential/token format (openai_key).

Output JSON

exfil-scan --input suspicious.txt --format json

Struttura prevista:

{
  "finding_count": 2,
  "scanned_targets": ["suspicious.txt"],
  "findings": [
    {
      "category": "metadata_leaks",
      "rule": "known_token_format:openai_key",
      "severity": "HIGH",
      "description": "Matched known credential/token format (openai_key).",
      "location": "suspicious.txt:1:10",
      "snippet": "..."
    }
  ]
}

Output HTML

exfil-scan --directory ./outputs --recursive --format html --output report.html

Comportamento previsto:

• Genera una pagina HTML autonoma con la tabella dei risultati
• Esegue l'escape del contenuto per un rendering sicuro
• Include gravità, categoria, regola, posizione, descrizione

Output Markdown

exfil-scan --input suspicious.txt --format markdown --output report.md

Stile previsto:

# exfil-scan Report

- Scanned targets: 1
- Total findings: 2

8) Configurazione e sensibilità

Il repository include default-config.yaml. Puoi passare un tuo file con --config.

Regolazione della sensibilità:

• low: meno falsi positivi, soglie più alte
• medium: impostazioni predefinite bilanciate
• high: rileva pattern più sottili

Override della sensibilità da CLI:

exfil-scan --input out.txt --sensitivity high

9) Pattern personalizzati e regolazione delle policy

Puoi aggiungere i tuoi formati di token e le tue chiavi di metadati:

sensitivity: medium
rules:
  metadata_keys:
    - api_key
    - db_password
    - internal_token
  token_patterns:
    custom_jwt: "\\beyJ[A-Za-z0-9_\\-]{10,}\\.[A-Za-z0-9_\\-]{10,}\\.[A-Za-z0-9_\\-]{10,}\\b"
    corp_secret: "\\bcorp_[A-Za-z0-9]{24,}\\b"

Quindi esegui:

exfil-scan --input response.log --config ./my-config.yaml

10) Panoramica dell'architettura

Responsabilità dei moduli:

• exfil_scan/cli.py: parsing degli argomenti, selezione dell'input, rendering dell'output, gestione dell'uscita
• exfil_scan/config.py: valori predefiniti, caricamento YAML, merge ricorsivo, normalizzazione dei profili
• exfil_scan/scanner.py: sei motori di rilevamento, dataclass per i risultati, formattazione del report
• tests/test_scan.py: test di regressione per rilevamento e formati di output

Flusso di esecuzione:

1. La CLI analizza gli argomenti.
2. La configurazione carica i valori predefiniti + gli override opzionali.
3. Lo scanner legge il testo da stdin/file/directory.
4. Ogni categoria abilitata viene eseguita in modo indipendente.
5. I risultati vengono ordinati per gravità e renderizzati.
6. Il codice di uscita comunica esito positivo/negativo/errore per l'automazione.

11) Codici di uscita

Questo rende l'integrazione CI semplice:

exfil-scan --directory ./artifacts --recursive --format json --output exfil-report.json

Se viene rilevato qualcosa, il tuo job può fallire rapidamente in base al codice di uscita 1.

12) Test

Esegui i test:

pytest

La copertura include:

• tutte e sei le categorie di rilevamento
• formattazione del report in tutte e quattro le modalità di output
• asserzioni a livello di regola per un comportamento stabile

13) Note sulla sicurezza

exfil-scan è uno scanner euristico. È progettato per ridurre il rischio e far emergere output sospetti, non per dimostrare la sicurezza del contenuto.

Schema di distribuzione consigliato:

1. esegui lo scanner in CI su prompt di test e output di fixture
2. esegui lo scanner come guardrail di produzione sulle risposte generate
3. instrada i risultati al triage degli analisti e alla telemetria
4. regola continuamente le soglie di configurazione in base alla revisione dei falsi positivi

14) Licenza

Questo progetto è concesso in licenza MIT. Consulta LICENSE per i termini completi.

15) Contributi

I contributi sono benvenuti. Quando apri una PR, includi:

• passaggi di riproduzione chiari
• comportamento atteso ed effettivo
• test per la nuova logica di rilevamento
• aggiornamenti della documentazione quando introduci nuove regole