APT-Hunter

Threat hunting for Windows event logs, built with a purple-team mindset.

APT-Hunter est un outil de threat hunting pour les journaux d'événements Windows. Il utilise des règles de détection prédéfinies et des statistiques de journaux pour faire remonter l'activité APT dissimulée dans de grands volumes d'événements, réduisant le temps nécessaire pour découvrir des comportements suspects. Il est particulièrement efficace pour les évaluations de compromission.

Les résultats sont écrits sous forme de chronologie qui peut être analysée directement dans Excel, Timeline Explorer, Timesketch et outils similaires, ou explorée dans le tableau de bord web intégré avec un triage LLM local en option.

• Introducing APT-Hunter
• APT-Hunter v3.0: rebuilt with multiprocessing

Table des matières

• Fonctionnalités
• Installation
• Démarrage rapide
• Options de ligne de commande
• Exemples
• Tableau de bord web
• Analyse LLM locale
• Triage agentique
• Exemples de sortie
• Auteur
• Crédits

Fonctionnalités

• Détection basée sur des règles sur Security, System, Sysmon, PowerShell, Defender, WinRM, Scheduled Tasks, Terminal Services et plus encore ; le type de journal est détecté automatiquement.
• Moteur multiprocessing pour une analyse rapide de grands ensembles de journaux.
• Hunting par chaîne, regex ou fichier de regex, plus prise en charge des règles Sigma.
• Hunting dans les journaux d'audit Office 365.
• Sortie chronologique au format Excel, CSV (compatible Timesketch) et rapports dédiés sur les logons, l'exécution de processus et l'accès aux objets.
• Tableau de bord web avec filtrage, graphiques, chronologie d'incident et export de rapport IR (Markdown / .docx).
• Analyse LLM locale via n'importe quel serveur compatible OpenAI (Ollama, LM Studio, llama.cpp). Rien ne quitte votre machine.
• Triage agentique qui regroupe des milliers d'alertes en une courte liste de constats à examiner.

Installation

Téléchargez les binaires compilés depuis la page Releases, ou exécutez depuis les sources (Python 3.8+) :

git clone https://github.com/ahmedkhlief/APT-Hunter.git
cd APT-Hunter
python3 -m pip install -r requirements.txt

Démarrage rapide

python3 APT-Hunter.py -p /opt/wineventlogs/ -o Project1 -allreport

-p accepte un répertoire ou un fichier unique. Ajoutez -web pour ouvrir le tableau de bord à la fin de l'analyse.

Options de ligne de commande

Exécutez python3 APT-Hunter.py -h pour la liste complète. Options principales :

Exemples

Analyser un dossier de fichiers EVTX (les types de journaux sont détectés automatiquement) :

python3 APT-Hunter.py -p /opt/wineventlogs/ -o Project1 -allreport

Se concentrer sur une plage temporelle :

python3 APT-Hunter.py -p /opt/wineventlogs/ -o Project1 -allreport -start 2022-04-03 -end 2022-04-05T20:56

Hunting avec une chaîne, une regex, ou un fichier de regex :

python3 APT-Hunter.py -hunt "psexec" -p /opt/wineventlogs/ -o Project2
python3 APT-Hunter.py -huntfile "(psexec|psexesvc)" -p /opt/wineventlogs/ -o Project2
python3 APT-Hunter.py -huntfile huntfile.txt -p /opt/wineventlogs/ -o Project2

Hunting avec des règles Sigma :

python3 APT-Hunter.py -sigma -rules rules.json -p /opt/wineventlogs/ -o Project2

Récupérer les dernières règles Sigma converties pour APT-Hunter (écrit rules.json) :

./Get_Latest_Sigma_Rules.sh

Tableau de bord web

Parcourez un rapport généré dans le navigateur : filtrage, graphiques, chronologie d'incident et export de rapport IR.

python3 run_webapp.py <Output>/<Output>_Report.xlsx     # or pass the output directory
python3 APT-Hunter.py -p <logs> -o <Output> -web         # analyse, then open the dashboard
python3 APT-Hunter.py -webview <Output>                  # open an existing report

Accepter un constat de triage l'épingle à la chronologie d'incident avec ses preuves, attachées comme sous-événements repliables : ils se trouvent sous le constat dans le tableau plutôt qu'entremêlés avec tout le reste, et ils sont exclus des graphiques de chronologie afin que les graphiques restent lisibles. Supprimer un constat supprime ses sous-événements avec lui.

Le serveur écoute par défaut sur 0.0.0.0:5000. Utilisez --host / --port (ou -webhost / -webport) pour modifier cela, par exemple --host 127.0.0.1 pour le garder en local. Les constats examinés et la chronologie sont conservés lorsque le cache du rapport est reconstruit.

Tableau de bord principal : total des événements et décomptes par sévérité, répartition par sévérité, principales règles de détection déclenchées, et volume d'événements quotidien. La barre latérale liste chaque journal d'événements et tableau récapitulatif du rapport.

Chronologie d'incident : constats épinglés représentés par heure et codés par couleur selon la sévérité. Zoomez et déplacez-vous dans les périodes chargées, générez un résumé exécutif par IA, et exportez le rapport IR ou le CSV.

Chronologie chronologique : une chaîne d'attaque se déploie en ses sous-événements, et le panneau de détails affiche le récit, les techniques MITRE et le score.

Le graphique de chronologie d'incident est zoomable, de sorte que les rafales d'événements séparés de quelques minutes ou secondes restent lisibles : faites glisser sur le graphique pour zoomer sur une période, Shift+glisser pour vous déplacer, Ctrl/Cmd+molette pour zoomer autour du curseur, ou utilisez la bande de vue d'ensemble en dessous. Les étiquettes ne se chevauchent jamais ; celles qui ne tiennent pas sont masquées, et survoler un point liste chaque événement empilé dessus.

Analyse LLM locale

Notez les événements détectés selon leur caractère malveillant à l'aide d'un modèle local, depuis la ligne de commande :

python3 APT-Hunter.py -p <logs> -o <Output> -llm -llm-provider ollama -llm-model llama3 -llm-severity High

Ou par événement depuis le tableau de bord (vérifier, expliquer, corréler). Configurez le fournisseur (Ollama / LM Studio / llama.cpp), le modèle, l'URL et le délai d'attente sur la page Settings du tableau de bord. N'importe quel serveur local compatible OpenAI fonctionne ; aucune donnée n'est envoyée à un service cloud.

Triage agentique

Agentic Triage dans la barre latérale du tableau de bord transforme des milliers d'alertes en une courte liste de constats :

1. Regroupement. Les alertes dans la portée choisie (sévérité minimale, ordinateurs, fenêtre temporelle) sont regroupées par règle, hôte, Event ID et forme du message. Un rapport d'environ 13,5 k alertes se réduit généralement à quelques dizaines de groupes.
2. Verdict de première passe. Le LLM juge chaque groupe exactement une fois. Cette passe est peu coûteuse et exhaustive, ce qui garantit que rien n'est ignoré.
3. Investigation. Un agent traite les pistes restantes avec des outils : il recherche des alertes, lit le journal d'événements brut derrière une alerte, parcourt la chronologie autour d'un instant, et relie ce qu'il trouve en chaînes d'attaque. Il peut seulement proposer des constats ; il n'écrit jamais lui-même dans la chronologie.
4. Examen. Les constats apparaissent dans une file avec score, verdict, technique MITRE, preuves et la trace d'investigation de l'agent. Accept ajoute un constat à la chronologie d'incident (et à l'export du rapport IR / .docx) ; Reject le rejette. Définissez un seuil d'ajout automatique dans Settings (ou par exécution) pour accepter automatiquement les constats à score élevé.

La phase d'investigation nécessite un LLM qui prend en charge l'appel d'outils. Si le vôtre ne le fait pas, APT-Hunter revient à un pipeline fixe de pivot/corrélation. La couverture est identique dans les deux cas, puisque l'agent n'ajoute que de la profondeur par-dessus la première passe. Les tours d'outils et une limite de temps réel sont plafonnés dans Settings.

Triage agentique : l'historique des exécutions montre la portée, les décomptes d'alertes et de groupes, les constats et les appels LLM par exécution. Ici, 91 alertes critiques sur un hôte se sont réduites à 32 groupes et une seule chaîne d'attaque à score élevé.

Détail d'un constat : le récit, les techniques MITRE, les preuves et la trace d'investigation complète (chaque événement lu, fenêtre de chronologie et recherche d'alerte effectués par l'agent), afin que chaque conclusion puisse être auditée.

Note : La sortie du LLM est une aide au triage, pas un verdict. Examinez les constats avant de vous y fier. Les modèles de raisonnement peuvent nécessiter de relever le délai d'attente des requêtes bien au-dessus de la valeur par défaut de 200 s.

Exemples de sortie

Auteur

Twitter : @ahmed_khlief · LinkedIn : Ahmed Khlief

Licence

Distribué sous GNU GPL v3. Voir LICENSE.

Crédits

Merci à Joe Maccry pour son incroyable contribution aux cas d'usage Sysmon ( plus de 100 cas d'usage ajoutés par Joe )