DTLcompare

DTLcompare compares two DTLknowsWhy remote diagnostic snapshots: one collected from a computer where access works, and one collected from a computer where the same access fails.

It produces a ranked diagnostic analysis that highlights confirmed differences, eliminated causes, likely causes, evidence, and suggested remediation steps. Reports can be generated as JSON, plain text, and HTML.

Important prerequisite: DTLknowsWhy

DTLcompare is not a standalone diagnostic collector. It is an analysis companion for DTLknowsWhy.

Before using this tool, you must have:

• DTLknowsWhy available in your Python environment.
• The DTLknowsWhy expert package importable, because comparative_analysis.py imports expert.compare.
• Two JSON snapshots generated by DTLknowsWhy remote diagnostics.

If Python cannot import expert.compare, DTLcompare will fail at startup. Run the tool from an environment where DTLknowsWhy is installed or where its source directory is included in PYTHONPATH.

What It Does

The script compares remote diagnostic data from two machines and tries to explain why access succeeds from one side but fails from the other.

It currently focuses on SMB/remote access diagnostics, including:

• Target mismatch detection.
• Ping reachability checks.
• TCP 445 availability checks.
• SMB share visibility differences.
• Authentication failure markers.
• Domain, workgroup, or Entra/Azure AD join differences.
• Applied filter differences.
• Probable causes with evidence and remediation guidance.

The expected input model is:

• working_snapshot: a DTLknowsWhy snapshot where the remote access test succeeds.
• failing_snapshot: a DTLknowsWhy snapshot where the equivalent test fails.

Usage

python comparative_analysis.py <working_snapshot.json> <failing_snapshot.json>

Example:

python comparative_analysis.py 172.17.7.19_snapshot_20260610_151730.json 172.17.7.19_snapshot_20260610_152617.json

By default, the script writes three report files in the current directory:

• <prefix>.json
• <prefix>.txt
• <prefix>.html

It also prints a human-readable summary to the console.

Options

--lang {fr,en}        Analysis language flag. Defaults to fr.
--json                Also print the findings as formatted JSON.
--output-prefix PATH  Output path prefix for generated report files.
--no-files            Do not write JSON, TXT, or HTML report files.

Examples:

python comparative_analysis.py ok.json ko.json --output-prefix reports/compare_ok_vs_ko

python comparative_analysis.py ok.json ko.json --json --no-files

Outputs

Each finding contains structured diagnostic information such as:

• case: stable diagnostic case identifier.
• title: short explanation of the finding.
• level: severity or information level.
• status: whether the cause is active, eliminated, or still a hypothesis.
• confidence: confidence level.
• relevance_score: ranking score used to sort findings.
• evidence: facts extracted from the snapshots.
• cause: explanation of what the evidence means.
• remediation: optional next action.

The HTML report is intended for sharing with support or infrastructure teams. The JSON report is better suited for automation or further processing.

Development Notes

The main entry point is comparative_analysis.py.

The script expects DTLknowsWhy snapshot structures and uses helper functions from:

from expert.compare import detect_join_type
from expert.compare import get_filter_names
from expert.compare import get_path
from expert.compare import share_names

Keep DTLknowsWhy and DTLcompare aligned when the snapshot schema evolves.

Update - 14 June 2026

comparative_analysis.py is now a full DTLknowsWhy snapshot comparison analyzer.

Important points confirmed from the code:

• The analysis compares one snapshot where access works with one snapshot where the same access fails.
• Findings are ranked by score, severity level, status, evidence, likely cause, and remediation.
• The report includes a human-readable conclusion, likely causes, eliminated causes, and verification steps.
• JSON, TXT, and HTML reports are generated by default, unless --no-files is used.
• --output-prefix selects the generated report filename prefix.
• --lang fr|en keeps the analysis layer bilingual.
• An example HTML report is present in the repository to validate the rendering.