Troubleshooting

Solutions for common issues with NetScan installation and usage.

Command Not Found

Problem: netscan: command not found

# Check if installed
ls -la /usr/local/bin/netscan
ls -la ~/.local/bin/netscan

# Add to PATH if using local install
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Or reinstall
curl -fsSL https://raw.githubusercontent.com/G1A1B1E/NetScan/main/install.sh | bash

Permission Denied

Problem: Scans fail or show incomplete results

# Use sudo for ARP scanning
sudo netscan -s

# Or grant capabilities (Linux)
sudo setcap cap_net_raw+ep $(which python3)

No Devices Found

Problem: Scan returns 0 devices

# Check interface
netscan --interfaces
ip addr show

# Specify correct interface
netscan -s -i en0    # macOS
netscan -s -i eth0   # Linux

# Try with sudo
sudo netscan -s

# Check target network
netscan -s -t 192.168.1.0/24 -v

Python Import Errors

Problem: ModuleNotFoundError: No module named 'requests'

# Install missing packages
pip3 install --user requests netifaces

# Or with system Python
python3 -m pip install requests netifaces

# Check Python version (need 3.7+)
python3 --version

MAC Lookup Fails

Problem: Unknown vendor for valid MAC

# Update OUI database
netscan --update-oui

# Check database exists
ls -la ~/.netscan/data/oui.txt

# Clear cache
rm -rf ~/.netscan/cache/*

Web Interface Won't Start

Problem: Address already in use

# Check what's using the port
lsof -i :8080

# Use different port
netscan -w -p 9000

# Kill existing process
kill $(lsof -t -i :8080)

Slow Scans

Problem: Scans take too long

# Reduce timeout
netscan -s --timeout 2

# Use more threads
netscan -s --threads 100

# Install Rust module
./build_rust.sh

# Scan smaller range
netscan -s -t 192.168.1.1-50

macOS: BSD vs GNU Tools

Problem: Commands behave differently

# Install GNU tools
brew install grep gnu-sed gawk coreutils

# NetScan handles this automatically, but you can force:
export PATH="/usr/local/opt/coreutils/libexec/gnubin:$PATH"

Docker Issues

Problem: Can't scan network from container

# Need host networking and capabilities
docker run --rm \
  --network host \
  --cap-add NET_RAW \
  --cap-add NET_ADMIN \
  netscan -s

Debug Mode

Enable verbose logging to diagnose issues:

# Verbose output
netscan -s -v

# Debug level
NETSCAN_LOG_LEVEL=DEBUG netscan -s

# Log to file
netscan -s --log-file debug.log

Still Need Help?