README.md aktualisiert

This commit is contained in:
2025-10-24 17:12:51 +02:00
parent e186f35533
commit 950e3714d5

531
README.md
View File

@@ -1,3 +1,530 @@
# free-ip-scanner
# Free IP Scanner
Scant in gewählten Netzwerken nach freien IPs
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)
- **Merge Requests:** [https://git.jtl-hosting.de/thomasciesla/free-ip-scanner/-/merge_requests](https://git.jtl-hosting.de/thomasciesla/free-ip-scanner/-/merge_requests)
## 📧 Kontakt
**Autor:** Thomas Ciesla
**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** 🚀