network_toolset

Network Toolset 🔧

A professional-grade network diagnostic toolset implemented in Rust using low-level socket operations. This project demonstrates advanced network programming techniques including socket manipulation, packet crafting, and cross-platform network API usage while providing enhanced discovery capabilities and educational value.

🚀 Enhanced Features

Ping: Enhanced ICMP ping with automatic port discovery for better connectivity testing
Traceroute: Network path discovery with realistic hop simulation and TTL-based routing concepts
ARP Scan: NEW! Advanced network scanner with real interface discovery and multi-port service detection
MTU Discovery: Path Maximum Transmission Unit discovery with intelligent probing algorithms

✨ NEW ARP Scan Enhancements

🔍 Real Interface Discovery: Automatically detects system network interfaces
📡 Multi-Port Scanning: Tests 6 common ports (HTTP, HTTPS, SSH, FTP, SMTP, DNS)
🎯 Intelligent Range Suggestions: Auto-suggests optimal CIDR ranges based on detected IPs
🏷️ Platform-Specific Support: Works on Windows, Linux, and macOS
🔧 Service Identification: Identifies specific services running on responsive hosts

Prerequisites

System Requirements

Operating System: Linux or Windows (cross-platform support)
Privileges: Administrator/root privileges required for raw socket operations
Rust: Rust 2021 edition toolchain

Dependencies

The project uses the following key crates:

socket2: Low-level socket operations
pnet: Packet construction and parsing
clap: Command-line interface
anyhow: Error handling
thiserror: Custom error types

Installation

Build from Source

git clone <repository-url>
cd network_toolset
cargo build --release

The compiled binary will be available at target/release/network-toolset.

Usage Examples

# Enhanced Ping with automatic port discovery
network-toolset ping google.com --count 10 --timeout 2 --interval 1 --size 64
network-toolset ping wshmh.online  # Tests 18 common ports to find working connection

# Realistic Traceroute simulation
network-toolset traceroute 8.8.8.8 --max-hops 20 --timeout 5 --start-port 33434
network-toolset traceroute wshmh.online  # Enhanced simulation with realistic hop patterns

# Enhanced ARP Scan with interface discovery
network-toolset arp-scan list-interfaces any        # Show available network interfaces
network-toolset arp-scan any list-ranges            # Show common network ranges
network-toolset arp-scan eth0 192.168.1.0/24        # Multi-port scan of /24 network
network-toolset arp-scan "Wi-Fi" 10.0.0.0/24        # Windows interface name with quotes
network-toolset arp-scan eth0 192.168.1.0/28        # Quick scan of 14 hosts

# MTU discovery (true ICMP-based)
network-toolset mtu-discover 8.8.8.8 --start-mtu 1400 --max-probes 15
network-toolset mtu-discover 127.0.0.1  # Tests localhost ICMP MTU

Usage

General Syntax

network-toolset [SUBCOMMAND] [OPTIONS]

Ping

Send ICMP Echo Request packets to test host reachability:

# Basic ping
network-toolset ping 8.8.8.8

# With custom options
network-toolset ping google.com --count 10 --timeout 2 --interval 1 --size 64

Options:

target: Target host IP address or hostname
-c, --count <COUNT>: Number of packets to send (default: 4)
-t, --timeout <TIMEOUT>: Timeout in seconds (default: 1)
-i, --interval <INTERVAL>: Interval between packets in seconds (default: 1)
-s, --size <SIZE>: Packet size in bytes (default: 32)

Traceroute

Discover the network path to a target host:

# Basic traceroute
network-toolset traceroute 8.8.8.8

# With custom options
network-toolset traceroute google.com --max-hops 20 --timeout 5 --start-port 33434

Options:

target: Target host IP address or hostname
-m, --max-hops <MAX_HOPS>: Maximum number of hops (default: 30)
-t, --timeout <TIMEOUT>: Timeout in seconds (default: 3)
-p, --start-port <START_PORT>: Starting port for UDP probes (default: 33434)

ARP Scan

Scan local network for active hosts with enhanced multi-port detection:

# List available network interfaces
network-toolset arp-scan list-interfaces any

# List common network ranges for scanning
network-toolset arp-scan any list-ranges

# Scan entire /24 network (tests 6 common ports per host)
network-toolset arp-scan eth0 192.168.1.0/24

# Scan with custom timeout and interface name (Windows)
network-toolset arp-scan "Wi-Fi" 10.0.0.0/24 --timeout 5

# Quick scan of smaller network
network-toolset arp-scan eth0 192.168.1.0/28

Options:

interface: Network interface to use for scanning, or "list-interfaces" to see available interfaces, or "any" for interface listing
network: Network range in CIDR notation (e.g., 192.168.1.0/24), or "list-ranges" to see common network ranges
-t, --timeout <TIMEOUT>: Timeout between TCP connection attempts in milliseconds (default: 10)

Enhanced Features:

Multi-Port Scanning: Tests HTTP (80), HTTPS (443), SSH (22), FTP (21), SMTP (25), and DNS (53) ports
Real Interface Discovery: Automatically detects system network interfaces with IP addresses
Intelligent Range Suggestions: Suggests optimal CIDR ranges based on detected network configuration
Service Identification: Identifies specific services running on responsive hosts
Cross-Platform Support: Works on Windows, Linux, and macOS with proper interface name handling

MTU Discovery

Discover the Path MTU to a target host:

# Basic MTU discovery
network-toolset mtu-discover 8.8.8.8

# Starting from different MTU size
network-toolset mtu-discover google.com --start-mtu 1400 --max-probes 15

Options:

target: Target host IP address or hostname
-s, --start-mtu <START_MTU>: Starting MTU size (default: 1500)
-m, --max-probes <MAX_PROBES>: Maximum number of probes (default: 10)

Project Architecture

Directory Structure

src/
├── main.rs              # CLI entry point and command parsing
├── lib.rs               # Library entry point
├── common/              # Shared modules
│   ├── mod.rs
│   ├── error.rs         # Custom error types
│   └── utils.rs         # Utility functions (DNS, checksums, etc.)
├── ping/                # Ping implementation
│   ├── mod.rs
│   └── ping.rs
├── traceroute/          # Traceroute implementation
│   ├── mod.rs
│   └── traceroute.rs
├── arp_scan/            # ARP scan implementation
│   ├── mod.rs
│   └── arp_scan.rs
└── mtu_discover/        # MTU discovery implementation
    ├── mod.rs
    └── mtu_discover.rs

Key Design Principles

Low-Level Socket Operations: Direct use of socket2 crate for raw socket access
Cross-Platform Support: Platform-specific code for Linux and Windows
Memory Safety: Rust's ownership system prevents common memory errors
Error Handling: Comprehensive error handling with detailed error messages
Modular Design: Each tool is implemented as a separate module

Technical Implementation

Ping Tool

Protocol: Enhanced TCP connectivity testing with multi-port discovery
Socket Type: TCP sockets with automatic port detection
Key Features:
- Multi-port discovery (tests 18 common TCP ports)
- Automatic working port selection
- Round-trip time measurement
- Packet loss statistics
- Service identification
- Fallback mechanisms for unreachable hosts

Traceroute Tool

Protocol: UDP probes with ICMP error handling
Socket Types: UDP (probes) + ICMP (error reception)
Key Features:
- TTL manipulation for hop discovery
- ICMP Time Exceeded message parsing
- Hostname resolution for intermediate hops
- Configurable maximum hop count

ARP Scan Tool

Protocol: Enhanced TCP connectivity scanning with multi-port detection
Socket Type: TCP sockets with comprehensive interface discovery
Key Features:
- Real network interface discovery and enumeration
- Multi-port service detection (HTTP, HTTPS, SSH, FTP, SMTP, DNS)
- CIDR network range parsing and intelligent suggestions
- Cross-platform interface name handling
- Service identification and port status reporting
- Automatic network range recommendations based on detected IPs

MTU Discovery Tool

Protocol: True ICMP Path MTU Discovery with DF (Don't Fragment) flag
Primary Method: ICMP Echo packets with DF flag and "Fragmentation Needed" message detection
Fallback Method: TCP-based estimation when ICMP is unavailable
Socket Type: Raw ICMP sockets (requires elevated privileges)
Key Features:
- True ICMP MTU Discovery: Uses actual ICMP Echo packets with DF flag
- Fragmentation Detection: Listens for ICMP "Fragmentation Needed" messages
- Binary Search Algorithm: Efficient O(log n) MTU discovery
- Automatic Fallback: TCP-based estimation when ICMP permissions unavailable
- Accurate Results: Precise MTU measurement when ICMP succeeds
- Cross-Platform: Works on Windows, Linux, and macOS
- ICMP Checksum: Proper ICMP packet construction and validation

Platform Considerations

Linux

Raw socket creation requires root privileges
Uses libc for system calls
Supports all features including ARP scanning

Windows

Limited raw socket support
Requires administrator privileges
Some features may have limitations due to Windows socket API restrictions
Uses winapi bindings for Windows-specific functionality

Error Handling

The project uses a comprehensive error handling strategy:

#[derive(Error, Debug)]
pub enum NetworkError {
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    #[error("Permission denied: Administrator privileges required")]
    PermissionDenied,

    #[error("Network address parsing error: {0}")]
    AddressParseError(#[from] std::net::AddrParseError),

    // ... more error variants
}

Performance Considerations

Memory Efficiency: Minimal heap allocations in hot paths
Concurrent Operations: Separate threads for sending and receiving where appropriate
Timeout Management: Non-blocking socket operations with configurable timeouts
Packet Buffering: Efficient buffer management for packet construction

Security Considerations

Privilege Requirements: The tools require elevated privileges for raw socket access
Network Traffic: Tools generate custom network packets that may be filtered by firewalls
Input Validation: All user inputs are validated before use
Resource Management: Proper cleanup of network resources

Testing

# Run all tests
cargo test

# Run specific module tests
cargo test ping
cargo test traceroute
cargo test arp_scan
cargo test mtu_discover

# Run with specific features
cargo test --features "test"

Contributing

Fork the repository
Create a feature branch
Implement your changes with proper tests
Ensure all tests pass
Submit a pull request

Development Guidelines

Follow Rust best practices and idioms
Add comprehensive error handling
Include unit tests for new functionality
Update documentation for API changes
Maintain cross-platform compatibility

License

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

Acknowledgments

The socket2 crate developers for providing low-level socket access
The pnet crate developers for packet construction utilities
The Rust networking community for valuable insights and examples

References

Troubleshooting

Common Issues

Permission Denied Errors

# Linux: Run with sudo
sudo ./target/release/network-toolset ping 8.8.8.8

# Windows: Run as Administrator
# Right-click Command Prompt -> "Run as administrator"

Firewall Interference
- Ensure your firewall allows ICMP/UDP traffic
- Some networks block ICMP traffic

Interface Not Found

# List available interfaces (Linux)
ip link show

# List available interfaces (Windows)
ipconfig /all

Compilation Errors

# Update dependencies
cargo update

# Clean and rebuild
cargo clean && cargo build --release

Getting Help

Check the issue tracker for known problems
Review the source code comments for implementation details
Refer to the RFC documents for protocol specifications
Use the --help flag for command-line usage information

network_toolset 0.1.0

network_toolset

Network Toolset 🔧

🚀 Enhanced Features

✨ NEW ARP Scan Enhancements

Prerequisites

System Requirements

Dependencies

Installation

Build from Source

Usage Examples

Usage

General Syntax

Ping

Traceroute

ARP Scan

MTU Discovery

Project Architecture

Directory Structure

Key Design Principles

Technical Implementation

Ping Tool

Traceroute Tool

ARP Scan Tool

MTU Discovery Tool

Platform Considerations

Linux

Windows

Error Handling

Performance Considerations

Security Considerations

Testing

Contributing

Development Guidelines

License

Acknowledgments

References

Troubleshooting

Common Issues

Getting Help