Skip to content

Home

Jump to bottom
heymaikol edited this page Aug 18, 2026 · 3 revisions

Network Doctor Wiki

Network Doctor answers one question about a broken connection: is the problem on my network, along the path, or at the service?

It does that by running independent, unprivileged, time-bounded probes (interface, DNS, TCP, TLS, HTTP, proxy, QUIC, encrypted DNS, path MTU) and turning the results into a plain-English diagnosis instead of a wall of ping, dig, and curl output.

This wiki is the explanatory half of the documentation. It teaches concepts, walks through workflows, and explains why things are built the way they are. It does not restate flags, defaults, exit codes, or inventories, since those live beside the code, where they change in the same commit as the behaviour. See Documentation Map for what lives where and why.

Two commands, two jobs

The project is network-doctor. It ships two binaries, and confusing them is the most common early stumble.

netdoc netdoc-sim
What it is The diagnostic tool A network simulator that grades netdoc
Who runs it Anyone with a broken connection Contributors, and anyone playing Challenge Mode
What it touches Your real network, read-only probes A throwaway virtual network; never your real one
Platforms Linux, macOS, Windows Linux only (natively), or any host via a Linux container
Needs root? No No

If you are here because something is broken, you want netdoc and nothing else on this page. Start at Getting Started.

netdoc-sim exists because a diagnostic tool needs to be tested against faults whose truth is known by construction. Challenge Mode is that same machinery with a person added as the second contestant.

Start here

I have a network problem

  1. Getting Started: install, first run, what the screen is showing you.
  2. Understanding Your Diagnosis: you have a verdict; what does it mean and what do you do next.
  3. How Network Doctor Works: why the probes are arranged the way they are, and why one failure never hides another.
  4. Troubleshooting and FAQ: rows that behave surprisingly, and the questions that come up most.

I want to play with the simulator

  1. Challenge Mode: diagnose a hidden fault yourself, then let Network Doctor try the same one. One container command on any OS.
  2. Simulator Overview: what netdoc-sim builds, how a run is structured, and what a scenario is.
  3. Hunts and Triage: automated fault generation, what a "false negative" actually means here, and the nightly pipeline.

I want to contribute

  1. Architecture: package boundaries, the probes → evidence → diagnosis flow, and the simulator pipeline.
  2. Development and Contributing: clone, build, the validation gate, and what a good pull request looks like.
  3. Documentation Map: where to put documentation so it does not drift.

Authoritative references in the repository

These are the sources of truth. When this wiki and one of these disagree, the repository is right and the wiki has a bug worth reporting.

Source Authoritative for
netdoc --help / netdoc.1 netdoc flags, syntax, defaults, target grammar
netdoc-sim help / netdoc-sim.1 netdoc-sim commands, flags, exit codes
README Install per platform, probe table, JSON schema, exit codes, validation gate
docs/simulation.md The complete simulator guide: setup, scenarios, campaigns, hunts, triage, the challenge contract
CONTRIBUTING.md Package layout rules, validation requirements, PR expectations
netdoc-sim scenarios / starters / authored The current inventories, never a hand-written list
SECURITY.md Reporting a vulnerability

Project links

This wiki is the explanatory half of Network Doctor's documentation. Exact flags, defaults, exit codes, and inventories are authoritative in the repository and in each command's own --help; see Documentation Map. Where the two disagree, the repository is right.

Network Doctor

Using netdoc

Using netdoc-sim

Contributing

Authoritative docs

Clone this wiki locally