Network diagnostics for Windows environments

Windows MTR is a Windows-focused network diagnostics CLI inspired by Linux mtr. On Windows, the default interactive UI plus IPv4 ICMP report, JSON, CSV, and dashboard probes use the system ICMP Helper API; TCP and UDP probes continue to use embedded Trippy. The experimental dashboard provides Overview, Hops, and Charts views with explicit loading and poll-error states; it is not a stable replacement for the embedded interactive TUI.

• 🌟 Features
• 📊 Performance
• 🔐 Security
• 💻 Installation
• 🚀 Quick Start
• 📈 Advanced Features
• 📋 Documentation
• 📊 Project Status & Roadmap
• 🤝 Contributing
• 📜 License
• 🙏 Acknowledgements

Windows MTR prioritizes predictable diagnostics and operational safety over unverified headline metrics. Performance and coverage claims should be treated as release-specific and validated from CI artifacts/benchmarks for each tagged release.

• Probe throughput depends on protocol, host kernel/network stack, and runtime flags
• Test coverage trends are tracked in CI and may vary by release
• Timing precision depends on OS scheduler behavior and system load
• Distribution size varies by release artifact composition and compression strategy

Windows MTR is built with enterprise-level security practices:

• 🛡️ Regular security audits with automated scanning
• 🔒 All dependencies vetted for vulnerabilities
• 🧪 Fuzz harness implemented with CI regression gating
• 🔑 SHA-256 checksum verification for canonical release ZIP artifacts

For REST API mode (mtr --api), the enforced security baseline is:

• Default bind address: 127.0.0.1:3000 (localhost only, enforced)
• Non-local bind requires explicit auth strategy (--api-auth api-key|mtls) and secure key handling (--api-key-env preferred for api-key)
• Default request timeout: 10s
• Max concurrent probes: 8
• Max requests per rate-limit window: 8
• Rate-limit window duration: 10s
• Max targets per request: 8
• Max payload size: 16 KiB
• Max retained completed jobs: 1024
• Completed job TTL: 15m

See docs/security/rest-api.md for the full threat model and controls.

1. Download windows-mtr-x86_64.zip from GitHub Releases.
2. Extract it; the ZIP contains mtr.exe, windows-mtr.exe, README.txt, and SHA256SUM.
3. Run PowerShell or CMD as Administrator.
4. Start with .\mtr.exe 8.8.8.8 (or .\windows-mtr.exe -r -c 10 8.8.8.8).

• Windows 7/Server 2012 R2 or later
• 50MB disk space
• Administrator privileges required for network operations

# Pull a release-tagged Windows MTR container (GHCR)
docker pull ghcr.io/benjisho/windows-mtr:v1.2.6

# Pull a release-tagged Windows MTR container (Docker Hub)
docker pull benjisho/windows-mtr:v1.2.6

# Run with direct networking (pin to a specific release tag)
docker run --network host ghcr.io/benjisho/windows-mtr:v1.2.6 -c 5 -r 8.8.8.8

Container images are published from the Release workflow to both GHCR (ghcr.io/benjisho/windows-mtr) and Docker Hub (benjisho/windows-mtr) from explicit release tags like v1.2.3 for linux/amd64 and linux/arm64.

Follow these steps to compile the Windows MTR executable:

1. Install Rust with rustup (Rust 1.88.0+ required).

2. Install Visual Studio Build Tools and select the Desktop development with C++ workload.

3. Clone this repository and change into the project directory:

   git clone https://github.com/benjisho/windows-mtr.git
   cd windows-mtr

4. (Optional) Generate a lockfile if you need to build offline:

   cargo generate-lockfile

5. Compile in release mode:

   cargo build --release

6. After a successful build the binary is located at target\release\mtr.exe.

The resulting executable is now self-contained and embeds Trippy directly (no additional runtime executable required).

Windows MTR requires administrator privileges to run properly, as it needs to send and receive network packets at a low level:

1. Right-click on Command Prompt or PowerShell and select "Run as administrator"
2. Navigate to your Windows MTR directory or add it to your PATH
3. Run your MTR commands with elevated privileges

mtr 8.8.8.8

mtr --ui dashboard 8.8.8.8

--ui enhanced is currently unavailable with bundled Trippy 0.13.0. Use default mode (mtr 8.8.8.8) for the full embedded Trippy TUI.

mtr -n -r -c 20 1.1.1.1

If interactive TUI crashes (for example Windows status 0xC0000005), try:

.\mtr.exe --ui dashboard 8.8.8.8

For stable non-interactive diagnostics:

.\mtr.exe -n -r -c 5 8.8.8.8

mtr -c 10 -r 8.8.8.8 > network-report.txt

mtr --json -c 20 8.8.8.8 > network-report.json

JSON output includes a top-level schema_version field (current: "1.0"). This value is bumped when the CLI JSON schema changes.

mtr --csv network-report.csv -c 20 8.8.8.8

mtr -T -P 443 example.com

# Start API server on localhost (default 127.0.0.1:3000)
mtr --api

# Start API server on a specific localhost bind
mtr --api --api-bind 127.0.0.1:4000

# Secure remote bind with API key from environment (preferred)
WINDOWS_MTR_API_KEY='replace-me' mtr --api --api-bind 0.0.0.0:4000 --api-auth api-key --api-key-env WINDOWS_MTR_API_KEY

# Tune REST API rate limiting (defaults: 8 requests per 10-second window)
mtr --api --api-max-requests-per-window 20 --api-rate-limit-window-seconds 30

# Secure remote bind with mTLS identity forwarding
mtr --api --api-bind 0.0.0.0:4000 --api-auth mtls

Visit our detailed usage guide for comprehensive examples.

mtr -c 50 -i 0.2 destination

mtr -c 100 -r destination

mtr -T -P 80 webserver.example.com

mtr -T -P 443 webserver.example.com

mtr -T -P 25 mailserver.example.com

mtr -c 10 -r --json 8.8.8.8 > metrics.json

$action = New-ScheduledTaskAction -Execute "C:\Tools\windows-mtr\mtr.exe" -Argument "-c 10 -r 8.8.8.8"
$trigger = New-ScheduledTaskTrigger -Daily -At 8am
Register-ScheduledTask -Action $action -Trigger $trigger -TaskName "Daily Network Test" -Description "Runs MTR test each morning"

mtr --json -c 10 8.8.8.8 | curl -X POST -d @- https://logging.example.com/api/v1/logs

Capability claims are validated against source code, tests, CI, documentation, and release artifact flow in docs/capability-validation.md.

• 📚 Full Documentation Hub
• 🛣️ Product Roadmap
• 📦 Distribution Plan
• ✅ Capability Validation Matrix
• 🧩 CLI/API Reference
• 🧪 Probe parity matrix
• 📑 Usage Examples
• 🛠️ Development Setup
• 🤝 Contributing Guide
• 🔄 Changelog

The full roadmap now lives in docs/ROADMAP.md, which is the single source of truth for feature status and planned milestones.

Quick snapshot:

• ✅ Released: Core MTR functionality, IPv6, Docker, JSON output, DNS cache TTL, REST API v1 (authentication, rate limiting, concurrency controls).
• 🚧 In progress: experimental dashboard fallback UI (--ui dashboard, --ui native alias).
• ✅ Released: versioned JSON schema, CSV export, release-artifact smoke validation, and weekly extended fuzz regression.
• 📅 Planned / 🛣️ Roadmap: SNMP integration, ETW observability, native TLS termination (if adopted), and runtime cleanup.

We welcome contributions from the community! Check out our contributing guidelines to get started.

To run the same repository-wide hook suite used in CI:

python -m pip install pre-commit
pre-commit run --all-files

Before running local pre-commit hooks, install Rust via rustup and make sure cargo is available on your PATH.

To validate API behavior and schema compatibility locally, run:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --test api_contract_tests -- --nocapture
cargo test --test api_integration_tests -- --nocapture
./scripts/check_openapi_compat.sh master

check_openapi_compat.sh resolves origin/<base-ref> first, then local <base-ref>, then HEAD~1 as a local fallback. It requires a local Docker engine and you can pin a different oasdiff image via OASDIFF_IMAGE=<image:tag>.

For any workflow change, pin each GitHub Actions uses: reference to a full 40-character commit SHA (avoid mutable tags/branches).

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

• trippy - Provides core networking functionality
• ratatui - Powers our beautiful terminal interface
• Our amazing contributors who help improve Windows MTR