Preface

This manual describes the command-line interface, the graphical user interface, and the internal module reference for DTLknowsWhy 2.1. It covers every executable entry point, every collector module, every shared support module, the expert rule engine, the comparative analyser, and the snapshot format. For step-by-step operational guidance, refer to the companion DTLknowsWhy User Guide.

DTLknowsWhy answers one practical question: "Why does it work on one machine and not on another?" Rather than listing symptoms, it identifies probable causes and proposes corrective actions. Version 2.1 replaces the legacy ipconfig /all text-parsing approach with a structured PowerShell and CIM data collection engine, making the tool fully language-independent and compatible with any Windows locale.

Intended Audience

This manual is intended for:

• System administrators managing Windows 10 and 11 workstations and small Windows-centric networks
• Network administrators diagnosing SMB, DNS, and connectivity issues
• Developers extending or integrating DTLknowsWhy

Readers are assumed to be comfortable with the Windows command prompt, basic TCP/IP networking, and Python execution. No Python development experience is required for operational use.

Conventions

Related Documents

Chapter 1 — Introduction

1.1 Overview

DTLknowsWhy is a Windows diagnostic and expert analysis tool. Run it on a machine to get an immediate picture of its configuration: OS version, network profile, IP settings, key Windows services, and basic connectivity. Optionally point it at another machine to classify it, test its ports, and retrieve its full remote snapshot.

Every collection run produces three output files: a JSON snapshot (raw data for archiving or later analysis), a plain-text report, and a dark-themed HTML report. Reports are available in French and English.

1.2 What's New in Version 2.1

Language-independent network collection

Previous versions collected network configuration by parsing ipconfig /all text output, which depended on localised Windows labels and worked reliably only on French Windows. Version 2.1 replaces this engine entirely with structured PowerShell and CIM data objects.

Graphical user interface with language selection

Version 2.1 adds a Tkinter GUI (DTLknowsWhy.exe) with a language selection control at startup. The selected language applies to all interface labels, menus, generated reports, and diagnostic messages. French and English are supported. The language selection is independent from the Windows display language.

New collector keys

Two new keys are added to the system section of the snapshot: lm_compatibility_level (integer from the LSA registry key, or null if absent) and bitlocker_status (dict of drive letter to encryption state). These feed new rules in the expert engine.

Expert engine and comparative analyser

The analyze() function now accepts a lang parameter. The comparative analyser (compare.py) is fully internationalised via shared/i18n.py: all finding tags, cause descriptions, and remediation strings are available in French and English via --lang.

1.3 Architecture

The tool is structured in four layers:

• Entry points: agent.py, expert.py, compare.py and the compiled executables
• Collectors: agent/collectors/ — one module per data category, all returning plain Python dicts
• Shared modules: shared/ — serialisation, text and HTML report generation, i18n, command runner, logger
• Expert modules: expert/ — rule engine and comparative analyser

Windows System
      |
      v
Collectors (system, network, tests, services, remote_tests)
      |
      v
Snapshot dict  ──────────────────────────────────┐
      |                                       |
      v                                       v
serializer.py                          rules_engine.py
report.py / html_report.py             compare.py
      |                                       |
      v                                       v
JSON + TXT + HTML files            Diagnostic findings (stdout)

1.4 Requirements

1.5 Installation

No installer is required. Copy the project folder to the target machine and run from the project root. The directory layout is:

DTLknowsWhy/
├── agent.py                   ← main entry point
├── expert.py                  ← expert analysis entry point
├── compare.py                 ← comparative analysis entry point
├── DTLknowsWhy.exe            ← GUI executable (console=False)
├── DTLknowsWhy-CLI.exe        ← CLI executable (console=True)
├── DTLknowsWhy-Agent.exe      ← remote agent executable
├── 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

Chapter 2 — Command Descriptions

This chapter describes each executable entry point: syntax, parameters, options, behaviour, and examples. For module internals, see Chapter 3.

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

# Local snapshot, English report
python agent.py --snapshot --lang en

# Local snapshot + remote agent query
python agent.py --target PC-BEN-002 --lang en

# Start HTTP server
python agent.py --listen

DTLknowsWhy.exe [--target IP_OR_HOST] [--lang {fr,en}]

DTLknowsWhy-CLI.exe [--snapshot] [--target IP_OR_HOST] [--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=en

# Interactive mode
DTLknowsWhy-Agent.exe --listen

# Install and start as Windows service
DTLknowsWhy-Agent.exe install
DTLknowsWhy-Agent.exe start

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

# Analyse latest snapshot, English output
python expert.py --lang en

# Analyse a specific snapshot
python expert.py PC-BEN-002_snapshot_20260607_093442.json --lang en

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

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

Chapter 3 — Module Reference

This chapter describes each Python module: purpose, public functions, parameters, and output keys. For CLI entry points, see Chapter 2.

Collectors

Shared Modules

Expert Modules

Appendices

Appendix A — Snapshot Format

The JSON snapshot produced by export_snapshot() has the following top-level structure in 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 is absent if no --target was specified. remote_agent_snapshot is absent if the agent was unreachable. causal_comparison is always present when target is set.

Appendix B — Target Classification

After remote tests complete, classify_target() in remote_tests.py assigns a target_type string. Rules are applied in order; the first match wins:

Appendix C — Firewall Configuration

DTLknowsWhy-Agent listens on TCP 5050. Create the inbound rule on the target machine from an elevated command prompt:

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

Alternatively, use Windows Defender Firewall → Advanced Settings → Inbound Rules → New Rule → Port → TCP 5050 → Allow.

Appendix D — SmartScreen Warning

On first execution, Windows Defender SmartScreen may display:

Windows protected your PC.
Microsoft Defender SmartScreen prevented an unrecognized app from starting.

This is expected for unsigned executables. To proceed: verify the file originates from the official DTLknowsWhy repository; click More info; click Run anyway. In corporate environments, request digital signing or explicit approval from your security team before wide deployment.

Appendix E — LmCompatibilityLevel

This registry value controls the NTLM authentication negotiation level. A missing key (null in the snapshot) means Windows uses its compiled-in default.

To set the value from an elevated PowerShell prompt:

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

Appendix F — Known Limitations

• Windows only. The tool imports ctypes.windll and calls Windows-specific commands. It will not run on Linux or macOS.
• Single active adapter. Collectors return values from the first matching adapter. On multi-adapter machines, secondary adapters are ignored.
• ARP MAC lookup requires LAN adjacency. The target must be on the same Layer 2 segment or have been recently contacted.
• Remote tests can be slow. Each TCP port probe has a 15-second timeout via PowerShell. Up to 60 seconds total if all four ports time out.
• Server mode writes files on every request. Each GET /snapshot triggers a full collection and writes new JSON, TXT, and HTML files on the agent machine.
• API key in plain text. API_KEY is hardcoded in server.py. No TLS. Trusted networks only.
• BitLocker collection requires elevation. Get-BitLockerVolume requires administrator privileges; the fallback manage-bde also requires elevation. Without admin, bitlocker_status will be null.
• compare.py is directional. Only PC B deviations from PC A are reported. Swap arguments for reverse comparison.
• HTML report logo path is relative. Place netdtl_logo.png in the same directory as the HTML report.
• Log file in current directory. dtlknowswhy.log is written to the invocation directory; logging silently fails if write permission is absent.

Appendix G — Version History