Nmap Modul by SimonS & Bayaro

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

  • 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!