c0de1ndex/netscan repository overview

⁠Netscan

Fast, lightweight network scanner with REST API. Automatically discovers devices on your network using intelligent hybrid scanning: ARP for physical networks, Nmap for VPN/tunnels.

⁠Quick Start

docker run -d \
  --name network-scanner \
  --network host \
  --cap-add NET_ADMIN \
  --cap-add NET_RAW \
  -e API_PORT=8080 \
  c0de1ndex/netscan:latest

Test it:

curl -X POST http://localhost:8080/scan/network
curl http://localhost:8080/scan/results

⁠Features

• Hybrid scanning - ARP for physical networks (fast, MAC addresses), Nmap for VPN/tunnels
• Auto-discovery - Finds all network interfaces including WireGuard, OpenVPN
• Smart filtering - Skips Docker/VM networks automatically
• Performance optimized - Typical scan completes in 20-30 seconds
• REST API - Simple JSON endpoints

⁠Docker Compose

services:
  network-scanner:
    image: c0de1ndex/netscan:latest
    container_name: netscan
    network_mode: host
    cap_add:
      - NET_ADMIN
      - NET_RAW
    restart: unless-stopped
    environment:
      - API_PORT=8080
      - SCAN_COOLDOWN_SECONDS=10

⁠API Endpoints

⁠Configuration

⁠Example Usage

# Health check
curl http://localhost:8080/health

# List discovered interfaces
curl http://localhost:8080/interfaces

# Start scan
curl -X POST http://localhost:8080/scan/network

# Check scan progress
curl http://localhost:8080/scan/status

# Get results
curl http://localhost:8080/scan/results | jq

⁠Scanning Methods

The scanner intelligently selects the best tool for each interface type:

Physical Networks (eth0, wlan0, en0):

• Uses arp-scan for speed (~5 seconds per network)
• Provides: IP addresses, MAC addresses, vendor identification
• Best for: Local network device discovery, identifying devices by manufacturer

VPN/Tunnel Networks (wg0, tun0, tap0):

• Uses nmap for Layer 3 scanning (~8 seconds per network)
• Provides: IP addresses, hostnames, host status
• Required for: VPN interfaces where ARP doesn't work (tunneled traffic)

⁠Why host network mode?

The scanner needs direct access to host network interfaces for ARP scanning. This requires:

• --network host - Access physical network interfaces
• --cap-add NET_ADMIN - Network administration capabilities
• --cap-add NET_RAW - Raw socket access for ARP

⁠Supported Platforms

• linux/amd64
• linux/arm64

⁠Interface Filtering

Automatically excludes:

• Docker networks (docker0, br-*, veth*)
• Virtual machines (virbr*, vmnet*, vboxnet*)
• Loopback (lo)

Automatically includes and scans:

• Physical interfaces (eth*, wlan*, en*) - scanned with arp-scan
• VPN/Tunnel interfaces (wg*, tun*, tap*) - scanned with nmap

Scan specific interfaces only:

docker run -d \
  --network host \
  --cap-add NET_ADMIN \
  --cap-add NET_RAW \
  -e INCLUDE_INTERFACES_ONLY=eth0,wlan0,wg0 \
  c0de1ndex/netscan:latest

⁠Use Cases

• Home network monitoring
• Edge device deployment
• IoT network discovery
• Network inventory automation
• CI/CD network validation
• Multi-site VPN network mapping

⁠Example Responses

⁠Physical Network (with arp-scan)

{
  "status": "success",
  "data": {
    "interfaces": {
      "eth0": {
        "name": "eth0",
        "ipv4": [{"ip": "192.168.1.100", "network": "192.168.1.0/24"}],
        "mac": "aa:bb:cc:dd:ee:ff"
      }
    },
    "arp_scan": {
      "192.168.1.0/24": {
        "interface": "eth0",
        "arp_scan": [
          {
            "ip": "192.168.1.1",
            "mac": "00:11:22:33:44:55",
            "vendor": "TP-Link Corporation Limited"
          },
          {
            "ip": "192.168.1.10",
            "mac": "aa:bb:cc:dd:ee:ff",
            "vendor": "Dell Inc."
          }
        ],
        "nmap_scan": [],
        "timestamp": "2026-01-09T15:30:00Z"
      }
    },
    "last_scan": "2026-01-09T15:30:00Z",
    "scan_duration": 5.2
  }
}

⁠Troubleshooting

No hosts found on VPN interface:

• VPN interfaces use nmap (Layer 3), not arp-scan
• Verify the VPN is connected and routing properly
• Check firewall allows ICMP/ping on the VPN network

Missing MAC addresses on some hosts:

• MAC addresses only available from arp-scan (physical networks)
• Tunnel/VPN interfaces won't show MAC addresses (Layer 3 only)

⁠Security

No built-in authentication - Intended for trusted networks.

For production:

• Use reverse proxy with authentication (nginx/Caddy)
• Restrict access with firewall rules