Troubleshooting Guide

Comprehensive troubleshooting procedures for ProRT-IP issues across platforms, performance problems, and common errors.

Common Issues

Permission Denied Errors

Symptoms:

Error: Permission denied (os error 13)
Error: Operation not permitted (os error 1)
Error: Failed to create raw socket

Cause: Raw sockets require elevated privileges on most operating systems. This is a security measure to prevent unauthorized packet manipulation.

Solutions:

1. Run with sudo (testing):

sudo prtip -sS -p 80,443 192.168.1.1

2. Set capabilities (Linux production):

# Build release binary
cargo build --release

# Grant raw socket capability
sudo setcap cap_net_raw,cap_net_admin+ep ./target/release/prtip

# Run without sudo
./target/release/prtip -sS -p 80,443 192.168.1.1

3. Use TCP Connect scan (no privileges required):

# Connect scan works without elevated privileges
prtip -sT -p 80,443 192.168.1.1
# Note: Slower and more detectable than SYN scan

4. Add user to specific group (Linux):

sudo usermod -a -G netdev $USER
# Log out and back in for group membership to take effect

Verification:

# Check capabilities (Linux)
getcap ./target/release/prtip
# Expected: cap_net_admin,cap_net_raw+ep

Packet Capture Failures

Symptoms:

Error: No suitable device found
Error: Failed to open capture device
Error: Device does not exist
PCAPNG capture failed: Interface not found

Causes:

• Network interface doesn't exist
• Interface name is incorrect
• Missing packet capture drivers (Windows/macOS)
• Permission issues

Solutions:

1. List available interfaces:

# Linux
ip link show
ip addr show

# macOS
ifconfig
networksetup -listallhardwareports

# Windows
ipconfig /all

2. Specify interface explicitly:

# Linux
prtip -e eth0 -sS 192.168.1.1

# macOS
prtip -e en0 -sS 192.168.1.1

# Windows
prtip -e "Ethernet" -sS 192.168.1.1

3. Install packet capture drivers (Windows):

# Download Npcap from https://npcap.com/
# Choose "WinPcap API-compatible mode" during installation

4. Install ChmodBPF (macOS):

# Install ChmodBPF for non-root packet capture
brew install --cask wireshark

# Or manually:
sudo chown $USER:admin /dev/bpf*
sudo chmod 600 /dev/bpf*

5. Check interface status:

# Ensure interface is UP
sudo ip link set eth0 up

# Verify interface has IP address
ip addr show eth0

Common Interface Names:

Network Timeout Issues

Symptoms:

Error: Operation timed out
Scan completed but no results
Warning: High timeout rate (>50%)

Causes:

• Target is down or blocking probes
• Network congestion
• Firewall dropping packets
• Timeout value too low
• Rate limiting too aggressive

Solutions:

1. Increase timeout:

# Use paranoid timing for slow/unreliable networks
prtip -T0 -p 80,443 192.168.1.1

# Or specify custom timeout (milliseconds)
prtip --timeout 5000 -p 80,443 192.168.1.1

2. Adjust timing template:

# T0 = Paranoid (5 min timeout, very slow)
# T1 = Sneaky (15 sec timeout, slow)
# T2 = Polite (1 sec timeout, medium)
# T3 = Normal (1 sec timeout, default)
# T4 = Aggressive (500ms timeout, fast)
# T5 = Insane (100ms timeout, very fast)

prtip -T2 -p 80,443 192.168.1.1

3. Reduce scan rate:

# Limit to 1000 packets/second
prtip --max-rate 1000 -sS 192.168.1.0/24

# Very slow scan (100 pps)
prtip --max-rate 100 -sS 192.168.1.0/24

4. Check target reachability:

# Ping target first
ping -c 4 192.168.1.1

# Traceroute to identify routing issues
traceroute 192.168.1.1

# Check if specific ports are filtered
telnet 192.168.1.1 80

5. Verify no firewall interference:

# Temporarily disable local firewall (Linux)
sudo ufw disable

# Check iptables rules
sudo iptables -L -v -n

# Windows Firewall
netsh advfirewall show allprofiles

Timeout Recommendations:

Service Detection Problems

Symptoms:

Port 80: open (service: unknown)
Port 443: open (service: unknown)
Low service detection rate (<30%)

Causes:

• Service using non-standard port
• Service requires specific handshake
• Service is SSL/TLS wrapped
• Insufficient timeout for service probe
• Service detection disabled

Solutions:

1. Enable service detection:

# Basic service detection
prtip -sV -p 80,443 192.168.1.1

# Aggressive service detection
prtip -A -p 80,443 192.168.1.1

# Higher intensity (0-9, default 7)
prtip -sV --version-intensity 9 -p 80,443 192.168.1.1

2. Increase service probe timeout:

# Allow more time for service responses
prtip -sV --timeout 5000 -p 80,443 192.168.1.1

3. Enable SSL/TLS detection:

# TLS handshake enabled by default in v0.4.0+
prtip -sV -p 443 192.168.1.1

# Disable TLS for performance
prtip -sV --no-tls -p 443 192.168.1.1

4. Manual service verification:

# Connect manually and send HTTP request
echo -e "GET / HTTP/1.0\r\n\r\n" | nc 192.168.1.1 80

# SSL/TLS connection
openssl s_client -connect 192.168.1.1:443 -showcerts

5. Check service probe database:

# List available probes
prtip --list-probes | grep -i http
# ProRT-IP uses 187 embedded probes by default

Expected Detection Rates:

OS Fingerprinting Issues

Symptoms:

OS fingerprint: Unknown
OS detection confidence: Low (<30%)
No OS matches found

Causes:

• Target has strict firewall rules
• Not enough open ports for fingerprinting
• OS not in fingerprint database
• Unusual network stack behavior
• Virtual machine or container

Solutions:

1. Enable OS detection:

# Basic OS detection
prtip -O -p 80,443 192.168.1.1

# Aggressive OS detection
prtip -A -p 80,443 192.168.1.1

2. Scan more ports:

# OS detection works best with multiple open ports
prtip -O -p- 192.168.1.1

# At minimum, scan common ports
prtip -O -F 192.168.1.1

3. Ensure target is responsive:

# Combine with service detection
prtip -A -p 22,80,443 192.168.1.1

# Verify target responds to probes
prtip -sS -p 22,80,443 192.168.1.1

4. Check OS fingerprint database:

# ProRT-IP uses 2600+ signatures
# Coverage: Windows, Linux, BSD, macOS, network devices

# Manual OS identification via TTL
# TTL 64 = Linux/Unix
# TTL 128 = Windows
# TTL 255 = Network device (Cisco, etc.)

OS Detection Confidence Levels:

Platform-Specific Issues

Linux

AppArmor/SELinux blocking raw sockets

Symptoms:

Error: Permission denied even with sudo
Error: SELinux is preventing prtip from using raw sockets

Solutions:

# Check SELinux status
getenforce

# Temporarily disable (testing only)
sudo setenforce 0

# Create SELinux policy (production)
sudo semanage permissive -a prtip_t

# AppArmor (Ubuntu/Debian)
sudo aa-complain /path/to/prtip

iptables interfering with scans

Symptoms:

Unexpected RST packets
Scan results inconsistent
Local firewall blocking responses

Solutions:

# Check iptables rules
sudo iptables -L -v -n

# Temporarily disable (testing only)
sudo iptables -P INPUT ACCEPT
sudo iptables -P OUTPUT ACCEPT
sudo iptables -P FORWARD ACCEPT
sudo iptables -F

# Or create exception for prtip
sudo iptables -A OUTPUT -m owner --uid-owner $(id -u) -j ACCEPT

Socket buffer limits

Symptoms:

Error: Cannot allocate memory
Warning: Socket buffer size limit reached
High packet loss at high rates

Solutions:

# Check current limits
sysctl net.core.rmem_max
sysctl net.core.wmem_max

# Increase socket buffers (requires root)
sudo sysctl -w net.core.rmem_max=134217728
sudo sysctl -w net.core.wmem_max=134217728

# Make persistent
echo "net.core.rmem_max=134217728" | sudo tee -a /etc/sysctl.conf
echo "net.core.wmem_max=134217728" | sudo tee -a /etc/sysctl.conf

Windows

Npcap not installed or outdated

Symptoms:

Error: The NPF driver isn't running
Error: Failed to open the adapter
PCAPNG capture not working

Solutions:

1. Download Npcap from https://npcap.com/
2. Run installer as Administrator
3. Choose "Install Npcap in WinPcap API-compatible Mode"
4. Reboot if prompted
5. Verify installation:

sc query npcap

Windows Firewall blocking scans

Symptoms:

No responses from local targets
Scan hangs or times out
Windows Security alerts

Solutions:

# Check firewall status
netsh advfirewall show allprofiles

# Create exception for prtip
netsh advfirewall firewall add rule name="ProRT-IP" dir=out action=allow program="C:\path\to\prtip.exe"

# Or temporarily disable (testing only)
netsh advfirewall set allprofiles state off

SYN scan tests fail on loopback

Symptoms:

4 SYN discovery tests fail on Windows loopback
Test test_discovery_syn_ipv4 ... FAILED

Cause: This is expected behavior on Windows. The Windows network stack doesn't support SYN scanning on loopback (127.0.0.1) due to architectural limitations.

Solutions:

# Use TCP Connect scan on loopback (works)
prtip -sT -p 80 127.0.0.1

# Use real network interface for SYN scans
prtip -sS -p 80 192.168.1.1

# This is documented and not a bug

macOS

ChmodBPF not configured

Symptoms:

Error: You don't have permission to capture on that device
Error: No suitable device found

Solutions:

# Install ChmodBPF (easiest via Wireshark)
brew install --cask wireshark

# Or manual configuration
cd /Library/LaunchDaemons
sudo curl -O https://raw.githubusercontent.com/Homebrew/homebrew-cask/master/Casks/wireshark-chmodbpf.rb
sudo launchctl load /Library/LaunchDaemons/ChmodBPF.plist

# Reboot for changes to take effect
sudo reboot

FIN/NULL/Xmas scans don't work

Symptoms:

All ports show as open|filtered
No definitive open/closed results

Cause: macOS and some BSD-based network stacks don't respond to stealth scans as expected. This is a limitation of the OS, not ProRT-IP.

Solutions:

# Use SYN scan instead
prtip -sS -p 80,443 192.168.1.1

# Or TCP Connect scan
prtip -sT -p 80,443 192.168.1.1

System Integrity Protection (SIP) interference

Symptoms:

Error: Operation not permitted
Error: Cannot modify network stack

Solutions:

# Check SIP status
csrutil status

# SIP must be enabled for security
# Solution: Run with sudo or use TCP Connect scan
sudo prtip -sS -p 80,443 192.168.1.1

Performance Issues

Slow Scanning

Symptoms:

• Scan takes much longer than expected
• Progress bar moves very slowly
• Low packet rate (<1000 pps)

Diagnosis:

# Run with verbose output
prtip -sS -vv -p 80,443 192.168.1.0/24

# Check timing template
prtip -T5 -p 80,443 192.168.1.0/24  # Fastest

# Monitor system resources
top  # Linux/macOS
taskmgr  # Windows

Solutions:

1. Increase parallelism:

# Override default parallelism (num_cpus * 2)
prtip --parallelism 100 -sS 192.168.1.0/24

2. Adjust timing template:

# T5 = Insane (fastest, least stealthy)
prtip -T5 -p 80,443 192.168.1.0/24

# Or custom rate
prtip --max-rate 100000 -sS 192.168.1.0/24

3. Disable unnecessary features:

# Disable service detection
prtip -sS -p 80,443 192.168.1.0/24  # No -sV

# Disable OS detection
prtip -sS -p 80,443 192.168.1.0/24  # No -O

# Disable TLS handshake
prtip -sV --no-tls -p 443 192.168.1.0/24

4. Use NUMA optimization (multi-socket systems):

# Enable NUMA-aware thread pinning
prtip --numa -sS 192.168.1.0/24
# Can provide 30%+ improvement on dual-socket servers

5. Reduce target scope:

# Scan fewer ports
prtip -F 192.168.1.0/24  # Top 100 instead of all 65535

# Scan smaller ranges
prtip -sS -p 80,443 192.168.1.0/28  # /28 instead of /24

High Memory Usage

Symptoms:

Warning: Memory usage above 80%
Error: Cannot allocate memory
System becoming unresponsive
OOM killer terminating process

Diagnosis:

# Check memory usage
free -h  # Linux
vm_stat  # macOS

# Monitor prtip memory
ps aux | grep prtip
top -p $(pgrep prtip)

Solutions:

1. Reduce parallelism:

# Lower concurrent operations
prtip --parallelism 10 -sS 192.168.1.0/24

2. Disable PCAPNG capture:

# Packet capture uses significant memory
prtip -sS 192.168.1.0/24  # Don't use --packet-capture

3. Stream results to disk:

# Don't buffer all results in memory
prtip -sS -oN results.txt 192.168.1.0/24

# Use database export for large scans
prtip -sS --with-db --database results.db 192.168.1.0/24

4. Scan in smaller batches:

# Break large scans into chunks
for i in {1..255}; do
  prtip -sS -p 80,443 192.168.1.$i
done

5. Resource monitoring triggers automatic degradation (v0.4.0+):

# ProRT-IP automatically reduces memory usage when >80% utilized
# Manual configuration:
prtip --memory-limit 80 -sS 192.168.1.0/24

CPU Bottlenecks

Symptoms:

• CPU usage at 100%
• Scan slower than network capacity
• High context switching

Diagnosis:

# Check CPU usage
mpstat 1 10  # Linux
top  # macOS
perfmon  # Windows

# Check context switches
vmstat 1 10  # Linux

Solutions:

1. Adjust thread count:

# Match CPU core count
prtip --threads $(nproc) -sS 192.168.1.0/24

# Or explicitly set
prtip --threads 8 -sS 192.168.1.0/24

2. Enable NUMA optimization:

# Pin threads to specific cores
prtip --numa -sS 192.168.1.0/24

3. Reduce packet processing overhead:

# Disable service detection
prtip -sS 192.168.1.0/24  # No -sV

# Use SYN scan instead of Connect
prtip -sS 192.168.1.0/24  # Faster than -sT

4. Build with release optimizations:

# Ensure using release build
cargo build --release
./target/release/prtip -sS 192.168.1.0/24

# Debug builds are 10-100x slower

Output & Export Issues

Greppable Output Not Parsing

Symptoms:

Output format is malformed
Cannot parse greppable results
Fields are missing or incorrect

Solutions:

# Verify greppable format
prtip -sS -oG results.txt 192.168.1.1
cat results.txt

# Expected format:
# Host: 192.168.1.1 () Status: Up
# Host: 192.168.1.1 () Ports: 80/open/tcp//http///, 443/open/tcp//https///

# Parse with awk
awk '/Ports:/ {print $2, $5}' results.txt

XML Output Invalid

Symptoms:

XML parsing errors
Invalid XML structure
Missing closing tags

Solutions:

# Verify XML output
prtip -sS -oX results.xml 192.168.1.1

# Validate XML
xmllint --noout results.xml

# Common issues:
# - Special characters in banners (automatically escaped)
# - Incomplete scans (use Ctrl+C gracefully, not kill -9)

Database Export Fails

Symptoms:

Error: Database locked
Error: Cannot create database file
SQLite error: disk I/O error

Solutions:

# Check file permissions
ls -la results.db
chmod 644 results.db

# Ensure directory is writable
mkdir -p /tmp/ProRT-IP
prtip -sS --with-db --database /tmp/ProRT-IP/results.db 192.168.1.1

# Check disk space
df -h /tmp

# Verify database is not locked by another process
lsof results.db

Database Issues

Cannot Query Database

Symptoms:

Error: No such table: scans
Error: Database file is encrypted or is not a database

Solutions:

# Verify database schema
sqlite3 results.db ".schema"

# Expected tables:
# - scans
# - scan_results

# Query manually
sqlite3 results.db "SELECT * FROM scans;"

# Use prtip db commands
prtip db list results.db
prtip db query results.db --scan-id 1

Database Corruption

Symptoms:

Error: Database disk image is malformed
SQLite error: database corruption

Solutions:

# Attempt recovery
sqlite3 results.db ".dump" > dump.sql
sqlite3 recovered.db < dump.sql

# Verify integrity
sqlite3 results.db "PRAGMA integrity_check;"

# If corrupted beyond repair, re-run scan
prtip -sS --with-db --database new-results.db 192.168.1.0/24

IPv6 Issues

IPv6 Scans Not Working

Symptoms:

Error: IPv6 not supported for this scan type
Warning: IPv6 support is partial in v0.4.0
Only TCP Connect works with IPv6

Cause: IPv6 support is partial in v0.4.0. Only TCP Connect scanner supports IPv6 targets.

Solutions:

# Use TCP Connect scan for IPv6
prtip -sT -p 80,443 2001:db8::1

# IPv6 CIDR ranges supported
prtip -sT -p 80 2001:db8::/64

# Dual-stack scanning
prtip -sT -p 80,443 example.com  # Resolves both IPv4 and IPv6

# Full IPv6 support available in v0.5.0+ (Phase 5 complete)
# Now supported: SYN (-sS), UDP (-sU), FIN/NULL/Xmas, Discovery

IPv6 Address Resolution

Symptoms:

Error: Cannot resolve IPv6 address
Error: Name resolution failed

Solutions:

# Ensure IPv6 is enabled
ping6 2001:db8::1

# Check DNS resolution
nslookup -type=AAAA example.com
dig AAAA example.com

# Specify IPv6 explicitly
prtip -sT -6 -p 80 example.com

# Or use direct IPv6 address
prtip -sT -p 80 2001:db8::1

Advanced Troubleshooting

Enable Debug Logging

# Set RUST_LOG environment variable
RUST_LOG=debug prtip -sS 192.168.1.1

# More verbose
RUST_LOG=trace prtip -sS 192.168.1.1

# Module-specific logging
RUST_LOG=prtip_scanner=debug prtip -sS 192.168.1.1

# Save debug output
RUST_LOG=debug prtip -sS 192.168.1.1 2> debug.log

Packet Capture for Analysis

# Capture packets for analysis
prtip -sS --packet-capture -p 80,443 192.168.1.1
# Output: scan-TIMESTAMP.pcapng

# Analyze with Wireshark
wireshark scan-*.pcapng

# Or tcpdump
tcpdump -r scan-*.pcapng

Network Trace

# Linux: tcpdump
sudo tcpdump -i eth0 -w trace.pcap host 192.168.1.1

# Run scan in another terminal
prtip -sS -p 80,443 192.168.1.1

# Analyze trace
wireshark trace.pcap

Strace/Dtrace for System Calls

# Linux: strace
sudo strace -e trace=network prtip -sS 192.168.1.1 2> strace.log

# macOS: dtrace
sudo dtruss -n prtip 2> dtruss.log

Memory Profiling

# Use valgrind (Linux)
valgrind --leak-check=full prtip -sS 192.168.1.1

# Use heaptrack
heaptrack prtip -sS 192.168.1.1
heaptrack_gui heaptrack.prtip.*.gz

Performance Profiling

# Linux: perf
sudo perf record --call-graph dwarf prtip -sS 192.168.1.1
sudo perf report

# Flamegraph
cargo install flamegraph
cargo flamegraph -- -sS 192.168.1.1

Getting Help

Before Asking for Help

1. Check this troubleshooting guide
2. Read the documentation in Documentation Index
3. Search existing issues on GitHub Issues
4. Enable debug logging and check output
5. Verify you're using the latest version: prtip --version

Reporting Bugs

Create a GitHub issue with:

## Environment
- ProRT-IP version: [output of `prtip --version`]
- OS: [output of `uname -a` (Linux/macOS) or `ver` (Windows)]
- Rust version: [output of `rustc --version`]
- Installation method: Binary/Source

## Description
[Clear description of the problem]

## Steps to Reproduce
1. Run: `prtip -sS -p 80 192.168.1.1`
2. Expected: [What you expected to happen]
3. Actual: [What actually happened]

## Error Output

[Paste error messages here]

## Debug Log

[Paste RUST_LOG=debug output]

## Additional Context
[Any other relevant information]

Getting Support

• GitHub Issues: https://github.com/doublegate/ProRT-IP/issues
• Documentation: Getting Started
• Security Issues: See SECURITY.md for responsible disclosure

Community Resources

• FAQ: Frequently Asked Questions
• Development Guide: Implementation Details
• Architecture: System Architecture
• Performance: Performance Tuning

Quick Reference

Common Error Messages and Solutions

Performance Optimization Checklist

• Use release build: cargo build --release
• Enable NUMA on multi-socket: --numa
• Adjust parallelism: --parallelism 100
• Use appropriate timing: -T4 for LANs, -T2 for WANs
• Disable unnecessary features: No -sV or -O if not needed
• Stream to disk: -oN results.txt or --with-db
• Scan in batches for large targets
• Increase socket buffers (Linux): sudo sysctl -w net.core.rmem_max=134217728

Platform-Specific Quick Fixes

Linux:

sudo setcap cap_net_raw+ep ./target/release/prtip

Windows:

# Install Npcap from https://npcap.com/
# Run as Administrator

macOS:

brew install --cask wireshark  # Installs ChmodBPF
sudo reboot

See Also

• FAQ - Frequently asked questions
• CLI Reference - Complete command-line reference
• Platform Support - Platform-specific installation
• Performance Tuning - Optimization strategies
• Database Storage - Database troubleshooting