Nmap Modul by SimonS

Version Version Version

Das Symcon Nmap Modul scannt das Netzwerk und stellt vorhandene Hosts in HTML-Tabellen im WebFront dar.
Das Modul verwendet das Open Source Programm "Network Mapper". (www.nmap.org)

📝 Inhaltsverzeichnis

🧐 Funktionsumfang

  • Das Nmap Modul scannt das Netzwerk und stellt gefundene Hosts in HTML-Tabellen im WebFront dar
  • Möglichkeit der Benachrichtigung bei "Neuer Host im Netzwerk" (Mail, WebFront, Skript für Telegram usw..)
  • Möglichkeit der Benachrichtigung und erweiterte Checks per "Benutzerdefiniertes Script"
  • Einfaches ICMP/PING Netzwerk Monitoring per "Benutzerdefiniertes Script". (Hat den Vorteil nicht für jeden Host eine eigene Instanz zu benötigen)
  • Möglichkeit die Ausführung von nmap auf einem "Remote Host" zu starten (nützlich bei vLANs, oder um andere Subnet-Bereiche zu scannen)
  • Möglichkeit 3 Variablen mit Hostanzahl erstellen zu lassen (Gesamt/Online/Offline). Für Archivierung und Logging.

Übersicht der 3 Ausgabe Tabellen

1. Info Tabelle:

  • IPs Gesamt: Zeigt an wieviele IP-Adressen das Netzwerk umfasst
  • Online: Zeigt die Hosts an die "Online" sind
  • Letzter Scan: Zeigt die Uhrzeit des zuletzt gestarteten Nmap Scan an
  • Behalte Offline Hosts: Zeigt an nach wieviel Tagen Hosts mit dem Status "Offline" entfernt werden
  • Timer: Hier wird die Moduleinstellung "Automatischer Scan alle x Minuten" angezeigt
  • Laufzeit: Wie lange hat der letzte Nmap Scan gedauert
  • Ergebnis: Den Status der von Nmap zurückgegeben wurde

2. Hosts Tabelle:

  • Status: Online/Offline (es werden hier jedoch nur IP-Adressen angezeigt die einmal Online waren)
  • IP: IP-Adresse des Hosts
  • Hostname: Dieser Name wird per DNS ermittelt (in den Moduleinstellungen kann FQDN deaktiviert werden)
  • MAC: Die ermittelte MAC Adresse des Hosts
  • Vendor: Nicht alle Geräte liefern die Vendor Bezeichnung aus
  • Zuletzt Online: selbst erklärend

3. Historie Tabelle:

  • Zeit: Jahr.Monat.Tag - Stunde:Minute:Sekunde
  • IPs Gesamt: Zeigt an wieviele IP-Adressen das gewählte Subnet umfasst
  • Hosts Gesamt: Zeigt die Gesamtanzahl der gefundenen Hosts im gewählten Subnet
  • Online, wieviele Hosts davon sind Online
  • Offline, wieviele Hosts davon sind Offline
  • Laufzeit: Wie lange hat der dieser Nmap Scan gedauert
  • Ergebnis: Der Status den Nmap zurückgegeben hat

👓 Screenshots:

Nmap Tabelle: Info
Screenshot

Nmap Tabelle: Hosts
Screenshot

Nmap Tabelle: Historie
Screenshot

🏁 Systemanforderungen

  • IP-Symcon ab Version 5.2
  • Symon-Variablenverbauch: 3 bis 7 Variablen (pro Modul-Instanz)
  • Dieses Modul kann nur auf "Linux" genutzt werden (keine Windows Unterstützung!)
  • Installiertes nmap Paket (local oder remote)
  • Bei "Execute auf Remotehost", werden weitere Pakete benötigt, siehe im Abschnitt "Installation"

🔧 Installation

1. Modul in Symcon installieren

Das Modul in IP-Symcon einbinden (nur für freigeschaltete Benutzer):

  1. In der Symcon Console unter "Kern Instanzen" die "Module Control" Instanz öffnen
  2. Auf "Hinzufügen" klicken und die Modul GIT-URL eintragen: 
    https://GITLAB-BENUTZER:GITLAB-PASSWORT@gitlab.com/SG-IPS-Module/Private/Nmap.git
  3. Nun kann im IPS-Objektbaum (an beliebiger Stelle) eine neue Modul-Instanz hinzufügt werden

2a. nmap - Execute LOKAL (/usr/bin/nmap)

Falls nmap auf dem lokalen (Symcon) Linux System gestartet werden soll.

  1. Installation des nmap Paketes am Symcon System, Consolenbefehl für Debian basierenden Disitributionen ist: 
    apt install nmap
  2. Nun testen wir im Symcon Nmap Modul per Button "TEST EXECUTE" den Aufruf von nmap. Es muss die Ausgabe der nmap Versionsinformationen in einem Popup erscheinen. Falls dies nicht der Fall ist stimmt entweder der Pfad nicht, oder es liegt Berechtigungsproblem vor.

Bei Debian basierenden Disitributionen ist der Pfad zur Nmap Binary: "/usr/bin/nmap".
Falls es sich um eine andere Dustribution handelt kann der Pfad einer Linux Binary mit folgenden Befehl ausgegeben werden:

which nmap

2b. nmap - Execute REMOTE (ssh user@host -t /usr/bin/nmap)

Falls nmap auf dem Remote Linux System gestartet werden soll.

  1. Installation benötigter Pakete am lokalen (Symcon) Host: 
    apt install openssh-client
  2. Installation benötigter Pakete am Remote Host: 
    apt install nmap openssh-server openssh-sftp-server
  3. Nach der Installation der Pakete geht es im nächsten Schritt um die SSH-Anmeldung am Remotehost ohne Kennworteingabe, Stichwort: Public Key Authentifizierung.

Public Key Authentifizierung einrichten

Im Normalfall reicht es aus per Befehl [ssh-copy-id] den Key auf das Zielsystem (wo nmap ausgeführt werden soll) zu übertragen. Dieses kleine Beispiel hier stellt nur eine kurze Beschreibung dar, weitere Informationen sind zB. auf der Ubuntu Wikipage zu finden. https://wiki.ubuntuusers.de/SSH/#PubKeys

Beispiel: Nmap soll auf dem Host "px4" ausgeführt werden, dort soll das Netzwerk 10.8.8.0/24 gescannt werden. Als Benutzerbeispiel gilt hier "meinuser", kann jedoch auch "root" oder ein Benutzer mit Standardrechten sein.

  1. Kopieren des Keys auf die Zielmaschine px4 
    ssh-copy-id meinuser@px4
  2. Erster Login auf das Zielsystem, wo später nmap gestartet werden soll 
    ssh px4
  3. Wenn wir erfolgreich am Zielsystem angemeldet sind, installieren wir gleich das benötigte Paket: nmap 
    apt install nmap
  4. Wie melden uns am Zielsystem wieder ab 
    exit
  5. Nun versuchen wir nochmal den Login auf der Zielmaschine, wichtig ist das nun keine Kennwortaufforderung mehr erscheint !! 
    ssh meinuser@px4
  6. Wenn der Login ohne Kennwort funktioniert hat können wir nun im Symcon Nmap Modul als Execute folgendes eintragen: 
    ssh meinuser@px4 -t /usr/bin/nmap
  7. Testaufruf in IP-Symcon Nun testen wir im Symcon Nmap Modul per Button "TEST EXECUTE" den Aufruf von nmap.
    Hier muss die Ausgabe der nmap Versionsinformationen in einem Popup erscheinen.
    Falls dies nicht der Fall ist, funktioniert entweder der Remotelogin nicht, oder es liegt Berechtigungsproblem vor.

⛏️ Befehlsreferenz

In der Modul-Instanz können folgende Einstellungen vorgenommen werden

  • Allgemein: Modulname automatisch setzen (Der Name setzt sich zusammen aus dem String "Nmap " und dem "Subnet")
  • Allgemein: Pfad zu nmap (/usr/bin/nmap)
  • Allgemein: Subnet, das zu scannende Netzwerk, üblicherweise 192.168.8.0/24 (CIDR-Format!)
  • Allgemein: 3 Variablen mit Hostanzahl erstellen (Gesamt/Online/Offline) -> Für Archivierung
  • Timer: Automatischer Scan alle x Minuten
  • Timer: Offline Hosts werden nach x Tagen entfernen
  • HTML-Tabelle: Tabelle mit Scan Informationen erstellen
  • HTML-Tabelle: Tabelle mit Hosts erstellen
  • HTML-Tabelle: Tabelle mit Historie erstellen, und Anzahl der Historie Datensätze (0=unlimitiert)
  • HTML-Tabelle: FQDN Hostnamen verwenden (entfernt den Domainteil aus dem Hostnamen)
  • HTML-Tabelle: Tabelle nach IP sortieren (Details siehe FAQ!)
  • HTML-Tabelle: Kleine Schrift für mobile Geräte (nur im Hochkant-Modus: 8px !)
  • HTML-Tabelle: Schriftfarbe
  • HTML-Tabelle: Hintergrundfarbe
  • HTML-Tabelle: Hintergrundfarbe für Geräte die Online sind
  • HTML-Tabelle: Hintergrundfarbe für Geräte die Offline sind
  • HTML-Tabelle: Schriftgrösse
  • HTML-Tabelle: Begrenzung der Textlänge VENDOR (0=Deaktiviert)
  • HTML-Tabelle: Zellenabstand Allgemein und Zellenabstand Rechts
  • Benachrichtigung: (Neuer Host): WebFront Instanz
  • Benachrichtigung: (Neuer Host): Push Instanz
  • Benachrichtigung: (Neuer Host): SMTP Instanz
  • Benachrichtigung: (Eigenes Skript): Erweiterte Benachrichtigungen (Online, Offline, MAC prüfen, Vendor usw..)
  • Benachrichtigung: Optional Wählbare Boolean True Variable (Globale Nachrichtensperre)
  • Befehl: TESTE EXECUTE (Ausgabe der nmap Versionsinformationen in einem Popup, diese darf NICHT LEER sein !)
  • Befehl: TESTE BENACHRICHTIGUNG (die Test-Nachricht versendet die Daten des ersten Hosts im Netzwerk, mit den gewählten Einstellungen des Konfigurationsformulars)
  • Befehl: STARTE SCAN (der manuelle Start von nmap)
  • Befehl: DATEN LÖSCHEN! (Löscht die gespeicherten Scan-Daten des Moduls)
  • Befehl: HISTORIE LÖSCHEN! (Löscht die gespeicherten Historie-Daten des Moduls)

Benachrichtigung (Neuer Host)

Das Modul versendet (per Instanz) eine Nachricht wenn ein "Neuer Host" gefunden wird.
Es stehen 3 Benachrichtigungs Möglichkeiten zur Auswahl.

  • WebFront (zB. zur Anzeige am Tablet)
  • Push (zB. senden an Symcon-App)
  • Mail

Zusätzlich kann jeweils eine BOOL Variable ausgewählt werden, die (wenn ausgewählt) den Wert "True" haben muss, damit die Benachrichtigung versendet wird.

Benachrichtigungen (Benutzerdefiniertes Skript)

Mit aktivieren von "Eigene Benachrichtigung" werden alle Variablen des Moduls (als Array) dem ausgewählten Skript übergeben. Somit stehen viele Möglichkeiten zur Auswahl, Beispiele:

  • IP-Adresse 10.8.3.45 ist Offline
  • MAC-Adresse 34:CA:56:93:27:BD ist Online
  • Neuer Host im Netzwerk

Zusätzlich kann eine BOOL Variable ausgewählt werden, die (wenn ausgewählt) den Wert "True" haben muss, damit die Benachrichtigung versendet wird.

MERKE!

  • Im Script ist für die Prüfung des Online/Offline-Status die Variable $NMAP['CHANGED'] wichtig, ansonsten wird bei jedem Timer Aufruf eine Benachrichtigung ausgelöst!

Beispiel-Skript: Eigene Benachrichtigung für "IP Offline" oder "Neuer Host".
(Verfügbare Variablen stehen unter diesem Beispielscript) 

<?php
//Nmap Telegram-Benachrichtigung (Host offline, Neuer Host)
//(Telegram: iD-Simon:xxxxxxxx, iD-Christoph:xxxxxxxxx)

$ARRAY = unserialize($_IPS['NMAP']);

foreach ($ARRAY as $NMAP) {
    if ($NMAP['CHANGED'] && $NMAP['IP'] == "10.8.5.102" && $NMAP['STATE'] == "down") {
        SendMessage($NMAP, "Host ist Offline!");
    }
    if ($NMAP['NEWHOST']) {
        SendMessage($NMAP, "Neuer Host im Netzwerk!");
    }
}

function SendMessage($NMAP, $TEXT) {
    $Bot = 12345;

    $TITLE = $_IPS["NMAP_TITLE"];
    $LF = "\r\n";

    $Message = $TITLE.$LF.$TEXT.$LF.$LF."IP: ".$NMAP['IP'].$LF."Hostname: ".$NMAP['HOSTNAME'].$LF."MAC: ".$NMAP['MAC'].$LF."Vendor: ".$NMAP['VENDOR'].$LF."Status: ".$NMAP['STATE'];

    //IPS_LogMessage($_IPS['SELF'], $Message);
    Telegram_SendText($Bot, $Message, "9762498"); 
}

Verfügbare Array-Variablen für "Benutzerdefiniertes Skript"

  • $NMAP['LF'] // (string) "crlf"
  • $NMAP['IP']
  • $NMAP['IP15'] // (string) "192.168.000.001"
  • $NMAP['HOSTNAME']
  • $NMAP['MAC'] // (string) "00:00:00:00:00:00"
  • $NMAP['VENDOR']
  • $NMAP['UNIXTIME']
  • $NMAP['STATE'] // (string) "up" || "down"
  • $NMAP['NEWHOST'] // (boolean) true || false
  • $NMAP['CHANGED'] // (boolean) true || false

✍️ Autoren

  • @Simon6714 - Idee & Erstarbeit

  • @Bayaro - Codechecker

    -> Ein dickes DANKE an Christoph(Bayaro), für die CSS-Codevorlage und die guten Tips zum Thema Symcon Modulerstellung :-)

🎉 FAQ

  • Wie funktioniert das Nmap Symcon Modul ?
    Das Symcon Nmap Modul ruft die Linux Binary nmap mit den Parametern "nmap -v -sn xxx.xxx.xxx.xxx -oX /tmp/datei" (Ping-Scan) auf, liest die erstellte XML Datei ein, und verarbeitet die Daten in Arrays. Das Modul bewahrt sich dabei immer die Daten des Scans auf, um beim nächsten Scan die Änderungen vergleichen zu können.
    Falls etwas nicht wie gewünscht funktioniert bzw. angezeigt wird stellen sich 2 Fragen:
    1. Sind die Informationen der von Nmap ausgegebenen XML-Datei korrekt ? (Pfad der XML: /tmp/nmap_$subnet.xml). Falls nicht können andere Nmap-Parameter das Problem beheben ?
    2. Falls die Daten im XML richtig sind, und nicht zur Ausgabe in der ~Htmlbox passen, dürfte es sich um einen Fehler in der Verarbeitung des Moduls handeln.


  • FEHLER: Execute ist nicht korrekt!
    1. Bei lokaler Ausführung: Pfad- oder Berechtigungsproblem
    2. Bei remote Ausführung: 1.Public-Key-Authentication funktioniert? | 2. nmap (am Remotehost) installiert? | 3. Berechtigunsproblem

  • FEHLER: Modul konnte nicht starten, kontrolliere Einstellungen!
    Falls du gerade deine Debian(Ubuntu?) Distribution aktualisiert hast, ev. funktioniert diese nmap Version nicht!
    Erfolgreich getestet:

    • nmap-Version 7.70 (in Debian Buster enhalten)

    Tip: Schalte das Debug des Moduls ein, und Suche dort nach "RunScan(Execute)", diesen Aufruf kannst du nun manuell in der CLI/Console des Systems starten, und prüfen ob die Zieldatei /tmp/Subnet.xml Datei erfolgreich erstellt wurde.

  • HTML Tabelle nach IP sortieren
    Die Tabelle ist ohne diese Einstellung schon korrekt sortiert, jedoch steht der ausführende Host dann nicht mehr am Ende der Liste, sondern wird einsortiert.

  • Kann das Modul auch für Diensteübersicht(offene Ports) verwendet werden ?
    Das Modul dient lediglich der Übersicht welche Hosts sich im Netzwerk befinden. (Für Security Themen gibt es bessere Werkzeuge ;-)

  • Manche Hosts wechseln bei (fast) jedem Scanvorgang Ihren Status !?
    Ja, dieses Verhalten ist bei manchen Geräten zu beobachten. Hauptsächlich Hosts per WLAN: Smartphones, Squeezebox. Ich konnte das aber zB. auch bei Homematic LAN-Gateways beobachten obwohl diese am Kabel verbunden sind. Ich habe hier auch schon mit Nmap-Parametern "gespielt", aber keine wirkliche Verbesserung feststellen können, falls jemand eine hilfreiche Entdeckung macht, bitte um Nachricht und Lösung ;-)

  • Der Hostname fehlt bei einem meiner Hosts !?
    Gegenfrage: Entspricht der Hostname dem Standard ? Als Hostname Zeichen sind eigentlich nur [A-Z][0-9] und [-] erlaubt, Details siehe:
    https://de.wikipedia.org/wiki/Hostname#Richtlinien
    Nmap hält sich anscheinend an diese Richtlinien.

  • Nmap im Docker Container
    Nmap kann nur im lokalen(selben) Netzwerk die MAC und Vendor Informationen auslesen.
    Da sich der Symcon-Docker-Container standardmäßig in einem eigenen Docker-Netzwerk befindet gibt es 2 Möglichkeiten:
    1. Docker Network Mode: "Host", hier bekommt der Container dieselbe IP-Adresse wie das Wirtsystem auf dem es läuft und Nmap funktioniert so problemlos.
    2. Docker Network Mode: "Bridge", verwende im Bridge Mode "Execute REMOTE", Voraussetzungen: 
      apt install openssh-client iproute2 iputils-ping
ssh-keygen -t rsa
..nun die Schritte wie in "2b. nmap - Execute REMOTE" beschrieben

  • Nmap Fehlermeldungen nicht in HTML-Tabellen sichtbar
    Obwohl der Nmap Scan nicht erfolgreich war ist dies nicht in den Ausgabetabellen sichtbar.
    In den HTML Ausgabetabellen stehen nur Fehlermeldungen des Nmap Scans selbst.
    Fehler vom Modul (Execute nicht erfolgreich) werden per Benachrichtung (einmalig) versendet!

  • Wäre fing anstatt nmap nicht besser?
    Bei meinem Vergleichstest (Subnet mit ca. 40 aktiven Hosts) benötigt nmap ca. 5-6 Sekunden, fing benötigt 16 Sekunden. Der Informationsgehalt ist derselbe (Hostname, MAC, Vendor..)