Installation

Get NetScan up and running in minutes. Choose between the Desktop GUI or CLI installation.

Desktop GUI (Recommended)

Download the pre-built installer for your platform:

macOS

Full Installer (GUI + CLI) NetScan-3.0.0-Installer.pkg
GUI Only (Intel) NetScan-3.0.0.dmg
GUI Only (Apple Silicon) NetScan-3.0.0-arm64.dmg
CLI Only NetScan-CLI-3.0.0.pkg

Windows

Installer NetScan-3.0.0-Setup.exe
Portable (no install) NetScan-3.0.0-Windows.zip

CLI Installation (Script)

Install the CLI tools using our install script, which automatically handles dependencies:

Global Installation (System-wide)

Requires sudo for installing to /usr/local/bin:

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

Local Installation (User only)

No sudo required. Installs to ~/.local/bin:

bash 
bash <(curl -fsSL https://raw.githubusercontent.com/G1A1B1E/NetScan/main/install.sh) --local
What the installer does:
  • Clones the NetScan repository to ~/.netscan
  • Installs system dependencies (nmap, python3, etc.)
  • Installs Python packages (requests, netifaces)
  • Creates the netscan command
  • Sets up directory structure

macOS Installation

Prerequisites

Install Homebrew if you haven't already:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Dependencies

# Required
brew install python@3 nmap

# Optional (for enhanced features)
brew install arp-scan grep gnu-sed gawk

Install NetScan

# Clone repository
git clone https://github.com/G1A1B1E/NetScan.git ~/.netscan
cd ~/.netscan

# Run installer
./install.sh --local

Add to PATH

If using --local, add this to your ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

Then reload your shell:

source ~/.zshrc

Linux Installation

Ubuntu / Debian

# Install dependencies
sudo apt update
sudo apt install -y python3 python3-pip nmap arp-scan git

# Install Python packages
pip3 install --user requests netifaces

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

Fedora / RHEL / CentOS

# Install dependencies
sudo dnf install -y python3 python3-pip nmap arp-scan git

# Install Python packages
pip3 install --user requests netifaces

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

Arch Linux

# Install dependencies
sudo pacman -S python python-pip nmap arp-scan git

# Install Python packages
pip install --user requests netifaces

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

Docker Installation

Run NetScan in a container with all dependencies included:

Using Docker

# Clone and build
git clone https://github.com/G1A1B1E/NetScan.git
cd NetScan
docker build -t netscan .

# Run interactive
docker run -it --rm --network host --cap-add NET_RAW netscan

# MAC lookup (no special permissions needed)
docker run --rm netscan -l 00:11:22:33:44:55

Using Docker Compose

# Start NetScan
docker compose up -d

# Attach to container
docker attach netscan

# Start with web interface
docker compose --profile web up -d

Using the Helper Script

# Build image
./docker.sh build

# Run commands
./docker.sh run              # Interactive menu
./docker.sh scan 192.168.1.0/24   # Network scan
./docker.sh lookup 00:11:22:33:44:55  # MAC lookup
./docker.sh web              # Start web interface
⚠️ Network Scanning in Docker:

For network scanning to work, you need:

  • --network host to see local network
  • --cap-add NET_RAW for ping/arp operations
  • --cap-add NET_ADMIN for interface operations

Manual Installation

For complete control over the installation process:

1. Clone the Repository

git clone https://github.com/G1A1B1E/NetScan.git ~/.netscan
cd ~/.netscan

2. Install Python Dependencies

# Required
pip3 install --user requests netifaces

# Optional (for reports, charts, advanced scanning)
pip3 install --user reportlab matplotlib scapy python-nmap

3. Create Directories

mkdir -p ~/.netscan/{cache,logs,exports,reports,data}

4. Set Permissions

chmod +x ~/.netscan/netscan
find ~/.netscan/lib -name "*.sh" -exec chmod +x {} \;
find ~/.netscan/helpers -name "*.py" -exec chmod +x {} \;

5. Create Symlink

# Global (requires sudo)
sudo ln -sf ~/.netscan/netscan /usr/local/bin/netscan

# Or local (add ~/.local/bin to PATH)
mkdir -p ~/.local/bin
ln -sf ~/.netscan/netscan ~/.local/bin/netscan

Performance Module (Optional)

For 10-100x faster performance on large networks, compile the Rust module:

1. Install Rust

# macOS/Linux
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Or with Homebrew
brew install rust

2. Install maturin

pip3 install maturin

3. Build the Module

cd ~/.netscan
./build_rust.sh

Verify Installation

python3 ~/.netscan/helpers/fast_core.py
# Should show: ✓ Using Rust backend (10-100x faster)

Verify Installation

After installation, verify everything is working:

# Check version
netscan --version

# Show help
netscan --help

# Test MAC lookup
netscan -l 00:11:22:33:44:55

# Launch interactive menu
netscan

Expected output for MAC lookup:

MAC Address: 00:11:22:33:44:55
Vendor: CIMSYS Inc

Uninstall

To remove NetScan from your system:

# Using the installer
~/.netscan/install.sh --uninstall

# Or manually
sudo rm -f /usr/local/bin/netscan
rm -f ~/.local/bin/netscan
rm -rf ~/.netscan

Troubleshooting

Command not found

If netscan is not found after installation:

# Check if the symlink exists
ls -la /usr/local/bin/netscan
ls -la ~/.local/bin/netscan

# Make sure ~/.local/bin is in your PATH
echo $PATH | grep -o '.local/bin'

# Add to PATH if needed (in ~/.zshrc or ~/.bashrc)
export PATH="$HOME/.local/bin:$PATH"

Permission denied

If you get permission errors during network scanning:

# Some operations require elevated privileges
sudo netscan -s

# Or use nmap with sudo
sudo nmap -sn 192.168.1.0/24

Python errors

If you encounter Python import errors:

# Reinstall Python packages
pip3 install --user --upgrade requests netifaces

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

macOS: BSD vs GNU tools

NetScan works best with GNU tools on macOS:

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

# The install script handles this automatically