r-lanlib

A Rust library crate for performing network scanning operations on any local area network (LAN). This is the Rust version of the go-lanscan package.

Features

ARP Scanning: Discover devices on your network using Address Resolution Protocol
SYN Scanning: Detect open ports on discovered devices using TCP SYN packets
Full Scanning: Combined ARP and SYN scanning in a single operation
Vendor Detection: Identify device manufacturers using MAC address lookup
Hostname Resolution: Resolve hostnames for discovered devices
Async Communication: Channel-based communication for real-time scan results
Flexible Targeting: Support for CIDR blocks, IP ranges, and port ranges

Requirements

Root privileges required: This library performs raw packet operations that require elevated permissions
Rust 1.89.0+ with Rust 2024 edition support

Installation

cargo add r-lanlib

Quick Start

See the working examples in examples/:

arp-scanner.rs - ARP device discovery
syn-scanner.rs - Port scanning on known devices
full-scanner.rs - Combined ARP + SYN scanning

Run them from the workspace root:

sudo -E cargo run --example arp-scanner -p r-lanlib
sudo -E cargo run --example syn-scanner -p r-lanlib
sudo -E cargo run --example full-scanner -p r-lanlib

API Reference

Core Modules

`network`

Provides helpers for selecting network interfaces:

get_default_interface() - Get the default network interface, returns Result<NetworkInterface>
get_interface(name) - Get a specific interface by name, returns Result<NetworkInterface>
get_available_port() - Find an available port for scanning, returns Result<u16>

`routing`

Provides OS-level routing table inspection:

get_default_gateway() - Detect the default gateway IP address by parsing the system routing table (netstat -rn on macOS, ip route show on Linux). Returns Option<Ipv4Addr> — None if the gateway cannot be determined or the platform is unsupported.

`oui`

OUI (Organizationally Unique Identifier) lookup for resolving MAC address prefixes to vendor/organization names:

oui::default(project_name, max_age) - Initialize the built-in IEEE OUI database. Downloads and caches five IEEE CSV data files locally under the OS-appropriate data directory for project_name. Re-downloads automatically when the cached files are older than max_age. Returns Result<Arc<dyn Oui>>.
oui::traits::Oui - Trait for custom OUI implementations. Implement this to supply your own vendor database to the scanners.
oui::db::OuiDb - The default implementation backed by locally cached IEEE CSV files. Supports MA-L (24-bit), MA-M (28-bit), and MA-S/IAB (36-bit) prefixes, resolving the most-specific match first.
oui::types::OuiData - Holds the organization string for a matched prefix.

`wire`

Low-level packet I/O:

wire::default(interface) - Create a Wire for reading and sending packets
Various packet builders for ARP, SYN, RST packets (in the packet module)

`scanners`

Main scanning implementations:

ARPScanner - Discover devices using ARP
SYNScanner - Scan ports on known devices
FullScanner - Combined ARP + SYN scanning

`targets`

Target specification utilities:

ips::IPTargets - Define IP ranges and CIDR blocks
ports::PortTargets - Define port ranges and individual ports

Data Structures

`Device`

Represents a discovered network device:

pub struct Device {
    pub hostname: String,
    pub ip: Ipv4Addr,
    pub mac: MacAddr,
    pub vendor: String,
    pub is_current_host: bool,
    pub is_gateway: bool,
    pub open_ports: PortSet,
    pub latency_ms: Option<u128>,
    pub response_ttl: Option<u8>,
}

`Port`

Represents a network port:

pub struct Port {
    pub id: u16,
    pub service: String,
}

`PortSet`

Wrapper around HashSet<Port> with convenience methods:

pub struct PortSet(pub HashSet<Port>);

impl PortSet {
    pub fn new() -> Self;
    pub fn to_sorted_vec(&self) -> Vec<Port>;
}

`ScanMessage`

Messages sent over the notification channel:

pub enum ScanMessage {
    Done,                    // Scanning complete
    Info(Scanning),          // Status update
    ARPScanDevice(Device),   // ARP discovery result
    SYNScanDevice(Device),   // SYN scan result (Device with open_ports populated)
}

Target Specification

IP Targets

// CIDR blocks
IPTargets::new(vec!["192.168.1.0/24".to_string()]);

// IP ranges
IPTargets::new(vec!["192.168.1.1-192.168.1.100".to_string()]);

// Individual IPs
IPTargets::new(vec!["192.168.1.1".to_string(), "10.0.0.1".to_string()]);

Port Targets

// Port ranges
PortTargets::new(vec!["1-1000".to_string()]);

// Individual ports
PortTargets::new(vec!["22".to_string(), "80".to_string(), "443".to_string()]);

// Mixed specification
PortTargets::new(vec![
    "22".to_string(),
    "80".to_string(),
    "8000-9000".to_string()
]);

Configuration Options

Scanner Timeouts

idle_timeout - How long to wait for responses before concluding scan
Default: 10 seconds (10,000ms)
Recommended: 5-30 seconds depending on network size and latency

Packet Send Throttle

throttle - Delay inserted between sending each packet
Default: 200 microseconds (Duration::from_micros(200))
Higher values reduce packet loss on congested or high-latency networks at the cost of increased total scan time

Scanner Features

include_vendor - Enable MAC address vendor lookup (requires oui to be set)
oui - Supply an Arc<dyn Oui> database for vendor lookups. Use oui::default(project_name, max_age) for the built-in IEEE database, or provide a custom implementation. When None, vendor lookup is skipped even if include_vendor is true.
include_host_names - Resolve hostnames via reverse DNS lookup
source_port - Source port for scan packets (auto-selected if not specified)
throttle - Delay between sending packets (default: 200µs); increase for more accurate scans on lossy or congested networks

Performance Tuning

Concurrent scanning: Multiple threads handle packet I/O for optimal throughput
Memory efficiency: Zero-copy packet processing where possible
Throttle control: Configurable per-packet send delay via throttle builder field (default 200µs); higher values reduce packet loss at the cost of scan speed
Timeout optimization: Adaptive timeouts based on network response times

Security Considerations

Requires root privileges for raw socket access on Unix-like systems
Network scanning may be restricted by network policies and firewalls
Built-in rate limiting prevents network congestion and reduces detection risk
Minimal network footprint: Optimized packet sizes and timing
Memory safety: Rust's ownership system prevents buffer overflows and memory corruption
Use responsibly and only on networks you own or have permission to scan
Logging: All scan activities can be logged for audit purposes

Ethical Usage Guidelines

Always obtain proper authorization before scanning
Respect network resources and avoid aggressive scanning
Be aware that scanning activities may be logged by network security systems
Consider the impact on network performance during large-scale scans

Error Handling

The library uses RLanLibError for comprehensive error reporting:

License

This project is dual-licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Related Projects

go-lanscan - Original Go implementation
r-lancli - Command-line interface using this library
r-lanterm - Terminal UI application using this library

r-lanlib 0.11.0