# Free IP Scanner

Ein leistungsstarker, zuverlässiger Netzwerk-Scanner zur Identifizierung von belegten und freien IP-Adressen in lokalen Netzwerken. Entwickelt für Proxmox-Umgebungen und komplexe Netzwerk-Setups mit mehreren VLANs bei JTL-Software.

[![Python](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## 📋 Inhaltsverzeichnis

- [Features](#-features)
- [Voraussetzungen](#-voraussetzungen)
- [Installation](#-installation)
- [Verwendung](#-verwendung)
- [Scan-Methoden](#-scan-methoden)
- [Argumente und Optionen](#-argumente-und-optionen)
- [Beispiele](#-beispiele)
- [Gemeinsame freie Host-IDs](#-gemeinsame-freie-host-ids)
- [Best Practices](#-best-practices)
- [Troubleshooting](#-troubleshooting)
- [Performance](#-performance-hinweise)

## ✨ Features

- **🔍 Mehrschichtige Erkennung**: Kombiniert ARP-Scan, Nmap und TCP-Port-Checks für 100% Zuverlässigkeit
- **🏷️ Hostname-Auflösung**: Zeigt automatisch Hostnamen für erkannte IPs an
- **📱 MAC-Adressen**: Erfasst MAC-Adressen bei ARP-Scans
- **🌐 Multi-Netzwerk Support**: Scannt mehrere Netzwerke gleichzeitig
- **🔗 Gemeinsame freie IPs**: Findet Host-IDs, die in allen Netzwerken frei sind (ideal für Multi-Interface VMs)
- **⚙️ Automatische Interface-Erkennung**: Findet das richtige Netzwerk-Interface für ARP-Scans
- **⚡ Parallele Scans**: Multithreading für schnelle Ergebnisse
- **🎨 Farbige Ausgabe**: Übersichtliche, farbcodierte Darstellung
- **📊 Progress-Bar**: Echtzeit-Fortschrittsanzeige bei umfangreichen Scans

## 🔧 Voraussetzungen

### Basis-Anforderungen

- **Python 3.6+** (standardmäßig auf Debian/Ubuntu installiert)
- **Root/Sudo-Rechte** (für ARP-Scan und aggressive Nmap-Scans)

### Empfohlene Tools

Für beste Ergebnisse sollten folgende Tools installiert sein:

```bash
apt update
apt install -y arp-scan nmap
```

**Ohne zusätzliche Tools:**
- Das Script funktioniert auch nur mit Ping und TCP-Port-Checks
- Die Zuverlässigkeit ist dann jedoch eingeschränkt

## 📦 Installation

### 1. Repository klonen

```bash
git clone https://git.jtl-hosting.de/thomasciesla/free-ip-scanner.git
cd free-ip-scanner
```

### 2. Script ausführbar machen

```bash
chmod +x ip-scanner.py
```

### 3. Optionale Tools installieren

```bash
# Für maximale Zuverlässigkeit
sudo apt install arp-scan nmap

# Prüfen ob Installation erfolgreich war
arp-scan --version
nmap --version
```

## 🚀 Verwendung

### Grundlegende Syntax

```bash
sudo ./ip-scanner.py <NETZWERK1> [NETZWERK2] [NETZWERK3] [OPTIONEN]
```

### Einfachstes Beispiel

```bash
sudo ./ip-scanner.py 192.168.1.0/24
```

### Typischer JTL-Hosting Anwendungsfall

```bash
# Zwei VLANs scannen
sudo ./ip-scanner.py 10.150.8.0/24 10.150.56.0/24 --method arp-scan
```

## 🔍 Scan-Methoden

Das Script unterstützt vier verschiedene Scan-Methoden:

### 1. **ARP-Scan** (Empfohlen) 🏆

```bash
sudo ./ip-scanner.py 10.150.8.0/24 --method arp-scan
```

**Vorteile:**
- ✅ Arbeitet auf Layer 2 (Ethernet-Ebene)
- ✅ Kann nicht blockiert werden (im Gegensatz zu ICMP/TCP)
- ✅ Erkennt ALLE Geräte im lokalen Netzwerk
- ✅ Findet auch Firewalls, Gateways und Geräte mit deaktiviertem Ping
- ✅ Liefert MAC-Adressen

**Nachteile:**
- ⚠️ Benötigt Root-Rechte
- ⚠️ Funktioniert nur im lokalen Netzwerk (nicht über Router hinweg)

**Wann verwenden:**
- Immer wenn möglich (höchste Zuverlässigkeit)
- Besonders wichtig für vollständige Inventarisierung
- Bei Proxmox-Umgebungen mit VLANs

### 2. **Nmap** (Sehr gut) ⚡

```bash
sudo ./ip-scanner.py 10.150.8.0/24 --method nmap
```

**Vorteile:**
- ✅ Sehr zuverlässig durch multiple Probe-Methoden
- ✅ Kombiniert ICMP, TCP SYN/ACK, UDP Pings
- ✅ Findet die meisten Hosts, auch mit Firewall

**Nachteile:**
- ⚠️ Langsamer als ARP-Scan
- ⚠️ Kann durch aggressive Firewalls teilweise blockiert werden

**Wann verwenden:**
- Wenn ARP-Scan nicht verfügbar ist
- Für Remote-Netzwerke
- Mit `--aggressive` Flag für Port-Scanning

### 3. **Comprehensive** (Fallback) 🔄

```bash
./ip-scanner.py 10.150.8.0/24 --method comprehensive
```

**Vorteile:**
- ✅ Benötigt keine zusätzlichen Tools
- ✅ Kombiniert Ping + TCP-Port-Checks
- ✅ Funktioniert ohne Root-Rechte

**Nachteile:**
- ⚠️ Weniger zuverlässig als ARP-Scan oder Nmap
- ⚠️ Kann Hosts übersehen, die ICMP und gängige Ports blockieren
- ⚠️ Langsamer bei großen Netzwerken

**Wann verwenden:**
- Als Fallback wenn ARP-Scan und Nmap nicht verfügbar sind
- Für schnelle Checks ohne Installation zusätzlicher Tools

### 4. **Auto** (Standard) 🎯

```bash
sudo ./ip-scanner.py 10.150.8.0/24
```

**Funktionsweise:**
1. Prüft ob `arp-scan` verfügbar → verwendet ARP-Scan
2. Falls nicht: Prüft ob `nmap` verfügbar → verwendet Nmap
3. Falls nicht: Verwendet Comprehensive-Methode

**Wann verwenden:**
- Für die meisten Anwendungsfälle
- Wenn du nicht sicher bist, welche Methode am besten ist

## 📚 Argumente und Optionen

### Positionsargumente

| Argument | Beschreibung | Beispiel |
|----------|--------------|----------|
| `networks` | Ein oder mehrere Netzwerke im CIDR-Format | `192.168.0.0/24 10.0.0.0/24` |

### Scan-Optionen

| Argument | Kurzform | Standard | Beschreibung |
|----------|----------|----------|--------------|
| `--method` | `-m` | `auto` | Scan-Methode: `auto`, `arp-scan`, `nmap`, `comprehensive` |
| `--threads` | `-t` | `100` | Anzahl paralleler Threads für Ping/TCP-Scan |
| `--ports` | `-p` | `22,80,443,3389,8080,8443,3306,5432` | Kommagetrennte Liste von TCP-Ports für Port-Check |
| `--aggressive` | - | `False` | Aktiviert aggressiven Nmap-Scan mit Port-Scanning |
| `--interface` | `-i` | auto | Netzwerk-Interface für ARP-Scan (z.B. `vmbr0`, `eth0`) |

### Ausgabe-Optionen

| Argument | Kurzform | Standard | Beschreibung |
|----------|----------|----------|--------------|
| `--show-all` | `-a` | `False` | Zeigt alle IPs auch bei großen Listen (keine Kürzung) |
| `--no-free` | - | `False` | Zeigt keine freien IPs an (nur belegte) |
| `--debug` | - | `False` | Aktiviert Debug-Modus mit detaillierter Ausgabe |

### Hilfe

```bash
./ip-scanner.py --help
```

## 💡 Beispiele

### Basis-Beispiele

#### Einzelnes Netzwerk scannen
```bash
sudo ./ip-scanner.py 192.168.1.0/24
```

#### Mehrere Netzwerke gleichzeitig scannen
```bash
sudo ./ip-scanner.py 10.150.8.0/24 10.150.56.0/24 172.16.0.0/24
```

#### Alle IPs anzeigen (keine Kürzung)
```bash
sudo ./ip-scanner.py 192.168.1.0/24 -a
```

#### Nur belegte IPs anzeigen
```bash
sudo ./ip-scanner.py 192.168.1.0/24 --no-free
```

### Erweiterte Beispiele

#### ARP-Scan mit spezifischem Interface
```bash
sudo ./ip-scanner.py 10.150.8.0/24 --method arp-scan --interface vmbr0
```

#### Aggressiver Nmap-Scan mit Port-Scanning
```bash
sudo ./ip-scanner.py 10.0.0.0/24 --method nmap --aggressive
```

#### Schneller Scan mit vielen Threads
```bash
./ip-scanner.py 192.168.0.0/24 --threads 200
```

#### Custom TCP-Ports prüfen (z.B. für Plesk, Proxmox)
```bash
./ip-scanner.py 10.0.0.0/24 --ports 22,80,443,8006,8080,8443,9090
```

#### Debug-Modus für Troubleshooting
```bash
sudo ./ip-scanner.py 10.150.8.0/24 --method arp-scan --debug
```

### JTL-Hosting Produktions-Beispiele

#### Vollständiger Scan der Proxmox VLANs
```bash
# Scannt zwei VLANs mit ARP für maximale Zuverlässigkeit
sudo ./ip-scanner.py 10.150.8.0/24 10.150.56.0/24 --method arp-scan -a
```

#### Schneller Check vor VM-Deployment
```bash
# Findet gemeinsame freie IPs für Multi-Interface VM
sudo ./ip-scanner.py 10.150.8.0/24 10.150.56.0/24 10.150.100.0/24
```

#### Großes Netzwerk scannen
```bash
# /16 Netzwerk mit vielen Threads
sudo ./ip-scanner.py 10.0.0.0/16 --threads 500 --method nmap
```

#### Nur belegte IPs für Dokumentation
```bash
# Export für IP-Übersicht
sudo ./ip-scanner.py 10.150.8.0/24 --no-free > ip-report.txt
```

## 🔗 Gemeinsame freie Host-IDs

### Was ist das?

Bei Multi-Interface Setups (z.B. VMs mit mehreren Netzwerkkarten) ist es praktisch, wenn die letzte Oktett-Zahl (Host-ID) in allen Netzwerken identisch ist.

**Beispiel für eine VM mit 3 Interfaces:**
- Interface 1 (Management): `10.150.8.123`
- Interface 2 (Storage): `10.150.56.123`
- Interface 3 (Public): `10.150.100.123`

### Ausgabe-Format

Wenn du mehrere Netzwerke scannst, zeigt das Script automatisch eine zusätzliche Tabelle:

```
╔═══ Gemeinsam freie Host-IDs ═══╗
  Netzwerke: 10.150.8.0/24, 10.150.56.0/24
  Anzahl gemeinsam frei: 189

  Host-ID  │ 10.150.8        │ 10.150.56       
  ─────────────────────────────────────────────
    3      │ 10.150.8.3      │ 10.150.56.3     
    4      │ 10.150.8.4      │ 10.150.56.4     
    5      │ 10.150.8.5      │ 10.150.56.5     
    ...

💡 Tipp: Für eine VM mit mehreren Interfaces kannst du z.B. verwenden:
   Interface 1: 10.150.8.3
   Interface 2: 10.150.56.3
```

### Verwendung

Diese Funktion ist besonders nützlich für:
- **Proxmox VMs** mit mehreren VLANs
- **JTL-Shop Server** mit Management- und Public-Netzwerk
- **Cluster-Setups** mit Management-, Storage- und Public-Netzwerken
- **Einfachere Verwaltung** durch konsistente IP-Endungen

## 🎯 Best Practices

### 1. Immer mit Root-Rechten bei ARP-Scan

```bash
# ✅ Richtig
sudo ./ip-scanner.py 10.150.8.0/24 --method arp-scan

# ❌ Falsch (arp-scan funktioniert nicht ohne sudo)
./ip-scanner.py 10.150.8.0/24 --method arp-scan
```

### 2. Verwende ARP-Scan für maximale Zuverlässigkeit

ARP-Scan ist die zuverlässigste Methode und sollte immer bevorzugt werden:

```bash
sudo ./ip-scanner.py 10.150.8.0/24 --method arp-scan
```

### 3. Debug-Modus bei Problemen

Wenn Scans nicht die erwarteten Ergebnisse liefern:

```bash
sudo ./ip-scanner.py 10.150.8.0/24 --method arp-scan --debug
```

### 4. Passende Thread-Anzahl wählen

- **Kleine Netzwerke (/24)**: 50-100 Threads ausreichend
- **Mittlere Netzwerke (/22-/20)**: 100-200 Threads
- **Große Netzwerke (/16)**: 200-500 Threads

```bash
sudo ./ip-scanner.py 10.0.0.0/16 --threads 300
```

### 5. Aggressive Scans nur wenn nötig

Der aggressive Modus ist langsamer, aber zuverlässiger:

```bash
# Nur wenn normale Scans nicht ausreichen
sudo ./ip-scanner.py 10.0.0.0/24 --method nmap --aggressive
```

### 6. Regelmäßige Scans in Cron-Jobs

Für automatische Überwachung:

```bash
# /etc/cron.daily/network-scan
#!/bin/bash
/opt/free-ip-scanner/ip-scanner.py 10.150.8.0/24 10.150.56.0/24 \
  --method arp-scan --no-free > /var/log/ip-scan-$(date +%Y%m%d).log
```

## 🔧 Troubleshooting

### Problem: "ioctl: No such device"

**Ursache:** ARP-Scan findet das Netzwerk-Interface nicht.

**Lösung 1:** Automatische Erkennung nutzen (sollte funktionieren)
```bash
sudo ./ip-scanner.py 10.150.8.0/24 --method arp-scan
```

**Lösung 2:** Interface manuell angeben
```bash
# Zeige alle Interfaces
ip addr show

# Verwende das richtige Interface (z.B. vmbr0 bei Proxmox)
sudo ./ip-scanner.py 10.150.8.0/24 --method arp-scan --interface vmbr0
```

### Problem: IPs werden nicht erkannt (Firewall)

**Ursache:** Geräte blockieren ICMP-Ping und TCP-Ports.

**Lösung:** Verwende ARP-Scan statt Ping/Nmap
```bash
sudo ./ip-scanner.py 10.150.8.0/24 --method arp-scan
```

ARP-Scan funktioniert auch bei:
- OPNsense/pfSense Gateways (.254)
- Firewalled VMs
- Systemen mit deaktiviertem ICMP

### Problem: Scan ist sehr langsam

**Ursachen & Lösungen:**

1. **Zu wenig Threads**
   ```bash
   ./ip-scanner.py 10.0.0.0/24 --threads 200
   ```

2. **Aggressive Nmap-Scans**
   ```bash
   # Entferne --aggressive Flag
   sudo ./ip-scanner.py 10.0.0.0/24 --method nmap
   ```

3. **Sehr große Netzwerke**
   ```bash
   # Teile in kleinere Subnets auf
   sudo ./ip-scanner.py 10.0.0.0/25 10.0.0.128/25
   ```

### Problem: "Permission denied"

**Ursache:** Fehlende Root-Rechte für ARP-Scan oder Nmap.

**Lösung:**
```bash
sudo ./ip-scanner.py 10.150.8.0/24 --method arp-scan
```

### Problem: Keine gemeinsamen freien IPs gefunden

**Ursache:** Alle Host-IDs sind in mindestens einem Netzwerk belegt.

**Lösung:** Scanne mit `-a` um alle IPs zu sehen und manuell zu vergleichen:
```bash
sudo ./ip-scanner.py 10.150.8.0/24 10.150.56.0/24 -a
```

## 📊 Performance-Hinweise

### Scan-Zeiten (Richtwerte auf Proxmox)

| Netzwerk-Größe | Methode | Threads | Durchschnittliche Zeit |
|----------------|---------|---------|------------------------|
| /24 (254 IPs) | ARP-Scan | - | 2-5 Sekunden |
| /24 (254 IPs) | Nmap | - | 5-10 Sekunden |
| /24 (254 IPs) | Comprehensive | 100 | 10-15 Sekunden |
| /22 (1022 IPs) | ARP-Scan | - | 10-20 Sekunden |
| /22 (1022 IPs) | Nmap | - | 30-60 Sekunden |
| /16 (65534 IPs) | Comprehensive | 500 | 15-30 Minuten |

### Optimierungs-Tipps

1. **ARP-Scan bevorzugen** - Schnellste und zuverlässigste Methode
2. **Threads erhöhen** bei großen Netzwerken
3. **Netzwerke aufteilen** bei sehr großen Bereichen
4. **Lokale Ausführung** direkt auf dem Proxmox-Host

## 🔐 Sicherheitshinweise

- **Root-Rechte:** Das Script benötigt Root-Rechte für ARP-Scan und aggressive Nmap-Scans
- **Netzwerk-Scanning:** Stelle sicher, dass du die Berechtigung hast, das Netzwerk zu scannen
- **Logging:** In Produktionsumgebungen können Scans in Firewall-Logs auftauchen
- **Rate-Limiting:** Manche Systeme könnten aggressive Scans als Angriff interpretieren
- **Interne Verwendung:** Dieses Tool ist für die interne Netzwerk-Verwaltung gedacht

## 📝 Lizenz

Dieses Projekt steht unter der MIT-Lizenz. Du kannst es frei verwenden, modifizieren und verteilen.

## 🤝 Beitragen

Verbesserungsvorschläge und Bug-Reports sind willkommen! 

- **Issues:** [https://git.jtl-hosting.de/thomasciesla/free-ip-scanner/issues](https://git.jtl-hosting.de/thomasciesla/free-ip-scanner/issues)
- **Pull Requests:** [https://git.jtl-hosting.de/thomasciesla/free-ip-scanner/pulls](https://git.jtl-hosting.de/thomasciesla/free-ip-scanner/pulls)

## 📧 Kontakt

**Autor:** Thomas Ciesla  
**E-Mail:** thomas.ciesla@jtl-software.com  
**Teams:** thomas.ciesla@jtl-software.com  
**Organisation:** JTL-Software  
**Repository:** [https://git.jtl-hosting.de/thomasciesla/free-ip-scanner](https://git.jtl-hosting.de/thomasciesla/free-ip-scanner)

## 🔄 Changelog

### Version 3.0 (2025-10-24)
- ✨ Automatische Interface-Erkennung für ARP-Scan
- ✨ Gemeinsame freie Host-IDs für Multi-Interface VMs
- ✨ Verbesserte Hostname-Auflösung
- ✨ Debug-Modus hinzugefügt
- 🐛 Besseres Error-Handling
- 🐛 Korrekte Berechnung freier IPs
- 📝 Ausführliche Dokumentation

### Version 2.0
- ✨ Mehrschichtige Scan-Methoden
- ✨ TCP-Port-Checks für Firewall-Umgehung
- ✨ MAC-Adressen-Erfassung
- ✨ Multi-Netzwerk Support

### Version 1.0
- 🎉 Initiale Version
- ✨ Basis-Funktionalität mit Ping-Scans

---

**Entwickelt für JTL-Software Proxmox-Umgebungen und professionelle Netzwerk-Verwaltung** 🚀