pingr 0.3.6

A blazing fast network scanner with beautiful terminal output and multiple export formats
pingr-0.3.6 is not a library.

pingr

Crates.io Documentation License

A blazing fast, modern network scanner with beautiful terminal output and multiple export formats. Alternative to tools like fping and nmap host discovery.

✨ Features

  • 🚀 Blazing Fast: Async parallel scanning with up to 10,000 concurrent threads
  • 🎨 Beautiful Output: Color-coded RTT times show network health at a glance
  • 📊 Multiple Export Formats: JSON, CSV, nmap, and plain text
  • 🧠 Smart Defaults: Auto-optimizes threads, enables hostname resolution and adaptive timeout
  • 📈 Detailed Statistics: RTT measurements, packet loss, and response time analysis
  • 🔍 DNS Resolution: Automatic hostname lookups with custom DNS server support (disable with -n)
  • 🪟 SMB Support: Query Windows hostnames via SMB (port 445) - most reliable method!
  • 📡 NetBIOS Support: Query Windows hostnames via NetBIOS (port 137) - lightweight alternative
  • 📁 File Input: Bulk scanning from target lists
  • 🛡️ Interrupt Handling: Graceful Ctrl-C with automatic result saving
  • 💻 Script-Friendly: Simple mode outputs clean IP lists for piping
  • ⚡ Cross-Platform: Works on Linux, macOS, Windows, and ARM devices

Installation

cargo install pingr

Quick Start

# Show help
pingr

# Simple scan with automatic hostname resolution
sudo pingr 192.168.1.0/24

# Fast scan without hostname resolution
sudo pingr -n 192.168.1.0/24

# Clean IP list output for scripts
sudo pingr -s 192.168.1.0/24

# Scan multiple networks from file
sudo pingr -i targets.txt

Usage

pingr <CIDR>... [OPTIONS]
pingr -i <FILE> [OPTIONS]

Arguments:
  <CIDR>         Network(s) in CIDR notation

Options:
  -i, --input <FILE>      Input file with targets
  -s, --simple            Simple mode - IP addresses only
  -n, --no-resolve        Skip hostname resolution
  --dns-server <IP>       Custom DNS server (e.g., domain controller)
  --netbios               Use NetBIOS name resolution (great for Windows)
  --smb                   Use SMB hostname query (most reliable for Windows)
  -q, --quiet             Quiet mode (minimal output)
  -v, --verbose           Show unreachable hosts
  -t, --threads <N>       Concurrent threads (auto)
  -c, --count <N>         Ping attempts per host (1)
  -o, --output <FILE>     Save results to file
  -f, --format <FMT>      Output format (text/json/both)
  --timeout <SEC>         Ping timeout in seconds (1)
  --stats                 Show RTT statistics
  --no-adaptive           Disable adaptive timeout
  --no-color              Disable colored output
  --export <FMT>          Export format (csv/nmap)
  -h, --help              Show help message

Examples

Basic Scanning

# Simple scan with beautiful output
sudo pingr 192.168.1.0/24

# Fast scan without DNS resolution
sudo pingr -n 10.0.0.0/24

# Multiple networks
sudo pingr 192.168.1.0/24 10.0.0.0/24 172.16.0.0/24

# Use custom DNS server (e.g., domain controller)
sudo pingr --dns-server 10.0.0.1 192.168.1.0/24

# Use NetBIOS for Windows networks (no DNS setup required!)
sudo pingr --netbios 192.168.1.0/24

# Use SMB for most reliable Windows hostname detection
sudo pingr --smb 192.168.1.0/24

Corporate Network Scanning

When scanning internal corporate networks, you have multiple options for hostname resolution:

Option 1: SMB (Most Reliable for Windows)

SMB queries directly retrieve hostnames from Windows hosts:

# Get Windows hostnames via SMB (port 445)
sudo pingr --smb 192.168.1.0/24

# SMB with statistics
sudo pingr --smb --stats 10.0.13.0/24

# Export with SMB-resolved names
sudo pingr --smb -o windows-scan -f both 192.168.1.0/24

Option 2: NetBIOS (Lightweight Alternative)

NetBIOS queries work even without reverse DNS configured:

# Get Windows hostnames via NetBIOS (port 137)
sudo pingr --netbios 192.168.1.0/24

# NetBIOS with statistics
sudo pingr --netbios --stats 10.0.13.0/24

# Export with NetBIOS names
sudo pingr --netbios -o windows-scan -f both 192.168.1.0/24

Option 3: Custom DNS Server

Use your domain controller if reverse DNS zones are configured:

# Scan with domain controller DNS
sudo pingr --dns-server 10.0.0.1 192.168.1.0/24

# Multiple networks with DC DNS
sudo pingr --dns-server 10.0.0.1 192.168.1.0/24 192.168.2.0/24

# Export results with hostnames from AD
sudo pingr --dns-server 10.0.0.1 -i corporate-networks.txt -o ad-audit -f both

Script Integration

# Clean IP list for piping
sudo pingr -s 192.168.1.0/24 | xargs -I {} nmap -sV {}

# Use in bash scripts
for ip in $(sudo pingr -s 192.168.1.0/24); do
    echo "Checking $ip..."
    ssh admin@$ip uptime 2>/dev/null
done

# Save to file for later processing
sudo pingr -s 192.168.1.0/24 > live_hosts.txt

Bulk Scanning

Create a targets.txt file:

# Corporate networks
192.168.1.0/24
192.168.2.0/24
10.0.0.0/24

# Branch offices
10.10.10.0/24
10.10.20.0/24

# Single servers
10.0.0.10
192.168.1.1

Then scan:

# Scan all networks from file
sudo pingr -i targets.txt

# With full features
sudo pingr -i targets.txt -t 5000 --stats -o results -f both

# Simple mode for automation
sudo pingr -s -i targets.txt > all_live_hosts.txt

Enterprise Network Audit

# Comprehensive scan with all features
sudo pingr \
    -i networks.txt \     # Read from file
    -t auto \             # Auto-optimize threads
    -c 3 \                # 3 pings per host
    --stats \             # Show RTT statistics
    -v \                  # Show all hosts
    -o audit_$(date +%Y%m%d) \  # Timestamped output
    -f both \             # JSON and text output
    --export csv          # Also export as CSV

Interrupt Handling

# Start a large scan
sudo pingr -i large_networks.txt -t 5000

# Press Ctrl-C anytime to save partial results
# Results automatically saved to pingr_interrupted_TIMESTAMP.txt/json

Understanding RTT Colors

The tool color-codes response times for quick network health assessment:

  • 🟢 Green (0-10ms): Excellent - Local network, wired connections
  • 🟡 Yellow (11-50ms): Good - Normal Wi-Fi, acceptable latency
  • 🟠 Orange (51-100ms): Fair - Slower devices, potential congestion
  • 🔴 Red (100ms+): Poor - Network issues, investigate these hosts

Performance Guide

Network Size Hosts Recommended Threads Scan Time
/24 254 256 ~2 sec
/22 1,022 512 ~5 sec
/20 4,094 1,024 ~10 sec
/16 65,534 4,096 ~30 sec
/12 1,048,574 8,192 ~5 min

Target File Format

The input file supports:

  • CIDR notation: 192.168.1.0/24
  • Single IPs: 10.0.0.1 (converted to /32)
  • Comments: Lines starting with #
  • Empty lines are ignored

Building from Source

git clone https://github.com/cybrly/pingr.git
cd pingr
cargo build --release
sudo ./target/release/pingr

Cross-Compilation

# Install cross
cargo install cross

# For Raspberry Pi
cross build --release --target aarch64-unknown-linux-musl

# For Ubuntu/Debian
cross build --release --target x86_64-unknown-linux-musl

# For Windows
cross build --release --target x86_64-pc-windows-gnu

Platform Support

  • ✅ Linux (x86_64, aarch64, armv7)
  • ✅ macOS (Intel & Apple Silicon)
  • ✅ Windows (with administrator privileges)
  • ✅ Raspberry Pi (all models)
  • ✅ Docker containers (with --cap-add=NET_RAW)

Docker Usage

FROM rust:latest
RUN cargo install pingr
ENTRYPOINT ["pingr"]

docker build -t pingr .
docker run --rm --cap-add=NET_RAW pingr 192.168.1.0/24

Requirements

  • Privileges: Requires root/sudo for ICMP raw sockets
  • Rust: 1.70+ for building from source
  • Memory: ~50MB for /16 network scan
  • Network: ICMP echo requests must be allowed

Changelog

v0.3.6 (2024-01-23)

  • ✨ New Features:

    • SMB Hostname Query: Added --smb flag for Windows hostname queries via SMB (port 445) - most reliable method
    • NetBIOS Name Resolution: Added --netbios flag for Windows hostname queries via NetBIOS (port 137) - lightweight alternative
    • Works great for corporate Windows networks without reverse DNS configured
    • Get hostnames like 1000-00555-LT, CORP-LKAMINSKI directly from Windows hosts
    • Both methods work without DNS configuration
    • Debug output for troubleshooting hostname resolution issues

  • ✨ Improvements:

    • Added DNS resolution statistics to --stats output showing resolved vs unresolved hostnames
    • Better error handling for custom DNS server queries
    • Comprehensive help text with all resolution methods

v0.3.5 (2024-01-XX)

  • 🐛 Bug Fixes:
    • Fixed version display consistency
    • Cleaned up debug output from DNS resolution

v0.3.3 (2024-01-XX)

  • ✨ New Features:

    • Custom DNS Server: Added --dns-server flag to specify custom DNS server (e.g., domain controller) for hostname resolution
    • Ideal for corporate networks where internal DNS has better PTR records than system DNS

  • 🐛 Bug Fixes:

    • Fixed hostname resolution: Corrected Result handling in spawn_blocking (was using .unwrap_or(None) instead of .ok().flatten())
    • DNS lookups now properly return hostnames instead of silently failing
    • Version consistency across all files

v0.3.2 (2024-01-XX)

  • 🐛 Bug Fixes:
    • Attempted fix for hostname resolution (didn't work)
    • Fixed version consistency across all files
    • Improved async handling of DNS resolution with proper spawn_blocking

v0.3.1 (2024-01-XX)

  • 🔧 Minor improvements and bug fixes

v0.3.0 (2024-01-XX)

  • 🔄 Breaking Changes:
    • Hostname resolution now ON by default (use -n to disable)
    • Adaptive timeout now ON by default (use --no-adaptive to disable)
    • No more default 192.168.1.0/24 scan - shows help instead
  • ✨ New Features:
    • Added -s/--simple mode for clean IP-only output
    • Help menu displayed when run without arguments
    • Improved script integration support
  • 🐛 Fixes:
    • Better interrupt handling
    • Improved error messages

v0.2.0 (2024-01-XX)

  • 🎯 File Input Support: Read targets from text files with -i flag
  • 🌐 Multi-Network Scanning: Scan multiple networks in one run
  • 🛡️ Interrupt Handling: Graceful Ctrl-C with automatic result saving
  • 📊 Network Grouping: Results organized by source network
  • 🔧 Enhanced Progress: Better progress tracking for multiple networks
  • 📈 Improved Statistics: Added RTT min/max/avg calculations

v0.1.0 (2024-01-XX)

  • Initial release
  • Fast async scanning with customizable concurrency
  • Colorful terminal output with RTT color-coding
  • Multiple export formats (JSON, CSV, nmap)
  • Basic RTT statistics and DNS resolution
  • Auto-optimization for thread count

Tips & Tricks

Speed Optimization

# Maximum speed (no DNS, high threads)
sudo pingr -n -t 10000 10.0.0.0/16

# Balanced (auto threads, with DNS)
sudo pingr 10.0.0.0/16

Network Monitoring

# Regular monitoring script
#!/bin/bash
while true; do
    sudo pingr -s 192.168.1.0/24 > /tmp/current_hosts.txt
    diff /tmp/previous_hosts.txt /tmp/current_hosts.txt
    mv /tmp/current_hosts.txt /tmp/previous_hosts.txt
    sleep 300
done

Integration with Other Tools

# Find and scan web servers
sudo pingr -s 10.0.0.0/24 | xargs -P10 -I {} curl -s -o /dev/null -w "%{http_code} {}\n" http://{}:80 2>/dev/null

# SSH availability check
sudo pingr -s 192.168.1.0/24 | parallel -j10 "nc -z -w1 {} 22 && echo {} has SSH"

# Generate Ansible inventory
echo "[servers]" > inventory.ini
sudo pingr 10.0.0.0/24 | grep -E "\.1[0-9]{2}" >> inventory.ini

Troubleshooting

Permission Denied

# Linux: Set capabilities to avoid sudo
sudo setcap cap_net_raw+ep $(which pingr)

# macOS: Always requires sudo
# Windows: Run as Administrator

No Results

  • Check firewall rules allow ICMP
  • Verify network connectivity
  • Try increasing timeout: --timeout 3
  • Some hosts may block ICMP

Slow Performance

  • Reduce thread count for congested networks
  • Use -n to skip DNS resolution
  • Check system ulimits: ulimit -n

No Hostnames Showing

If you're not seeing hostnames even with DNS resolution enabled:

  1. Check if PTR records exist:

    # Test reverse DNS lookup
host 192.168.1.1
# Or with specific DNS server
host 192.168.1.1 10.0.0.1

  2. Common reasons:

    • Your DNS server doesn't have reverse DNS (PTR) zones configured
    • Internal IPs often don't have PTR records by default
    • Only the domain controller may have complete records

  3. Solutions:

    • Use --dns-server with your domain controller IP: sudo pingr --dns-server 10.0.0.1 192.168.1.0/24
    • Ask your network admin to configure reverse DNS zones for your networks
    • Use --stats flag to see DNS resolution success rate

  4. Setting up reverse DNS (for admins):

    • Windows DNS: Create reverse lookup zones (e.g., 13.0.10.in-addr.arpa for 10.0.13.0/24)
    • BIND: Add reverse zone files with PTR records
    • Ensure your DHCP server updates DNS with hostnames

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

# Fork and clone
git clone https://github.com/yourusername/pingr.git
cd pingr

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
cargo test
cargo clippy
cargo fmt

# Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

Author

Chris Neuwirth CNeuwirth@networksgroup.com GitHub: @cybrly

License

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

Acknowledgments

Star History

Star History Chart

Note: pingr requires root/administrator privileges to send ICMP packets. This is a system requirement for raw socket access, not a limitation of the tool.

For more information, bug reports, or feature requests, please visit the GitHub repository.