Analyse de logiciels malveillants axée sur les preuves avec inspection approfondie des PE/.NET, reconstruction Ghidra, vérifications croisées par IA, YARA et débogage ELF.
AIDebug est une interface en ligne de commande et une interface terminale de rétro-ingénierie de logiciels malveillants axée sur les preuves. Elle combine un triage hors ligne déterministe, une inspection hexadécimale complète du fichier, une analyse approfondie de la structure PE, un désassemblage Capstone, une reconstruction Ghidra, des vérifications croisées LLM optionnelles, un débogage ELF local, des exercices d'apprentissage compilés et des rapports destinés à l'examen par un analyste.
Version source actuelle : AIDebug 3.1.0. Voir les notes de version 3.1.0.
La dernière version publiée immuable reste AIDebug v3.0.0, disponible sous le nom
1200km-aidebug, jusqu'à ce que le tag 3.1.0 assorti à la version et la publication GitHub complètent le flux de publication vérifié.
Installez le paquet stable depuis PyPI :
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install 1200km-aidebug==3.0.0
aidebug --version
Installez les capacités optionnelles selon vos besoins :
# Fournisseurs LLM distants/locaux et génération YARA validée
python -m pip install "1200km-aidebug[ai]==3.0.0"
# Instrumentation dynamique Frida
python -m pip install "1200km-aidebug[dynamic]==3.0.0"
# Toutes les intégrations Python optionnelles
python -m pip install "1200km-aidebug[all]==3.0.0"
Pour le développement :
git clone https://github.com/anpa1200/AIDebug.git
cd AIDebug
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev,dynamic]"
Ghidra, GDB, Bubblewrap, un compilateur C et les composants cibles Frida sont des outils externes utilisés uniquement par les flux de travail qui les requièrent.
Ouvrez un échantillon PE ou ELF dans l'interface terminale principale :
aidebug --binary /path/to/sample.exe --offline
Exécutez une analyse déterministe sans l'interface plein écran et exportez les preuves :
aidebug --binary /path/to/sample.exe \
--offline --no-tui --report --json-export --yara \
--out-dir reports/
Utilisez la reconstruction Ghidra :
aidebug --binary /path/to/sample.exe --offline --no-tui --decompile
aidebug --binary /path/to/sample.exe --offline --no-tui \
--decompile-all reports/sample-reconstruction.c
Analysez une unité de traduction C via un artefact ELF temporaire non exécuté :
aidebug --source /path/to/example.c --offline --no-tui
Identifiez un fichier arbitraire indépendamment de son extension de nom :
aidebug --identify /path/to/renamed-or-unknown-file --offline
--identify rapporte un JSON structuré avec le type déclaré, le type MIME, les extensions courantes, la confiance, la méthode, les preuves, le SHA-256 et la taille. La couverture déterministe inclut les formats exécutables et bytecode courants, les archives et images disque, les conteneurs Office/OpenDocument/EPUB, les documents, les images, l'audio/vidéo, les captures de paquets, les bases de données, les artefacts de registre/journaux d'événements, les scripts et le texte. Les formats basés sur ZIP sont inspectés par des noms de membres bornés et de petites lectures de métadonnées ; les fichiers ne sont jamais exécutés ni extraits.
Installez python-magic ainsi que la base de données libmagic du système d'exploitation pour des signatures supplémentaires connues de la plateforme locale :
python -m pip install python-magic
Lorsqu'aucune signature déterministe, structure ou règle de texte ne correspond, un fournisseur d'IA configuré peut inférer un candidat à partir de métadonnées bornées : l'extension, la taille, le SHA-256, jusqu'à 96 octets d'en-tête, 32 octets de fin, l'entropie de l'échantillon et le ratio NUL. Le corps du fichier, les chaînes extraites et le chemin du système de fichiers ne sont pas envoyés. Les résultats exclusivement issus de l'IA sont étiquetés ai-inference, plafonnés à 60 % de confiance et nécessitent une validation par l'analyste. Utilisez --offline pour désactiver complètement le repli ; un type non résolu est rapporté comme Unknown avec le statut de sortie 2.
Appuyez sur S dans l'interface terminale principale, ou démarrez directement dans l'espace de travail :
aidebug --binary /path/to/sample.exe --offline --strings
L'espace de travail préserve les décalages de fichier, les adresses mappées lorsqu'elles sont disponibles, l'encodage, les longueurs en octets et en caractères, les informations de doublons d'occurrences, le contexte de section, la confiance, le score de triage et les raisons déterministes de chaque classification. Les filtres couvrent la longueur minimale, l'encodage, la catégorie et la recherche en texte libre ; le tri des colonnes et la pagination rendent les inventaires volumineux utilisables. Chaque encodage sélectionné analyse l'artefact complet borné en taille. L'inventaire conservé est plafonné à 25 000 enregistrements et 4 096 caractères affichés par valeur ; les comptes exacts de candidats/omissions et la couverture complète en octets rendent chaque plafond visible. Chaque enregistrement conserve au plus 32 annotations DLL/API et 4 096 caractères de description ; les débordements adverses sont rapportés dans les raisons de l'enregistrement.
La détection est multi-étiquettes. Une seule valeur peut simultanément être une DLL, un chemin Windows, une URL, une adresse IP, une clé de registre, une commande, un fragment PowerShell, un pipe nommé, un hash, un candidat d'identifiants, un user agent ou un autre type de preuve pris en charge. Les candidats de domaine sont normalisés IDNA et vérifiés contre un instantané hors ligne embarqué de la zone racine IANA ; les adresses IP doivent occuper un jeton valide complet, et les affectations de configuration doivent correspondre à une grammaire conservatrice de ligne complète. Cela empêche que de courts fragments binaires soient promus simplement parce qu'ils contiennent un point, deux-points ou signe égal. Les étiquettes liées partagent une même famille de confiance, donc ip_address plus ipv6 n'est pas traité comme deux observations indépendantes. Les DLL et API connues reçoivent de courtes descriptions de capacité neutres ; les noms inconnus reçoivent un repli explicite non vérifié au lieu d'un objectif deviné. Un nom extrait est une preuve de présence, pas une preuve que le code l'a invoqué ou que l'échantillon est malveillant.
Imprimez l'inventaire déterministe localement, filtrez la vue CLI affichée ou écrivez l'inventaire complet canonique en JSON réservé au propriétaire :
aidebug --binary /path/to/sample.exe --strings --no-tui
aidebug --binary /path/to/sample.exe --strings --no-tui \
--string-encoding ascii --min-string-length 6 --string-category url
aidebug --binary /path/to/sample.exe --strings --no-tui \
--strings-output reports/sample-strings.json
L'examen des chaînes par IA est une action distincte d'adhésion volontaire. Appuyez sur A dans l'espace de travail et confirmez l'avertissement de confidentialité/coût, ou demandez-le explicitement en mode CLI :
aidebug --binary /path/to/sample.exe --strings --no-tui \
--analyze-strings --accept-ai-cost \
--strings-output reports/sample-strings-ai.json
Chaque chaîne conservée reçoit un identifiant de preuve stable. Après confirmation explicite, le chemin IA planifie chaque enregistrement conservé à travers des blocs déterministes bornés ; les échecs de fournisseur ou de validation s'arrêtent en toute sécurité et restent visibles. Les réponses doivent rendre compte de chaque identifiant fourni et passer une validation locale stricte de schéma, d'énumération, de référence et d'ancrage IOC avant d'être acceptées. Un réducteur final voit les constatations validées plutôt que l'inventaire brut. Les limites d'extraction, les lots échoués et les comptes examinés/envoyés sont toujours rapportés ; une couverture incomplète force une évaluation globale unknown. Les chaînes peuvent contenir des mots de passe, des jetons API, des données client et des injections de prompt rédigées par des attaquants, donc examinez la frontière IA distante avant d'activer cette fonctionnalité.
Inspectez les analyses précédentes par fichier ou par SHA-256 :
aidebug --history /path/to/sample.exe
aidebug --history 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
Chargez un fichier PE et appuyez sur X (ou P) dans l'interface graphique principale. AIDebug présente les octets exacts qu'il a hachés et organise les preuves structurelles dans des vues bornées et navigables.
| Zone | Preuves |
|---|---|
| En-têtes | DOS, NT, COFF, en-tête optionnel, caractéristiques, répertoires de données et indicateurs d'atténuation |
| Sections | Champs complets IMAGE_SECTION_HEADER, plages mappées, entropie et permissions |
| Imports et exports | Descripteurs d'import, entrées INT/IAT, imports différés, ordinaux, noms, RVA et redirecteurs |
| Ressources | Hiérarchie type/nom/langue, métadonnées, hashes, aperçus et export sûr sans écrasement |
| Relocalisations et ASLR | Blocs/entrées de relocalisation et évaluation structurelle de compatibilité ASLR |
| TLS | Répertoire TLS, données de modèle, index, table de callbacks, mappages et preuves de terminaison |
| Exceptions et déroulement | Fonctions runtime x64, UNWIND_INFO, opérations, gestionnaires et enregistrements chaînés |
| Configuration de chargement | Champs versionnés, indicateurs Guard, preuves de cookie de pile et d'atténuation d'exploitation |
| CFG | Pointeurs de vérification/expédition, cibles Guard Function ID, ordre, suppression et vérifications de cohérence |
| Authenticode | Enregistrements de certificats, preuves PKCS#7/X.509, comparaison de digest d'image PE et vérification du signataire |
| Débogage et provenance | En-tête Rich, répertoire de débogage, CodeView RSDS/NB10, GUID PDB, âge et chemin |
| Superpositions | Décalage exact, taille, hash, entropie, aperçu et export sûr |
| .NET / CLR | En-tête COR20, racine et flux de métadonnées, tables ECMA-335, assemblys, références et ressources |
AIDebug n'exécute pas un PE lors de la construction de ces vues. La vérification statique de certificats n'est pas une confiance racine Windows ni une validation de révocation, les métadonnées Rich ne sont pas une attribution, les métadonnées de nom fort ne sont pas une confiance d'éditeur, et les indicateurs d'atténuation statiques ne sont pas une preuve de politique runtime effective.
Ces articles fournissent les flux de travail détaillés et les captures d'écran qui complètent la documentation du dépôt :
Ouvrez le catalogue complet ou commencez par un cas spécifique :
aidebug --learn
aidebug --learn mov-load
aidebug --learn lea-arithmetic
aidebug --learn switch-dispatch
Chaque cas inclus est un fichier autonome sous learning/cases/.
AIDebug compile le cas sélectionné en un ELF x86-64 temporaire, affiche le code C exact et les instructions générées par le compilateur, demande à Ghidra une reconstruction indépendante, enregistre la provenance de construction et supprime l'artefact temporaire.
Le binaire de leçon généré n'est jamais exécuté.
Utilisez --no-tui pour une sortie texte, ou chargez une collection externe examinée :
aidebug --learn movsxd --no-tui
aidebug --learn --learning-collection /path/to/reviewed-cases
L'analyse IA est optionnelle. Le mode hors ligne déterministe reste disponible sans identifiants.
python -m pip install "1200km-aidebug[ai]==3.0.0"
cp .env.example .env
chmod 600 .env
Configurez exactement un fournisseur, ou définissez AIDEBUG_LLM_PROVIDER explicitement lorsque plusieurs identifiants existent :
AIDEBUG_LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=replace_with_your_key
# Alternatives :
# OPENAI_API_KEY=replace_with_your_key
# GEMINI_API_KEY=replace_with_your_key
# OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
Utilisez AIDEBUG_ENV_FILE=/absolute/path/to/private.env pour garder la configuration à l'écart des répertoires d'analyse non fiables. L'analyse groupée distante nécessite l'accusé de réception explicite --accept-ai-cost. Examinez la frontière de données IA distante avant d'envoyer des preuves d'échantillon à un fournisseur.
Le mode actif basé sur GDB exécute l'ELF local sélectionné. Utilisez-le uniquement dans un laboratoire isolé et autorisé :
aidebug --binary ./sample.elf --mode debug --breakpoint main
Les commandes disponibles incluent break, continue, step, next, finish, registers, changes, io, disassemble et quit. Le mode dynamique Frida est disponible séparément pour les flux de travail d'instrumentation locaux ou distants pris en charge.
| Sortie | Utilisation prévue |
|---|---|
| Rapport HTML | Examen humain et notes de cas |
| JSON versionné | Entrée d'intégration personnalisée ; pas un schéma natif fournisseur ni STIX |
| JSON d'intelligence de chaînes | Inventaire canonique de chaînes conservées plus annotations IA validées optionnelles et couverture |
| Candidats YARA | Graines d'ingénierie de détection compilées localement nécessitant examen et tests |
| Candidats ATT&CK | Hypothèses au niveau technique nécessitant validation par l'analyste |
| Visualisation CFG | Examen du flux de contrôle au niveau fonction |
| Historique SQLite | Preuves de session locales et restauration de constatations basée sur SHA-256 |
flowchart LR
Input[PE, ELF, or C source] --> Parse[Bounded parsing and hashing]
Parse --> Structure[Hex and PE structure evidence]
Parse --> Strings[Deterministic string intelligence]
Parse --> Disasm[Capstone disassembly]
Disasm --> Patterns[Deterministic patterns]
Disasm --> Ghidra[Ghidra reconstruction]
Patterns --> Offline[Offline findings]
Patterns --> AI[Optional LLM cross-check]
Strings --> StringAI[Opt-in chunked string AI review]
Ghidra --> AI
Offline --> Reports[HTML, JSON, YARA, CFG]
AI --> Reports
StringAI --> StringJSON[Structured string JSON]
Reports --> History[SHA-256-indexed history]Utilisez AIDebug uniquement sur des logiciels et systèmes que vous êtes autorisé à examiner, dans une VM ou un laboratoire d'analyse de logiciels malveillants isolé.
Lisez le modèle de sécurité complet, la politique de sécurité et le plan de limitations et de validation avant d'analyser des échantillons non fiables.
| Document | Objectif |
|---|---|
| Flux de travail de l'analyste | Processus d'analyse reproductible |
| Modèle de sécurité | Frontières de confiance et fonctionnement sûr |
| Plan de validation | Revendications de capacité testables |
| Preuves d'échantillon | Captures d'écran illustratives et artefacts simulés |
| Comparaison | Portée et positionnement |
| Préparation de version | Portes de version reproductibles |
| Notes de version AIDebug 3.1 | Changements de la version source actuelle |
| Notes de version AIDebug 3.0 | Changements de la version publiée précédente |
| Journal des modifications | Historique des versions |
Exécutez les vérifications locales rapides :
python -m ruff check .
python -m pytest -q
Exécutez la porte de version isolée complète :
./scripts/release-readiness.sh
Voir CONTRIBUTING.md pour les directives de contribution. N'attachez pas de logiciels malveillants vivants, d'identifiants, de données de cas privées ou de preuves non expurgées aux problèmes ou aux demandes de tirage.
AIDebug est publié sous la licence MIT.