Script de soumission par lots Hybrid Analysis

Ce script Python parcourt récursivement un dossier et soumet les fichiers exécutables, scripts, documents et autres fichiers pertinents à Hybrid Analysis (Falcon Sandbox) pour une analyse automatisée des malwares.

Fonctionnalités

• Parcours récursif des répertoires
• Soumet uniquement les types de fichiers pris en charge (voir la liste ci-dessous)
• Ignore les fichiers vides, trop volumineux ou déjà soumis
• Empêche les attaques de type path traversal – vérifie que les fichiers se trouvent dans la racine de numérisation
• Ignore les liens symboliques pour éviter les soumissions en double ou non intentionnelles
• Utilise une Session requests persistante pour une communication API efficace
• Stocke le cache dans un répertoire utilisateur dédié (~/.hybrid_analysis_submitter/) pour ne pas polluer les dossiers numérisés
• Utilise un cache SHA‑256 local pour éviter les soumissions en double
• Gère gracieusement la limitation de débit de l'API (erreurs 429)
• S'arrête automatiquement lorsque le quota de l'API est épuisé
• Supporte la configuration en ligne de commande du dossier, de la taille limite des fichiers, de l'ID d'environnement et du nom du fichier cache
• Lit la clé API à partir d'un fichier .env pour des raisons de sécurité

Prérequis

• Python 3.6+
• Une clé API Hybrid Analysis valide (un niveau gratuit est disponible)

Installation

1. Clonez ou téléchargez ce script sur votre machine locale.

2. Installez les paquets requis :

pip install requests python-dotenv

3. Créez un fichier .env dans le même répertoire que le script avec votre clé API :

HYBRID_API_KEY=votre_cle_api_ici

Vous pouvez obtenir une clé API en vous inscrivant sur Hybrid Analysis.

Utilisation

Exécutez le script depuis la ligne de commande en spécifiant le dossier à numériser :

python submit_to_hybrid.py /chemin/vers/dossier

Arguments en ligne de commande

Exemples

Numériser un dossier avec les paramètres par défaut :

python submit_to_hybrid.py C:\fichiers_suspects

Numériser un dossier mais augmenter la limite de taille à 200 Mo et utiliser un environnement différent (ex. Android) :

python submit_to_hybrid.py /home/utilisateur/echantillons --max-file-size 200 --environment-id 300

Utiliser un nom de fichier cache personnalisé :

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

Exemple de sortie

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

Types de fichiers pris en charge

• Exécutables Windows (PE) : .exe, .scr, .pif, .dll, .com, .cpl
• Installateurs et packages : .msi
• Scripts Windows : .bat, .cmd, .ps1, .psd1, .psm1, .js, .vbs, .vbe, , ,

Pour la liste officielle de tous les types de fichiers pris en charge, consultez la FAQ Hybrid Analysis.

Comment ça fonctionne

1. Parcours récursif – Le script utilise os.walk() pour traverser chaque sous‑dossier.
2. Vérifications de sécurité – Il vérifie que chaque fichier se résout en un chemin à l'intérieur de la racine de numérisation (empêche le path traversal) et ignore les liens symboliques.
3. Filtrage des fichiers – Il vérifie l'extension du fichier, la taille (les fichiers vides ou plus grands que --max-file-size sont ignorés) et si le fichier a déjà été soumis (cache SHA‑256).
4. Soumission – Chaque fichier est téléchargé vers le point d’accès https://hybrid-analysis.com/api/v2/submit/file en utilisant une Session requests persistante avec votre clé API.
5. Limitation de débit – Après chaque soumission, le script attend 2 secondes. S'il reçoit une réponse HTTP 429 (Too Many Requests), il compte l'erreur. Après 3 erreurs 429 consécutives, la numérisation s'arrête automatiquement.
6. Persistance du cache – Les fichiers soumis avec succès sont stockés dans un fichier cache JSON dans ~/.hybrid_analysis_submitter/ afin de ne pas être à nouveau soumis lors des exécutions futures. Le cache est enregistré trié pour une meilleure lisibilité.

Limitation de débit et quotas

• Les comptes gratuits Hybrid Analysis ont des limites de soumissions horaires/quotidiennes.
• Le script détecte les réponses HTTP 429 et s'arrête après 3 erreurs de ce type pour éviter des tentatives infinies.
• Un délai de 2 secondes est ajouté entre les soumissions pour respecter l'API.

Notes importantes

• La clé API est lue uniquement à partir du fichier .env – ne l'écrivez pas en dur.
• Les fichiers vides (0 octet) sont toujours ignorés.
• Les fichiers plus grands que --max-file-size sont ignorés.
• Seuls les fichiers avec des extensions dans ALLOWED_EXTENSIONS sont soumis.
• Les liens symboliques sont ignorés pour éviter les soumissions en double et les confusions de chemins.
• Le path traversal est empêché – le script ignorera tout fichier qui se résout en dehors du répertoire de numérisation spécifié.
• Le cache empêche la re‑soumission de fichiers identiques entre plusieurs exécutions et est stocké dans votre répertoire utilisateur (~/.hybrid_analysis_submitter/).
• Le script utilise un délai d'attente de 120 secondes pour chaque requête HTTP.
• Les fichiers cache sont stockés dans un répertoire dédié – ils ne sont pas mélangés avec le contenu numérisé.

Dépannage

Licence

Ce script est fourni tel quel à des fins éducatives et d'analyse de sécurité. Utilisez-le de manière responsable et conformément aux Conditions d'utilisation d'Hybrid Analysis.

Avertissement

Soumettre des fichiers à un bac à sable tiers peut exposer un contenu potentiellement sensible. Assurez-vous d'avoir le droit de partager les fichiers avant de les télécharger.