thomasciesla/free-ip-scanner

Fork 0

Go to file

thomasciesla ed270c20bb ip-scanner.py aktualisiert

2025-11-26 10:00:45 +01:00

ip-scanner.py

ip-scanner.py aktualisiert

2025-11-26 10:00:45 +01:00

README.md

README.md aktualisiert

2025-10-24 17:17:01 +02:00

README.md

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.

✨ 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:

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

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

2. Script ausführbar machen

chmod +x ip-scanner.py

3. Optionale Tools installieren

# 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

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

Einfachstes Beispiel

sudo ./ip-scanner.py 192.168.1.0/24

Typischer JTL-Hosting Anwendungsfall

# 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) 🏆

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) ⚡

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) 🔄

./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) 🎯

sudo ./ip-scanner.py 10.150.8.0/24

Funktionsweise:

Prüft ob arp-scan verfügbar → verwendet ARP-Scan
Falls nicht: Prüft ob nmap verfügbar → verwendet Nmap
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

./ip-scanner.py --help

💡 Beispiele

Basis-Beispiele

Einzelnes Netzwerk scannen

sudo ./ip-scanner.py 192.168.1.0/24

Mehrere Netzwerke gleichzeitig scannen

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)

sudo ./ip-scanner.py 192.168.1.0/24 -a

Nur belegte IPs anzeigen

sudo ./ip-scanner.py 192.168.1.0/24 --no-free

Erweiterte Beispiele

ARP-Scan mit spezifischem Interface

sudo ./ip-scanner.py 10.150.8.0/24 --method arp-scan --interface vmbr0

Aggressiver Nmap-Scan mit Port-Scanning

sudo ./ip-scanner.py 10.0.0.0/24 --method nmap --aggressive

Schneller Scan mit vielen Threads

./ip-scanner.py 192.168.0.0/24 --threads 200

Custom TCP-Ports prüfen (z.B. für Plesk, Proxmox)

./ip-scanner.py 10.0.0.0/24 --ports 22,80,443,8006,8080,8443,9090

Debug-Modus für Troubleshooting

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

JTL-Hosting Produktions-Beispiele

Vollständiger Scan der Proxmox VLANs

# 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

# 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

# /16 Netzwerk mit vielen Threads
sudo ./ip-scanner.py 10.0.0.0/16 --threads 500 --method nmap

Nur belegte IPs für Dokumentation

# 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

# ✅ 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:

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

3. Debug-Modus bei Problemen

Wenn Scans nicht die erwarteten Ergebnisse liefern:

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

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:

# 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:

# /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)

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

Lösung 2: Interface manuell angeben

# 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

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:

Zu wenig Threads

./ip-scanner.py 10.0.0.0/24 --threads 200

Aggressive Nmap-Scans

# Entferne --aggressive Flag
sudo ./ip-scanner.py 10.0.0.0/24 --method nmap

Sehr große Netzwerke

# 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:

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:

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

ARP-Scan bevorzugen - Schnellste und zuverlässigste Methode
Threads erhöhen bei großen Netzwerken
Netzwerke aufteilen bei sehr großen Bereichen
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
Pull Requests: 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

🔄 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 🚀