Network diagnostic suite that separates real transport loss from ICMP noise, identifies the earliest credible affected segment, and generates ISP-ready evidence.
NMPL Pro – Evidence-Backed Packet Loss Diagnostics
Summary
I built NMPL Pro, a network diagnostic utility engineered to eliminate false-positive packet-loss alerts caused by intermediate control-plane rate limiting (CoPP). Rather than making overconfident claims about “finding the broken router,” NMPL evaluates downstream loss persistence to isolate genuine transport degradation, identifies the earliest credible affected network segment, enriches path hops with ASN/organization data, and produces defensible telemetry reports.
It combines an open-source CLI core engine, a FastAPI + HTMX dashboard, and a CLI background daemon for continuous monitoring. The goal is to turn “my connection is flaky” into a classified, reproducible, evidence-backed decision.
Impact / Why It Matters
- Eliminates control-plane alert noise — Evaluates downstream persistence to distinguish isolated intermediate ICMP drops (CoPP artifacts) from actual target-traffic degradation.
- Turns ambiguous symptoms into evidence — Replaces raw MTR dumps with classified verdicts: Real Loss, ICMP Artifact, Local/Access Issue, or Inconclusive.
- Self-hosted and privacy-first — Operates entirely on local hardware with no external cloud telemetry dependencies, fitting directly under discretionary expense limits of $39–$79 lifetime.
- Production-ready engineering — Built with a rate-limited API, async workers, SQLite WAL mode for concurrent operations, and a comprehensive automated test suite.
What I Built
- Rule-based detection engine — ICMP/UDP probes with per-target adaptive baselines (30-probe warm-up window) and downstream persistence verification.
- Downstream persistence analysis — Automated
mtr capture and parsing that checks whether intermediate loss carries through to downstream hops before triggering alerts. - Hop enrichment — Cached, non-blocking ASN/organization lookups via Team Cymru DNS with RDAP fallback, attached to incidents at capture time.
- Incident lifecycle manager — Open/resolve state tracking, automatic resolution on recovery, and background reconciliation of orphaned incidents.
- FastAPI + HTMX dashboard — Live monitoring, searchable incident archive, per-incident hop details, and one-click evidence exports.
- CLI daemon — Threaded multi-target monitoring for headless systems; shares state with the local SQLite database.
- Docker deployment — Containerized stack using
NET_RAW and NET_ADMIN capabilities, with digest-pinned base images.
Results & Evidence
Diagnostic logic
- Evaluates downstream persistence to filter out isolated router ICMP rate-limiting artifacts.
- Establishes adaptive baselines over warm-up windows (~30 probes) to account for naturally lossy or rate-limited endpoints.
- Classifies incidents using deterministic persistence rules (Real Loss, ICMP Artifact, Local/Access Issue, or Inconclusive).
- SQLite in WAL mode handles simultaneous background daemon writes and web UI reads without lock contention.
- An automated
pytest suite covers socket probes, baseline calculations, storage drivers, HTTP rate limiting, async workers, and report generation. - Fully offline-capable: detection, path analysis, and metric storage run locally without third-party API dependencies; enrichment degrades gracefully when offline.
Tech & Methods
| Area | Tools & Techniques |
|---|
| Backend | Python 3.9+, FastAPI, AsyncIO, SQLite (WAL mode) |
| Frontend | HTMX, HTML5, Jinja2 templates, CSS |
| Networking | Raw ICMP/UDP sockets, mtr for path traces, Paris traceroute flow hashing |
| Enrichment | Team Cymru DNS, RDAP fallback, in-process IP cache |
| DevOps | Docker, Docker Compose, Linux capabilities (NET_RAW, NET_ADMIN) |
| Testing | pytest suite covering the end-to-end pipeline from probes to report generation |
Limits & Next Steps
Validated
- End-to-end detection, downstream persistence verification, enrichment, and report generation.
- Dashboard and CLI daemon operational across Linux, macOS, and WSL.
- Incident archive with filtering, hop details, and evidence re-export.
Not yet validated / Non-goals
- No Bayesian fault models: rejected subjective prior modeling in favor of deterministic downstream persistence.
- Large-scale multi-tenant enterprise deployment with heavy concurrent monitoring targets.
- Out-of-the-box integrations with external observability stacks such as Prometheus or Grafana.
Next steps
- Package the core CLI for Homebrew and PyPI distribution.
- Add structured metrics exporters for Prometheus/OpenTelemetry integration.
- Expand enrichment caching strategies for high-churn IP routes.
Usage
Web Dashboard
Open: http://localhost:8000
Docker
1
2
| cd docker
docker compose up -d
|
CLI
1
2
3
4
5
6
7
8
| # Single-target diagnostic trace
python3 -m core 8.8.8.8 --mtr
# Multi-target daemon
python3 cli.py --targets "1.1.1.1,8.8.8.8" --interval 3.0
# Generate exportable ISP evidence report
python3 cli.py --report 1 --export json
|
Links