exfil-scan

Analiza las salidas de LLM y el contenido generado por IA en busca de señales de exfiltración de datos antes de que lleguen a los usuarios, los registros o los sistemas posteriores.

---

1) Por qué existe exfil-scan

Las aplicaciones modernas con LLM procesan habitualmente prompts sensibles, documentos internos, respuestas de API y datos de usuario. Eso crea una nueva frontera de seguridad: la capa de salida.

La familia de ataques EchoLeak (incluido CVE-2025-32711) demostró cómo se pueden incrustar payloads ocultos u ofuscados en el texto generado y usarlos para exfiltrar datos a través de herramientas, enlaces o cadenas de análisis.

Los escáneres tradicionales se centran en archivos, dependencias y tráfico en tiempo de ejecución. No inspeccionan la salida generada por el modelo de una manera específicamente diseñada para ello.

exfil-scan proporciona un "escáner de virus para respuestas de LLM":

• inspecciona texto plano, JSON, markdown y registros
• identifica seis clases de patrones sospechosos de exfiltración
• notifica hallazgos con gravedad y ubicación
• se integra limpiamente en flujos de trabajo de CI/CD y de desarrollo local

---

2) Qué detecta

Categoría	Gravedad	Qué se detecta
Texto oculto	ALTA	Secuencias Unicode de ancho cero e invisibles utilizadas para ocultar payloads
Datos codificados	ALTA	Secuencias de escapes Base64/hex/octal/unicode que probablemente transportan contenido codificado
Datos en URL	MEDIA	Cadenas de consulta sospechosamente largas y payloads codificados en parámetros de URL
Fugas de metadatos	ALTA	Claves similares a credenciales y formatos de token en salidas estructuradas/no estructuradas
Esteganografía Unicode	MEDIA	Controles bidireccionales y palabras de estilo homoglifo con escritura mixta
Anomalías estructurales	BAJA	Secuencias extremas de saltos de línea/tabulaciones y artefactos de codificación con carácter de reemplazo

---

3) Principales características

• Tres perfiles de sensibilidad: low, medium, high
• Soporte de anulación de configuración YAML
• Entrada desde stdin, un único archivo o un directorio
• Salida en text, json, markdown o html
• Códigos de salida estables para automatización
• API de Python limpia para integrarla en otras herramientas

---

4) Instalación

Instalar desde el código fuente

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

Instalación estándar con pip (cuando esté publicada)

pip install exfil-scan

Instalación para desarrollo

pip install -e ".[dev]"
pytest

---

5) Inicio rápido

Escanear salida de LLM canalizada

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

Escanear un único archivo

exfil-scan --input output.txt

Escanear un directorio de forma recursiva

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

---

6) Referencia de opciones de CLI

Opción	Tipo	Valor por defecto	Descripción
-i, --input	ruta	ninguno	Escanea un archivo de entrada
-d, --directory	ruta	ninguno	Escanea todos los archivos compatibles de un directorio
-r, --recursive	indicador	false	Recorre subdirectorios con --directory
-c, --config	ruta	ninguno	Ruta del archivo de configuración YAML
-s, --sensitivity	low|medium|high	config/default	Sobrescribe el perfil de sensibilidad
-f, --format	text|json|html|markdown	text	Define el formato del informe
-o, --output	ruta	stdout	Escribe el informe renderizado en un archivo
--version	indicador	n/a	Muestra la versión de la CLI
-h, --help	indicador	n/a	Muestra el uso y los argumentos

Notas:

• Usa --input o --directory, no ambos.
• Si no se proporciona ninguna ruta, la herramienta lee desde stdin.
• Si existen hallazgos, el proceso termina con el código 1.

---

7) Ejemplos de uso según el formato de salida

Salida en texto plano

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

Estilo esperado:

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).

Salida JSON

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

Estructura esperada:

{
  "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": "..."
    }
  ]
}

Salida HTML

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

Comportamiento esperado:

• Genera una página HTML independiente con una tabla de hallazgos
• Escapa el contenido para renderizarlo de forma segura
• Incluye gravedad, categoría, regla, ubicación y descripción

Salida Markdown

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

Estilo esperado:

# exfil-scan Report

- Scanned targets: 1
- Total findings: 2

---

8) Configuración y sensibilidad

El repositorio incluye default-config.yaml. Puedes pasar tu propio archivo con --config.

Ajuste de sensibilidad:

• low: menos falsos positivos, umbrales más grandes
• medium: valores por defecto equilibrados
• high: detecta patrones más sutiles

Sobrescritura de sensibilidad desde CLI:

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

---

9) Patrones personalizados y ajuste de políticas

Puedes añadir tus propios formatos de token y claves de metadatos:

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"

Luego ejecuta:

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

---

10) Resumen de la arquitectura

Responsabilidades de los módulos:

• exfil_scan/cli.py: análisis de argumentos, selección de entrada, renderizado de salida y gestión de códigos de salida
• exfil_scan/config.py: valores por defecto, carga de YAML, fusión recursiva y normalización de perfiles
• exfil_scan/scanner.py: seis motores de detección, dataclasses de hallazgos y formato del informe
• tests/test_scan.py: pruebas de regresión de detección y formatos de salida

Flujo de ejecución:

1. La CLI analiza los argumentos.
2. La configuración carga los valores por defecto más las anulaciones opcionales.
3. El escáner lee el texto desde stdin/archivo/directorio.
4. Cada categoría habilitada se ejecuta de forma independiente.
5. Los hallazgos se ordenan por gravedad y se renderizan.
6. El código de salida comunica éxito/fallo/error para la automatización.

---

11) Códigos de salida

Código	Significado
0	Sin hallazgos (limpio)
1	Hallazgos detectados
2	Error de ejecución o de argumentos

Esto hace que la integración en CI sea sencilla:

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

Si se detecta cualquier hallazgo, tu trabajo puede fallar rápidamente basándose en el código de salida 1.

---

12) Pruebas

Ejecuta las pruebas:

pytest

La cobertura incluye:

• las seis categorías de detección
• el formato del informe en los cuatro modos de salida
• aserciones a nivel de regla para un comportamiento estable

---

13) Notas de seguridad