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

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

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

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

exfil-scan es un escáner heurístico. Está diseñado para reducir el riesgo y sacar a la luz salidas sospechosas, no para demostrar que el contenido es seguro.

Patrón de despliegue recomendado:

1. ejecuta el escáner en CI sobre prompts de prueba y salidas de fixtures
2. ejecuta el escáner en las protecciones de producción sobre las respuestas generadas
3. envía los hallazgos al triaje de analistas y a la telemetría
4. ajusta continuamente los umbrales de configuración a partir de la revisión de falsos positivos

14) Licencia

Este proyecto está bajo la Licencia MIT. Consulta LICENSE para ver los términos completos.

15) Contribuciones

Las contribuciones son bienvenidas. Al abrir un PR, incluye:

• pasos claros para reproducir el problema
• comportamiento esperado y real
• pruebas para la nueva lógica de detección
• actualizaciones de documentación al introducir nuevas reglas