heymaikol/network-doctor runs your whole network runbook in one pass

The difference between a network problem that takes five minutes to diagnose and one that takes an hour is usually whether you remember to check DNS, MTU, and the proxy in the same pass. Most engineers forget at least one. Network Doctor is a small Go program that remembers all of them for you and prints a verdict you can actually paste into Slack.

The tool lives at github.com/heymaikol/network-doctor and runs as a terminal app. You point it at a host, it walks the path from your network interface out to the destination, and it reports a status for every layer: interface, connectivity, DNS, TCP, TLS, HTTP, proxy, and path MTU (the largest packet size that can travel end-to-end without fragmentation). The output is plain English with a pass, warning, failure, skipped, or not-applicable verdict per check, plus the supporting evidence so you can decide whether to trust the verdict or dig deeper.

What it actually checks

Most network debugging tools answer one question well. ping tells you about reachability. dig tells you about DNS. mtr tells you about the path. curl tells you about HTTP. Network Doctor’s claim is that it answers all of these in one run, in the right order, and binds the answers to a single interface if you ask.

The check list is what you would write if you were building a runbook for a new on-call engineer:

• Local network interfaces and whether they are actually up.
• Internet connectivity from the host, not from somewhere on the cloud.
• DNS resolution, including which resolver answered and how fast.
• TCP handshake to the destination port.
• TLS handshake, with certificate chain and expiry.
• HTTP and HTTPS response codes and headers.
• The proxy the environment has configured, and whether traffic flows through it.
• Path MTU, without needing root to set the DF (don’t fragment) bit.
• LAN scanning and network mapping when you want to see what is on the local subnet.

Each check has its own status line, and the program runs them concurrently so a slow DNS lookup does not gate the rest of the report.

Why a wrapper is the point

You can do all of this with a shell script that calls ping, dig, curl, and mtr in sequence. The reason to use Network Doctor instead is the framing. The tool labels each check with a status you can grep, and the JSON output mode lets you feed the same report into a status page or an alert rule.

A few things make it worth installing alongside your usual mtr habit:

• It binds traffic to a specific interface or IP address, which matters when you are debugging a multi-homed host and want to know which path a packet actually took.
• The watch mode re-runs the checks on an interval, which is the right shape for catching an intermittent TLS handshake failure or a flaky proxy.
• The structured JSON output means you can drop it into a cron job and diff today’s report against yesterday’s.
• It integrates with ping, dig, curl, traceroute, mtr, and nmap rather than reinventing them, so when a check fails it can hand you the right next command to run.
• It runs on Linux, macOS, and Windows from the same binary, so the runbook is portable across the team.

Where it falls short

A tool that prints a verdict is only as good as the verdict. A few honest limits.

Network Doctor reports what it can observe from the host it runs on. If the actual fault is upstream of your provider, the tool will report a failure and a route, but it cannot tell you whose network is dropping the packet. The MTU check is a heuristic, not a guarantee, and it can flag a problem that turns out to be a normal link with a lower-than-default MTU. The LAN scanning mode assumes you have permission to probe the local subnet, which is not always true on shared office networks.

The bigger trade-off is that any automated diagnostic tool can produce false confidence. A pass on every check does not prove the application works; it proves the layers below the application work. When the bug is in the app, the tool will look clean and that is the moment to reach for the actual logs.

There is also a tradeoff in how the tool integrates with what is already on the box. Network Doctor shells out to ping, dig, curl, traceroute, mtr, and nmap, which means a clean install requires those binaries to be present. On a stripped-down container image or a minimal Alpine-based VM, you may need to add them by hand before the report is complete. The tool does not bundle them because the maintainers chose to lean on the standard utilities rather than reimplement them in Go. That choice keeps the binary small and the code easy to audit, but it does mean the report is only as good as the underlying tools on the host.

Finally, the structured JSON output is the right shape for an alerting pipeline, but it is not a substitute for proper instrumentation on the services you actually run. Treat the JSON as a quick “is the network up” signal you can wire into a status page or a CI smoke test, not as the primary source of truth for production health. The same way you would not replace Prometheus with a one-shot script, you should not replace your real observability with a snapshot from Network Doctor.

When to reach for it

Reach for Network Doctor when the failure mode is “the network” and you do not yet know which layer. Skip it when you already know the answer and just need to confirm one specific check, because a single curl -v is faster than launching the full tool. And if you are writing a runbook for a new on-call engineer, install it on their laptop on day one and tell them to run it first.

The source is at github.com/heymaikol/network-doctor under the GPL v3.

A few practical recipes from real on-call shifts

The tool gets more useful the more you use it. A handful of patterns that pay off on a real rotation:

• Run it against the API you are debugging, then run it against a known-good control like example.com. If both fail the same check, the fault is upstream of you; if only the target fails, the fault is between you and them.
• Bind it to the specific interface or IP address of a multi-homed host when you suspect a routing table is sending traffic out the wrong NIC. The MTU check is the one that catches asymmetric path issues fastest because the wrong interface usually has a different MTU.
• Use the watch mode when a customer reports an “intermittent” failure. A 30-second watch loop with a one-second DNS TTL will catch the exact minute a resolver starts failing, which is usually the answer.
• Pipe the JSON output into a diff against yesterday’s run when the team wakes up to “things are slow” and nobody can point at a cause. The diff between two healthy runs is small; the diff after a deploy or a config push is usually obvious.
• Pair it with mtr rather than replacing mtr. Network Doctor tells you which layer is broken; mtr tells you where along the path it is broken. They answer different questions and complement each other.

The honest summary: install it once, run it before you reach for curl -v, and let the verdict tell you which layer to investigate next.