I built a network simulator that deliberately breaks virtual networks so my diagnostic tool can figure out what went wrong

I’ve been building an open source project called Network Doctor, a terminal-based network diagnostic tool written in Go.

Recently I ended up building something alongside it that I’m especially proud of: a network simulator designed to test Network Doctor by creating reproducible broken networks.

The simulator can build isolated virtual network environments and then deliberately introduce failures such as:

• packet loss and unstable connectivity
• DNS outages
• incorrect routes
• multi-segment routed networks
• IPv4 and IPv6 failures
• SOCKS5 and SOCKS5h proxy behavior
• TLS problems like expired certificates and hostname mismatches

What made it really fun was adding deterministic bug hunting.

I can give the simulator a seed, have it mutate a healthy network in different ways, run Network Doctor against every case, and compare what Network Doctor thinks is wrong against the simulator’s ground truth.

If it discovers something suspicious, the exact failure can be reproduced later using the same seed and case number.

And this is no longer just theoretical.

The simulator has already found a real problem in Network Doctor.

I set up a GitHub Actions workflow that runs these hunts automatically and turns reproducible findings into GitHub issues. One of those hunts discovered a genuine problem and automatically created GitHub Issue #14 for it.

I investigated the generated case, fixed the problem, and now Issue #14 is now closed.

That was probably the moment when the simulator went from “this is a cool testing system” to “okay, this is actually finding bugs I might not have noticed otherwise.”

The generated issues include things like:

• the simulator seed
• the exact case number
• what the simulated network was actually doing
• what Network Doctor diagnosed
• a command to reproduce the exact failure

So basically, I built a small laboratory where I can break networks on purpose, let Network Doctor investigate them, and occasionally have the laboratory file a bug report against the doctor.

It’s been one of the most enjoyable parts of building the project.

Network Doctor is open source here:

https://github.com/heymaikol/network-doctor

I’d love to hear what kinds of network failures or topologies you think would be interesting to simulate next.