DTLknowsWhy — Manuel de référence v2.1

Préface

Ce manuel décrit l'interface en ligne de commande, l'interface graphique et la référence des modules internes de DTLknowsWhy 2.1. Il couvre chaque point d'entrée exécutable, chaque module collecteur, chaque module partagé, le moteur expert de règles, l'analyseur comparatif et le format des snapshots. Pour un guide opérationnel pas à pas, consultez le Guide utilisateur DTLknowsWhy.

DTLknowsWhy répond à une question pratique : « Pourquoi ça fonctionne sur une machine et pas sur une autre ? » Plutôt que de lister des symptômes, il identifie les causes probables et propose des actions correctives. La version 2.1 remplace l'ancienne analyse textuelle d'ipconfig /all par un moteur de collecte basé sur des objets PowerShell et CIM structurés, rendant l'outil entièrement indépendant de la langue et compatible avec toute locale Windows.

Audience visée

Ce manuel s'adresse aux administrateurs systèmes gérant des postes Windows 10 et 11 et des réseaux Windows, aux administrateurs réseau qui diagnostiquent des problèmes SMB, DNS et de connectivité, ainsi qu'aux développeurs qui étendent ou intègrent DTLknowsWhy. Une connaissance de l'invite de commandes Windows et des bases TCP/IP est supposée. Aucune expérience de développement Python n'est requise pour l'utilisation opérationnelle.

Conventions

Documents associés

Chapitre 1 — Introduction

1.1 Vue d'ensemble

DTLknowsWhy est un outil de diagnostic et d'analyse experte pour Windows. Exécutez-le sur une machine pour obtenir immédiatement une image complète de sa configuration : version du système d'exploitation, profil réseau, paramètres IP, services Windows clés et connectivité de base. Pointez-le optionnellement vers une seconde machine pour récupérer son snapshot complet via l'agent intégré, puis comparez les deux configurations pour identifier la cause probable de la différence.

1.2 Nouveautés de la version 2.1

Collecte réseau indépendante de la langue

Les versions précédentes collectaient la configuration réseau en analysant la sortie texte d'ipconfig /all, ce qui dépendait des libellés Windows localisés et ne fonctionnait de manière fiable que sur Windows en français. La version 2.1 remplace entièrement ce moteur par des objets PowerShell et CIM structurés.

Interface graphique avec sélection de langue

La version 2.1 ajoute une interface Tkinter (DTLknowsWhy.exe) avec un sélecteur de langue au démarrage. La langue choisie s'applique à tous les libellés d'interface, menus, rapports générés et messages de diagnostic. Le français et l'anglais sont pris en charge. La sélection de langue est indépendante de la langue d'affichage de Windows.

Nouvelles clés de collecte

Deux nouvelles clés sont ajoutées à la section system du snapshot : lm_compatibility_level (entier issu de la clé de registre LSA, ou null si absente) et bitlocker_status (dictionnaire lettre de lecteur → état de chiffrement). Ces clés alimentent de nouvelles règles dans le moteur expert.

Moteur expert et analyseur comparatif

La fonction analyze() accepte désormais un paramètre lang. L'analyseur comparatif (compare.py) est entièrement internationalisé via shared/i18n.py : tous les tags de résultat, descriptions de causes et chaînes de remédiation sont disponibles en français et en anglais via --lang.

1.3 Architecture

L'outil est structuré en quatre couches :

• Points d'entrée : agent.py, expert.py, compare.py et les exécutables compilés
• Collecteurs : agent/collectors/ — un module par catégorie de données, retournant tous des dicts Python simples
• Modules partagés : shared/ — sérialisation, génération de rapports texte et HTML, i18n, exécuteur de commandes, journal
• Modules experts : expert/ — moteur de règles et analyseur comparatif

Système Windows
      |
      v
Collecteurs (system, network, tests, services, remote_tests)
      |
      v
Dict snapshot  ──────────────────────────────┐
      |                                       |
      v                                       v
serializer.py                          rules_engine.py
report.py / html_report.py             compare.py
      |                                       |
      v                                       v
Fichiers JSON + TXT + HTML        Résultats de diagnostic (stdout)

1.4 Prérequis

1.5 Installation

Aucun installeur n'est nécessaire. Copiez le dossier du projet sur la machine cible et exécutez depuis la racine du projet. La structure de répertoires est :

DTLknowsWhy/
├── agent.py                   ← point d'entrée principal
├── expert.py                  ← point d'entrée analyse expert
├── compare.py                 ← point d'entrée analyse comparative
├── DTLknowsWhy.exe            ← exécutable GUI (console=False)
├── DTLknowsWhy-CLI.exe        ← exécutable CLI (console=True)
├── DTLknowsWhy-Agent.exe      ← exécutable agent distant
├── agent/
│   ├── gui.py
│   ├── server.py
│   ├── service.py
│   └── collectors/
│       ├── system.py
│       ├── network.py
│       ├── tests.py
│       ├── remote_tests.py
│       └── services.py
├── expert/
│   ├── rules_engine.py
│   └── compare.py
└── shared/
    ├── commands.py
    ├── serializer.py
    ├── report.py
    ├── report_writer.py
    ├── html_report.py
    ├── html_writer.py
    ├── i18n.py
    ├── version.py
    └── logger.py

Chapitre 2 — Descriptions des commandes

Ce chapitre décrit chaque point d'entrée exécutable : syntaxe, paramètres, options, comportement et exemples. Pour les modules internes, voir le Chapitre 3.

python agent.py [--snapshot] [--target IP_OU_HÔTE] [--listen] [--once] [--lang {fr,en}]

# Snapshot local, rapport en français (défaut)
python agent.py --snapshot

# Snapshot local + requête agent distant
python agent.py --target PC-BEN-002 --lang fr

# Démarrer le serveur HTTP
python agent.py --listen

DTLknowsWhy.exe [--target IP_OU_HÔTE] [--lang {fr,en}]

DTLknowsWhy-CLI.exe [--snapshot] [--target IP_OU_HÔTE] [--listen] [--lang {fr,en}]

DTLknowsWhy-Agent.exe --listen
DTLknowsWhy-Agent.exe install
DTLknowsWhy-Agent.exe start
DTLknowsWhy-Agent.exe stop
DTLknowsWhy-Agent.exe remove

GET /snapshot?key=DTLSECRET&lang=fr

# Mode interactif
DTLknowsWhy-Agent.exe --listen

# Installation et démarrage comme service Windows
DTLknowsWhy-Agent.exe install
DTLknowsWhy-Agent.exe start

python expert.py [snapshot.json] [--lang {fr,en}]

# Analyser le dernier snapshot, sortie en français
python expert.py --lang fr

# Analyser un snapshot spécifique
python expert.py PC-BEN-002_snapshot_20260607_093442.json --lang fr

python compare.py snapshot_ref.json snapshot_cible.json [--lang {fr,en}]

python compare.py PREDATOR_snapshot_20260607.json PC-BEN-002_snapshot_20260607.json --lang fr

Chapitre 3 — Référence des modules

Ce chapitre décrit chaque module Python : objectif, fonctions publiques, paramètres et clés de sortie. Pour les points d'entrée CLI, voir le Chapitre 2.

Collecteurs

Modules partagés

Modules experts

Annexes

Annexe A — Format du snapshot

Le snapshot JSON produit par export_snapshot() a la structure de niveau supérieur suivante en v2.1 :

{
  "metadata": {
    "generated_at":       "2026-06-07T09:34:42",
    "generated_at_local": "07/06/2026 09:34:42",
    "role":               "local",
    "target":             "PC-BEN-002"
  },
  "system": {
    "hostname":               "PREDATOR",
    "username":               "didier",
    "is_admin":               true,
    "windows_product_name":   "Windows 11 Pro",
    "windows_version":        "23H2",
    "windows_build":          "22631",
    "lm_compatibility_level": null,
    "bitlocker_status":       { "C:": "FullyEncrypted" }
  },
  "network": {
    "active_adapter_profile": "Réseau",
    "network_category":       "Private",
    "ipv4":                   "172.17.7.10",
    "subnet_mask":            "255.255.255.0",
    "default_gateway":        "172.17.7.1",
    "dns_servers":            ["172.17.7.1"],
    "dhcp_enabled":           false,
    "netbios_option":         0,
    "netbios_enabled":        true
  },
  "tests":    { "ping_localhost": true, "ping_self": true, "ping_gateway": true },
  "services": { "LanmanServer": "Running", "LanmanWorkstation": "Running",
                "FDResPub": "Running", "fdPHost": "Running", "lmhosts": "Running" },
  "remote_tests": {
    "target": "172.17.7.3", "resolved_name": "PC-BEN-002",
    "ping_target": true, "tcp_80": false, "tcp_139": true,
    "tcp_443": false, "tcp_445": true,
    "mac_address": "B0:7B:25:7B:C7:58", "target_type": "probable_windows"
  },
  "diagnosis":         [...],
  "causal_comparison": [...],
  "remote_agent_snapshot": { ... }
}

remote_tests est absent si aucun --target n'a été spécifié. remote_agent_snapshot est absent si l'agent était inaccessible. causal_comparison est toujours présent quand target est défini.

Annexe B — Classification de la cible

À la fin des tests distants, classify_target() dans remote_tests.py attribue une chaîne target_type. Les règles sont appliquées dans l'ordre ; la première correspondance l'emporte :

Annexe C — Configuration du pare-feu

DTLknowsWhy-Agent écoute sur TCP 5050. Créer la règle entrante sur la machine cible depuis une invite de commandes élevée :

netsh advfirewall firewall add rule name="DTLknowsWhy Agent" ^
  dir=in action=allow protocol=TCP localport=5050

Alternativement, via Pare-feu Windows Defender → Paramètres avancés → Règles de trafic entrant → Nouvelle règle → Port → TCP 5050 → Autoriser la connexion.

Annexe D — Avertissement SmartScreen

Au premier lancement, Windows Defender SmartScreen peut afficher :

Windows a protégé votre PC.
Microsoft Defender SmartScreen a empêché le démarrage d'une application non reconnue.

Ce comportement est attendu pour les exécutables non signés numériquement. Pour continuer : vérifier que le fichier provient du dépôt officiel DTLknowsWhy ; cliquer sur Informations complémentaires ; cliquer sur Exécuter quand même. En environnement d'entreprise, demander la signature numérique ou l'approbation explicite de l'équipe de sécurité avant tout déploiement étendu.

Annexe E — LmCompatibilityLevel

Cette valeur de registre contrôle le niveau de négociation d'authentification NTLM. Une clé absente (null dans le snapshot) signifie que Windows utilise son défaut compilé.

Pour définir la valeur depuis une invite PowerShell élevée :

Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\Lsa" `
  -Name LmCompatibilityLevel -Value 3 -Type DWord

Annexe F — Limitations connues

• Windows uniquement. L'outil importe ctypes.windll et appelle des commandes spécifiques à Windows. Il ne fonctionnera pas sous Linux ou macOS.
• Adaptateur unique. Les collecteurs retournent les valeurs du premier adaptateur correspondant. Sur les machines multi-adaptateurs, les adaptateurs secondaires sont ignorés.
• La recherche MAC par ARP requiert l'adjacence Layer 2. La cible doit être sur le même segment réseau ou avoir été contactée récemment.
• Les tests distants peuvent être lents. Chaque sondage TCP a un délai de 15 s via PowerShell. Jusqu'à 60 s si les quatre ports expirent.
• Le mode serveur écrit des fichiers à chaque requête. Chaque GET /snapshot déclenche une collecte complète et écrit de nouveaux fichiers JSON, TXT et HTML sur la machine agent.
• La collecte BitLocker requiert les droits administrateur. Sans droits admin, bitlocker_status sera null.
• compare.py est directionnel. Seules les déviations du PC B par rapport au PC A sont signalées. Intervertir les arguments pour la comparaison inverse.
• Le chemin du logo du rapport HTML est relatif. Placer netdtl_logo.png dans le même répertoire que le rapport HTML.
• Fichier journal dans le répertoire courant. dtlknowswhy.log est écrit dans le répertoire d'exécution ; la journalisation échoue silencieusement sans permission d'écriture.

Annexe G — Historique des versions