Script de Envío por Lotes de Hybrid Analysis

Este script de Python escanea recursivamente una carpeta y envía archivos ejecutables, scripts, documentos y otros archivos relevantes a Hybrid Analysis (Falcon Sandbox) para análisis automatizado de malware.

Características

• Recorre recursivamente los directorios
• Envía solo tipos de archivo compatibles (ver lista más abajo)
• Omite archivos vacíos, de tamaño excesivo o enviados previamente
• Previene ataques de path traversal – asegura que los archivos estén dentro de la raíz del escaneo
• Omite enlaces simbólicos para evitar envíos duplicados o no deseados
• Utiliza una Sesión de requests persistente para una comunicación eficiente con la API
• Almacena la caché en un directorio de usuario dedicado (~/.hybrid_analysis_submitter/) para evitar contaminar las carpetas escaneadas
• Utiliza una caché local SHA‑256 para evitar envíos duplicados
• Maneja elegantemente la limitación de velocidad de la API (errores 429)
• Se detiene automáticamente cuando se agota la cuota de la API
• Admite configuración por línea de comandos de la carpeta, límite de tamaño de archivo, ID de entorno y nombre del archivo de caché
• Lee la clave API de un archivo .env por seguridad

Requisitos

• Python 3.6+
• Una clave API de Hybrid Analysis válida (nivel gratuito disponible)

Instalación

1. Clona o descarga este script en tu máquina local.

2. Instala los paquetes necesarios:

pip install requests python-dotenv

3. Crea un archivo .env en el mismo directorio que el script con tu clave API:

HYBRID_API_KEY=your_api_key_here

Puedes obtener una clave API registrándote en Hybrid Analysis.

Uso

Ejecuta el script desde la línea de comandos, especificando la carpeta a escanear:

python submit_to_hybrid.py /path/to/folder

Argumentos de Línea de Comandos

Ejemplos

Escanear una carpeta con configuración predeterminada:

python submit_to_hybrid.py C:\suspicious_files

Escanear una carpeta pero aumentar el límite de tamaño a 200 MB y usar un entorno diferente (ej., Android):

python submit_to_hybrid.py /home/user/samples --max-file-size 200 --environment-id 300

Usar un nombre de archivo de caché personalizado:

python submit_to_hybrid.py ./malware --cache-file my_cache.json

Ejemplo de Salida

Scanning folder: C:\suspicious_files

Submitting: C:\suspicious_files\malware.exe (2.34 MB)
 -> Success! Job ID: 5f8a9c2d3e4f5a6b7c8d9e0f
Submitting: C:\suspicious_files\document.pdf (0.12 MB)
 -> Success! Job ID: 6g9b0c1d2e3f4a5b6c7d8e9f
Skipping already submitted: C:\suspicious_files\malware.exe
Skipping symlink: C:\suspicious_files\link_to_malware.exe

Finished.
Files found:      42
Files submitted:  35
Files skipped:    6
Files failed:     1

Tipos de Archivo Compatibles

• Ejecutables de Windows (PE): .exe, .scr, .pif, .dll, .com, .cpl
• Instaladores y paquetes: .msi
• Scripts de Windows: .bat, .cmd, .ps1, .psd1, .psm1, .js, .vbs, .vbe, , ,

Para la lista oficial de todos los tipos de archivo compatibles, consulta las Preguntas Frecuentes de Hybrid Analysis.

Cómo Funciona

1. Recorrido recursivo – El script usa os.walk() para recorrer cada subcarpeta.
2. Verificaciones de seguridad – Verifica que cada archivo resuelva a una ruta dentro de la raíz del escaneo (previene path traversal) y omite enlaces simbólicos.
3. Filtrado de archivos – Verifica la extensión del archivo, el tamaño (se omiten archivos de 0 bytes o mayor a --max-file-size), y si el archivo ha sido enviado antes (caché SHA‑256).
4. Envío – Cada archivo se sube al endpoint https://hybrid-analysis.com/api/v2/submit/file usando una Sesión de requests persistente con tu clave API.
5. Limitación de velocidad – Después de cada envío, el script espera 2 segundos. Si recibe una respuesta HTTP 429 (Demasiadas solicitudes), cuenta el error. Después de 3 errores 429 consecutivos, el escaneo se detiene automáticamente.
6. Persistencia de caché – Los archivos enviados correctamente se almacenan en un archivo de caché JSON dentro de ~/.hybrid_analysis_submitter/ para que no se vuelvan a enviar en ejecuciones futuras. La caché se guarda ordenada para facilitar la lectura humana.

Limitación de Velocidad y Cuotas

• Las cuentas gratuitas de Hybrid Analysis tienen límites de envío por hora/día.
• El script detecta respuestas HTTP 429 y se detiene después de 3 errores de este tipo para evitar reintentos infinitos.
• Se añade una demora de 2 segundos entre envíos para ser respetuoso con la API.

Notas Importantes

• La clave API se lee solo del archivo .env – no la codifiques directamente.
• Los archivos vacíos (0 bytes) siempre se omiten.
• Los archivos mayores que --max-file-size se omiten.
• Solo se envían archivos con extensiones en ALLOWED_EXTENSIONS.
• Se omiten enlaces simbólicos para evitar envíos duplicados y confusión de rutas.
• Se previene el path traversal – el script omitirá cualquier archivo que resuelva fuera del directorio de escaneo especificado.
• La caché evita reenviar archivos idénticos en múltiples ejecuciones y se almacena en tu directorio de usuario (~/.hybrid_analysis_submitter/).
• El script usa un tiempo de espera de 120 segundos para cada solicitud HTTP.
• Los archivos de caché se almacenan en un directorio dedicado – no se mezclan con el contenido escaneado.

Solución de Problemas

Licencia

Este script se proporciona tal cual para fines educativos y de análisis de seguridad. Úsalo de manera responsable y de acuerdo con los Términos de Servicio de Hybrid Analysis.

Aviso Legal

Enviar archivos a un sandbox de terceros puede exponer contenido potencialmente sensible. Asegúrate de tener el derecho de compartir los archivos antes de subirlos.