Table des matières

• Aperçu
• Exemple d'utilisation de ThePhish
  • Un utilisateur envoie un email à ThePhish
  • L'analyste analyse l'email
• Implémentation
• Installation
  • Installation avec Docker et Docker Compose
  • Installation à partir de zéro
• Configurer les analyseurs
  • Configurer les niveaux des analyseurs
  • Analyseurs testés
  • Activer l'analyseur MISP
  • Activer l'analyseur Yara
• Activer le répondant Mailer
• Utiliser la liste blanche
• Contribution à TheHive4py
• Contribution à Cortex-Analyzers
• Licence
• Publications académiques
• Qui parle de ThePhish
• Dépôts GitHub mentionnant ThePhish
• Crédits

Aperçu

Le diagramme suivant montre le fonctionnement de ThePhish à haut niveau :

1. Un attaquant lance une campagne de phishing et envoie un email de phishing à un utilisateur.
2. Un utilisateur qui reçoit un tel email peut l'envoyer en pièce jointe à la boîte aux lettres utilisée par ThePhish.
3. L'analyste interagit avec ThePhish et sélectionne l'email à analyser.
4. ThePhish extrait tous les observables de l'email et crée un cas sur TheHive. Les observables sont analysés grâce à Cortex et ses analyseurs.
5. ThePhish calcule un verdict basé sur les verdicts des analyseurs.
6. Si le verdict est définitif, le cas est clôturé et l'utilisateur est notifié. De plus, s'il s'agit d'un email malveillant, le cas est exporté vers MISP.
7. Si le verdict n'est pas définitif, l'intervention de l'analyste est nécessaire. Il doit examiner le cas sur TheHive avec les résultats donnés par les différents analyseurs pour formuler un verdict, puis il peut envoyer la notification à l'utilisateur, exporter éventuellement le cas vers MISP et clôturer le cas.

Exemple d'utilisation de ThePhish

Cet exemple vise à montrer comment un utilisateur peut envoyer un email à ThePhish pour qu'il soit analysé et comment un analyste peut analyser cet email en utilisant ThePhish.

Un utilisateur envoie un email à ThePhish

Un utilisateur peut envoyer un email à l'adresse email utilisée par ThePhish pour récupérer les emails à analyser. L'email doit être transféré en pièce jointe au format EML afin d'éviter la contamination de l'en-tête de l'email. Dans ce cas, le client de messagerie utilisé est Mozilla Thunderbird et l'adresse email utilisée est une adresse Gmail.

L'analyste analyse l'email

L'analyste navigue vers la page web de ThePhish et clique sur le bouton « Liste des emails » pour obtenir la liste des emails à analyser.

Lorsque l'analyste clique sur le bouton « Analyser » correspondant à l'email sélectionné, l'analyse démarre et sa progression s'affiche sur l'interface web.

Pendant ce temps, ThePhish extrait les observables (URLs, domaines, adresses IP, adresses email, pièces jointes et empreintes de ces pièces jointes) de l'email, puis interagit avec TheHive pour créer le cas.

Trois tâches sont créées à l'intérieur du cas.

Ensuite, ThePhish commence à ajouter les observables extraits au cas.

À ce stade, l'utilisateur est notifié par email que l'analyse a commencé grâce au répondant Mailer.

La description de la première tâche permet au répondant Mailer d'envoyer la notification par email.

Une fois la première tâche clôturée, la deuxième tâche démarre et les analyseurs sont lancés sur les observables. La progression de l'analyse est affichée sur l'interface web pendant le lancement des analyseurs.

La progression de l'analyse peut également être consultée sur TheHive, grâce à son flux en direct.

Une fois que tous les analyseurs ont terminé leur exécution, la deuxième tâche est clôturée et la troisième démarre, puis ThePhish calcule le verdict. Comme le verdict est « malveillant », tous les observables jugés malveillants sont marqués comme IoC. Dans ce cas, un seul observable est marqué comme IoC.

Le cas est ensuite exporté vers MISP en tant qu'événement, avec un seul attribut représenté par l'observable mentionné ci-dessus.

Ensuite, ThePhish envoie le verdict par email à l'utilisateur grâce au répondant Mailer.

Enfin, la tâche et le cas sont clôturés. La description de la troisième tâche permet au répondant Mailer d'envoyer le verdict par email. De plus, le cas a été clôturé après cinq minutes et résolu comme « Vrai Positif » avec « Aucun impact », ce qui signifie que l'attaque a été détectée avant de pouvoir causer des dégâts.

Une fois le cas clôturé, le verdict est disponible pour l'analyste sur l'interface web, ainsi que tout le journal de la progression de l'analyse.

À ce stade, l'analyste peut revenir en arrière et analyser un autre email. Le cas ci-dessus concernait un email de phishing, mais un flux de travail similaire peut être observé lorsque l'email analysé est classé comme « sûr ». En effet, le cas est clôturé et le verdict est envoyé par email à l'utilisateur.

Ensuite, le verdict est également affiché à l'analyste sur l'interface web.

D'autre part, lorsqu'un email est classé comme « suspect », le verdict est uniquement affiché à l'analyste sur l'interface web.

À ce stade, l'analyste doit utiliser les boutons sur le côté gauche de la page pour utiliser TheHive, Cortex et MISP pour une analyse plus poussée. En effet, l'analyse n'est pas encore terminée, donc l'utilisateur est seulement informé que l'analyse de l'email qu'il a transféré à ThePhish a commencé. En effet, la dernière tâche et le cas ne sont pas encore clôturés car ils doivent être fermés par l'analyste lui-même une fois qu'il élabore un verdict final.

L'analyste peut consulter les rapports de tous les analyseurs sur TheHive et Cortex et, si cela ne s'avère pas suffisant, il peut également télécharger le fichier EML de l'email et l'analyser manuellement.

Lorsque l'analyste termine l'analyse, il peut remplir le corps de l'email à envoyer à l'utilisateur dans la description de la dernière tâche, lancer le répondant Mailer, exporter le cas vers MISP si le verdict est « malveillant » en cliquant sur le bouton « Exporter », puis clôturer le cas.

Implémentation

ThePhish est une application web écrite en Python 3. Le serveur web est implémenté avec Flask, tandis que la partie front-end de l'application, qui est la page dynamique écrite en HTML, CSS et JavaScript, est implémentée avec Bootstrap. Outre le module serveur web, la logique back-end de l'application est constituée de trois modules Python qui encapsulent la logique de l'application elle-même et d'une classe Python utilisée pour prendre en charge la journalisation via le protocole WebSocket. Si vous souhaitez voir une représentation graphique de la logique de l'application, cliquez ici. De plus, plusieurs fichiers de configuration sont utilisés par les modules susmentionnés à diverses fins.

Lorsque l'analyste navigue vers l'URL de base de l'application, la page web de ThePhish est chargée et une connexion bidirectionnelle est établie avec le serveur. Cela est réalisé en utilisant la bibliothèque JavaScript Socket.IO dans la page web qui permet une communication en temps réel, bidirectionnelle et basée sur les événements entre le navigateur et le serveur. Cette connexion est établie via une connexion WebSocket lorsque cela est possible et utilise le long polling HTTP comme solution de repli. Pour que cela fonctionne, l'application serveur utilise la bibliothèque Python Flask-SocketIO, qui fournit une intégration Socket.IO pour les applications Flask. Cette connexion est ensuite utilisée par ThePhish pour afficher la progression de l'analyse sur l'interface web.

Chaque fois que l'analyste effectue une action sur l'interface web, une requête AJAX est envoyée au serveur, une requête HTTP asynchrone qui permet d'échanger des données avec le serveur en arrière-plan et de mettre à jour la page sans la recharger. Cela permet à l'analyste à la fois de visualiser la liste des emails à analyser et de lancer l'analyse.

ThePhish interagit avec TheHive et Cortex grâce à TheHive4py et Cortex4py. De plus, il interagit avec un serveur IMAP pour récupérer les emails à analyser.

Installation

Installation avec Docker et Docker Compose

Étant donné que l'installation et la configuration des services TheHive, Cortex et MISP à partir de zéro pour un environnement de production peuvent ne pas être très simples, TheHive Project fournit des images Docker et des modèles Docker Compose ici pour faciliter la procédure d'installation. Pour simplifier, les modèles fournis sont simples, sans fournir toutes les options de configuration de chaque image Docker.

Si vous souhaitez simplement essayer ThePhish ou le faire fonctionner le plus rapidement possible, vous pouvez utiliser le modèle Docker fourni dans le dossier docker, qui est une version modifiée d'un des modèles Docker fournis par TheHive Project et qui permet également de créer un conteneur ThePhish. Pour installer ThePhish avec Docker et Docker Compose, veuillez vous référer à ce guide. Je recommande vivement de l'installer de cette manière au moins la première fois que vous l'utilisez, afin que vous puissiez apprendre les bases et comment le configurer avec une configuration minimale qui devrait fonctionner du premier coup. En effet, le guide précédemment lié fournit également une procédure pas à pas pour configurer les instances TheHive, Cortex et MISP.

Installation à partir de zéro

Ce guide concerne la seule installation de ThePhish, qui nécessite :

• Une instance opérationnelle de TheHive
• Une instance opérationnelle de Cortex
• Une instance opérationnelle de MISP
• Une adresse email que les utilisateurs peuvent utiliser pour envoyer des emails à ThePhish
• Un système d'exploitation basé sur Linux avec Python 3.8+ installé

Pour installer, configurer et intégrer les instances TheHive, Cortex et MISP, veuillez vous référer à leur documentation officielle :

• Documentation TheHive
• Documentation Cortex
• Documentation MISP

Il est conseillé que l'adresse email depuis laquelle ThePhish récupère les emails à analyser soit une adresse Gmail, car c'est celle avec laquelle ThePhish a été le plus testé. Il est préférable que le compte soit nouvellement créé, dans le seul but d'être utilisé par ThePhish. La procédure pour activer le mot de passe d'application requis par ThePhish pour se connecter à la boîte aux lettres et récupérer les emails est expliquée ici.

Cette procédure d'installation a été testée sur une VM exécutant Ubuntu 20.04.3 LTS avec Python 3.8 installé et les versions de TheHive, Cortex et MISP indiquées dans ce fichier docker-compose.yml.

Une fois que TheHive, Cortex et MISP sont configurés et écoutent à une certaine URL, et que l'adresse email est prête à être utilisée, vous pouvez installer et configurer ThePhish.

1. Cloner le dépôt

   root@kitploit:~

   $ git clone https://github.com/emalderson/ThePhish.git
   

2. Créer un environnement virtuel Python et l'activer (c'est une bonne pratique mais pas obligatoire)

   root@kitploit:~

   $ cd ThePhish/app
   $ sudo apt install python3-venv
   $ python3 -m venv venv
   $ source venv/bin/activate
   

3. Installer les dépendances

   root@kitploit:~

   $ pip install -r requirements.txt
   

4. Ajouter la fonction run_responder() au fichier api.py de TheHive4py

   Pour envoyer des emails à l'utilisateur, ThePhish utilise le répondant Mailer. Comme ThePhish utilise TheHive4py pour interagir avec TheHive, une fonction permettant d'exécuter un répondant par son ID est nécessaire. Malheureusement, cette fonction ne fait pas encore partie de TheHive4py, mais une pull request a été faite pour l'ajouter à TheHive4py (#219). En attendant qu'elle soit ajoutée, elle doit être ajoutée manuellement en utilisant la commande suivante pour que ThePhish fonctionne correctement (remplacez la version de Python dans la commande si vous utilisez une version différente de Python) :

   root@kitploit:~

   $ (cat << _EOF_
   
   
       def run_responder(self, responder_id, object_type, object_id):
           req = self.url + "/api/connector/cortex/action"
           try:
               data = json.dumps({ "responderId": responder_id, "objectType": object_type, "objectId": object_id})
               return requests.post(req, headers={"Content-Type": "application/json"}, data=data, proxies=self.proxies, auth=self.auth, verify=self.cert)
           except requests.exceptions.RequestException as e:
               raise TheHiveException("Responder run error: {}".format(e))
   _EOF_
   ) | tee -a venv/lib/python3.8/site-packages/thehive4py/api.py > /dev/null
   

5. Configuration

   Le fichier configuration.json est le fichier de configuration global qui permet de paramétrer la connexion à la boîte aux lettres et aux instances de TheHive, Cortex et MISP. Il permet également de paramétrer les éléments liés aux cas qui seront créés sur TheHive.

   root@kitploit:~

   {
   	"imap" : {
   		"host" : "imap.gmail.com",
   		"port" : "993",
   		"user" : "",
   		"password" : "",
   		"folder" : "inbox"
   	},
   	"thehive" : {
   		"url" : "http://thehive:9000",
   		"apikey" : ""
   	},
   	"cortex" : {
   		"url" : "http://cortex:9001",
   		"apikey" : "",
   		"id" : "local"
   	},
   	"misp" : {
   		"id" : "MISP THP"
   	},
   	"case" : {
   		"tlp" : "2",
   		"pap" : "2",
   		"tags" : ["email", "ThePhish"]
   	}
   }
   

   • Dans la partie imap, si vous utilisez une adresse Gmail, vous devez uniquement définir le nom d'utilisateur utilisé pour se connecter au serveur IMAP (qui est votre adresse email) et le mot de passe d'application.
   • Dans la partie thehive, vous devez définir l'URL à laquelle l'instance TheHive est accessible et définir la clé API de l'utilisateur créé sur TheHive que ThePhish utilisera pour interagir avec TheHive.
   • Dans la partie cortex, vous devez définir l'URL à laquelle l'instance Cortex est accessible et définir la clé API de l'utilisateur créé sur Cortex que ThePhish et TheHive utiliseront pour interagir avec Cortex. De plus, vous devez définir l'ID attribué à l'instance Cortex.
   • Dans la partie misp, vous devez uniquement définir l'ID attribué à l'instance MISP.
   • Dans la partie case, vous pouvez définir les niveaux TLP et PAP par défaut pour les cas créés par ThePhish ainsi que les tags qui leur seront appliqués lors de leur création.

   Vous pouvez apprendre comment créer une organisation et un utilisateur avec le rôle org-admin dans cette organisation sur TheHive et obtenir sa clé API ici (documentation ThePhish, recommandée) ou . De même, vous pouvez apprendre comment créer une organisation et un utilisateur avec les rôles dans cette organisation sur Cortex et obtenir sa clé API ou .

6. Lancer l'application

Le serveur qui sera utilisé pour exécuter l'application est le serveur WSGI fourni par eventlet, car il est listé dans les dépendances. Il est nécessaire pour que le protocole WebSocket fonctionne et éviter de recourir au long polling HTTP. Sans eventlet, le serveur WSGI par défaut de Flask (Werkzeug) sera utilisé. Si vous souhaitez utiliser un autre serveur WSGI (par exemple Gunicorn) ou un proxy inverse (par exemple NGINX), la documentation de Flask-SocketIO explique comment procéder.

L'application devrait maintenant être accessible à l'adresse http://localhost:8080.

⚠️ Attention : Si vous utilisez Mozilla Firefox pour utiliser ThePhish et que pour une raison quelconque un message d'erreur apparaît pendant l'analyse, la solution peut se trouver ici.

Configurer les analyseurs

ThePhish peut lancer un analyseur ou un répondeur uniquement s'il est activé et correctement configuré sur Cortex. Cette partie de la documentation explique comment les activer, tandis que cette partie liste les analyseurs et répondeurs disponibles avec leurs paramètres de configuration. Il est à noter que si de nombreux analyseurs sont gratuits, certains nécessitent un accès spécial et d'autres exigent un abonnement valide ou une licence produit.

Configurer les niveaux des analyseurs

Chaque analyseur produit un rapport au format JSON qui contient un niveau de malveillance pour un observable pouvant être « info », « safe », « suspicious » ou « malicious ». Cependant, même si la structure du rapport suit généralement une convention, cette convention n'est pas toujours respectée. De plus, après l'analyse du code de nombreux analyseurs et plusieurs tests, certains analyseurs se sont avérés contenir des bugs. Pour cette raison, des ajustements et des solutions de contournement ont été utilisés soit pour obtenir malgré tout les niveaux de malveillance fournis par ces analyseurs, soit pour empêcher l'application de planter à cause de ces bugs.

Par ailleurs, ces niveaux ne représentent pas toujours le niveau réel de malveillance d'un observable. Comme cela dépend de la façon dont les analyseurs eux-mêmes ont été programmés, ThePhish est livré avec un autre fichier de configuration appelé analyzers_level_conf.json, avec lequel il est possible de créer une correspondance entre les niveaux de malveillance réels fournis par un analyseur et les niveaux décidés par l'analyste. En plus de cela, ce fichier permet à l'analyste de choisir quels sont les types d'observables auxquels ces modifications doivent être appliquées. Le fichier doit suivre la structure illustrée dans l'exemple ci-dessous, en utilisant le nom exact des analyseurs à configurer et avec le niveau souhaité à droite. Si un analyseur n'est pas listé dans ce fichier, alors les niveaux de malveillance qu'il fournit sont laissés inchangés.```json { "DomainMailSPFDMARC_Analyzer_1_1" : { "dataType" : ["url", "ip", "domain", "mail"], "levelMapping" : { "malicious" : "suspicious", "suspicious" : "suspicious", "safe" : "safe", "info" : "info" } }, "MISP_2_1" : { "dataType" : ["url", "ip", "domain", "mail"], "levelMapping" : { "malicious" : "malicious", "suspicious" : "malicious", "safe" : "safe", "info" : "info" } } }

Alors que les parties liées à la correspondance exacte et à la correspondance par expressions régulières sont utilisées sans aucune modification, les parties restantes servent à créer trois autres listes d'expressions régulières. Il n'est pas nécessaire de concevoir des expressions régulières complexes pour activer ces fonctionnalités, vous devez seulement ajouter les domaines aux listes appropriées et ThePhish fera le reste. Par exemple, dans l'exemple ci-dessus, non seulement le domaine «paypal.com» est filtré, mais tout sous-domaine, URL et adresse e-mail contenant le domaine «paypal.com» est également filtré. Ces expressions régulières ont été conçues pour éviter certains comportements indésirables, par exemple elles empêchent que des domaines comme «paypal.com.attacker.com» soient accidentellement mis sur liste blanche.

Remarque : Si vous ajoutez un domaine sous «domainsInSubdomains», le domaine lui-même sera également filtré. Par conséquent, il n'est pas nécessaire d'ajouter le même domaine à la liste des domaines sous «exactMatching». La distinction est faite pour les cas où seul le domaine doit être mis sur liste blanche, et non ses sous-domaines. Ainsi, dans cet exemple, inclure «paypal.com» dans les deux listes est redondant.

Le fichier de liste blanche fourni dans ce dépôt contient déjà quelques observables mis sur liste blanche, mais il ne s'agit que d'un exemple, vous pouvez (et devriez) le modifier selon vos besoins en supprimant ou ajoutant des éléments.

Contribution à TheHive4py

ThePhish utilise une excellente fonctionnalité de TheHive : la possibilité d'exporter un cas vers MISP en tant qu'événement. Cela permet d'utiliser l'analyseur MISP_2_1 pour rechercher une correspondance entre un observable dans un cas et un attribut de l'un de ces événements sur MISP. Malheureusement, lors des premières étapes de développement de ThePhish, une fonction permettant de le faire via l'API en Python n'était pas encore disponible dans TheHive4py. Pour cette raison, une pull request (#187) a été faite à TheHive4py pour ajouter cette fonctionnalité. La pull request a été acceptée et la fonction export_to_misp() a été ajoutée au jalon 1.8.0 de TheHive4py.

Contribution à Cortex-Analyzers

ThePhish repose fortement sur les analyseurs fournis par Cortex. Pour garantir leur bon fonctionnement, des pull requests sont faites au dépôt qui les contient. Voici une liste mise à jour de ces pull requests :

• Correction de KasperskyTIP : la catégorie orange précédemment ignorée est désormais malveillante (#1270)
• Correction de PhishTank : ajout d'un en-tête User-Agent pour faire fonctionner à nouveau l'API PhishTank (#1271)
• Correction de SpamHausDBL : remplacement de la fonction de requête (ne fonctionnant pas) par la fonction de résolution (#1272)

Licence

ThePhish est un logiciel open-source et gratuit distribué sous la licence AGPL (Affero General Public License).

Publications académiques

• ITASEC 2022 : Conférence italienne sur la cybersécurité, 20–23 juin 2022, Rome, Italie
  • Lien vers les actes : https://ceur-ws.org/Vol-3260/
  • Lien vers l'article : https://ceur-ws.org/Vol-3260/paper6.pdf

Qui parle de ThePhish

• SecSI - https://secsi.io/blog/thephish-an-automated-phishing-email-analysis-tool/
• The Daily Swig - https://portswigger.net/daily-swig/thephish-the-most-complete-non-commercial-phishing-email-analysis-tool

Dépôts GitHub mentionnant ThePhish

• TheHive-Project/awesome
• matiassingers/awesome-readme

Crédits

Ce projet a commencé en 2020 et une version précoce et incomplète a été présentée comme mon travail final pour l'obtention du diplôme au Cybersecurity HackAdemy organisé par l'Université de Naples Federico II. Pour cela, je tiens à remercier Roberto Celletti pour l'idée initiale et mon équipe composée de gianpor, MrFelpon et xdinax, qui m'ont aidé dans les premières étapes du développement de l'application avec le déploiement initial et les premiers tests.

Ensuite, j'ai entièrement repensé l'outil en termes de fonctionnalités, de logo et d'interface utilisateur, ajouté la prise en charge de Docker et rédigé une documentation complète afin de le présenter comme mémoire de fin d'études pour mon master en ingénierie informatique en 2021 à l'Université de Naples Federico II sous la direction de Simon Pietro Romano (spromano).

Je tiens également à remercier Xavier Mertens (xme) pour avoir développé IMAP2TheHive et l'avoir publié sur GitHub, car cela a été l'étincelle initiale qui a conduit au développement de ce projet et dont le code de ThePhish s'est inspiré.

Les URLs et IDs définis dans ce fichier doivent être les mêmes que ceux définis dans le fichier de configuration de TheHive nommé application.conf, qui contient une partie relative à Cortex et une partie relative à MISP. Les paramètres à rechercher sont name et url dans les deux parties, qui correspondent aux IDs et URLs des instances Cortex et MISP. Les IDs peuvent également être trouvés dans la fenêtre À propos sur l'interface web de TheHive. Un exemple où l'ID Cortex est la chaîne local et l'ID MISP est la chaîne MISP THP est montré dans la figure suivante :

Le fichier application.conf est utilisé pour intégrer TheHive avec Cortex et MISP. Vous pouvez apprendre comment configurer l'intégration avec Cortex ici (documentation ThePhish, recommandée) ou ici (documentation TheHive), tandis que pour l'intégration avec MISP vous pouvez aller ici (documentation ThePhish, recommandée) ou ici (documentation TheHive).Les URL auxquelles les instances de TheHive, Cortex et MISP sont accessibles doivent également être remplacées dans le fichier templates/index.html pour que les boutons de l'interface web puissent les atteindre. Pour ce faire, remplacez les trois derniers href de cette portion de code :