Kurz gesagt: Der IoC Lookup lädt IoCs („Indicator of Compromise“, d.h. bösartige Domains, IP-Adressen oder URLs) von verschiedenen Blocklisten herunter und fasst sie in drei csv-Dateien (eine für jeden Typ) zusammen. Die Informationen dieser Dateien werden über eine REST-API bereitgestellt und können von Graylog über einen HTTP-JSON Path-Adapter verwendet werden, um eine Lookup-Tabelle zu erstellen.

Ein häufiges Anwendungsszenario ist die Kennzeichnung und Anreicherung aller Arten von Logs (d. h. Active Directory, VPN, DNS, E-Mail usw.), die bösartige IPs, Domänen oder URLs enthalten, mit detaillierten Informationen über den IoC für weitere Untersuchungen.

Der größte Aufwand besteht darin, den Flask-Server für die API zu konfigurieren und die JSON-Datei mit den herunterzuladenden Blocklisten einzurichten.

Darüber hinaus ist es leicht erweiterbar für neue Blocklisten oder Use Cases.

IOC-Lookup 1.0 für Graylog

Dieses Plug-in liest CSV-Listen mit IOCs via HTTP-JSON Path-Adapter.

Kosten: 250,- Euro exkl. MwSt.

Contact Sales

 

Wie funktioniert es?

IoC Lookup besteht aus zwei kleinen Programmen, einer Graylog Lookup Table und einigen Graylog Pipelines. Das erste ist das anfängliche Programm zum Herunterladen der Blockliste und zur Bereitstellung der CSV-Dateien mit IoCs („ioc-lists.py“) und das zweite ist der Flask-Server („ioc-server.py“), der die REST-API für die weitere Suche bereitstellt.

Das Hauptprogramm („ioc-lists.py“) lädt alle angegebenen Blocklisten in „downloads.json“ herunter und speichert sie für die weitere Verwendung zwischen. Nach Abschluss aller Downloads liest es jede Datei und sortiert die enthaltenen IoCs in die drei Kategorien IP, Domain und URL. Darüber hinaus versucht es, die gefundenen IoCs mit zusätzlichen Daten wie dem Datum des ersten Auftretens anzureichern. Im nächsten Schritt werden die sortierten IoCs und ihre Quellen in drei verschiedenen csv-Dateien gespeichert, eine für jede Art von IoC, d.h. eine Datei für IPs, eine für Domains und eine für URLs.

Zusätzlich können die IoC-Daten über eine kleine Flask REST-API („ioc-server.py“) abgefragt werden. Die API bedient einen Endpunkt („/lookup“), der eine Get-Anfrage mit dem Lookup-Wert (IP, Domain, URL) und einem Autorisierungs-Token erwartet. Wenn der angegebene Lookup-Wert als IoC bekannt ist, wird die Quelle der gefundenen IoC-Blockliste zurückgegeben, andernfalls gibt die Anfrage false zurück. Darüber hinaus bietet die API einen Endpunkt („/reload“), der einen Post-Request und einen Autorisierungs-Token erwartet und eine Möglichkeit bietet, die API mit neuen IoC-Daten aus den Dateien zu aktualisieren.

Der API-Endpunkt wird mit einem Graylog HTTP JSONPath Data Adapter verwendet, um eine Lookup Table zu erstellen. Diese Lookup Table wird in verschiedenen Pipelines verwendet, um verschiedene Logs mit IPs, Domänen und URLs daraufhin zu überprüfen, ob es sich um IoCs handelt, und wenn ja, das Log mit zusätzlichen Informationen anzureichern.

Installation

Erstinstallation von IoC Lookup

Nachdem Sie Ihre Kopie von IoC Lookup erhalten haben, kopieren Sie sie auf ein System, auf dem ein beliebiges Linux-Betriebssystem mit systemd läuft. Nun müssen Sie die Python-Abhängigkeiten installieren. Sie können dies mit folgendem Befehl innerhalb des IoC Lookup Ordners tun: „pip install -r requirements.txt“. Wenn Sie ein System mit dem Stand Python 2 und Python 3 installiert haben, müssen Sie „pip3“ anstelle von „pip“ aufrufen. Danach müssen Sie zwei Ordner in Ihrem Programmverzeichnis erstellen: „downloads“ und „lists“.

Damit der Flask-Server funktioniert, müssen Sie „gunicorn“ installieren, dies kann mit dem Konsolenbefehl „sudo apt install gunicorn3“ getan werden. Wenn Sie möchten, können Sie „apt-get“ statt „apt“ verwenden. Die Installation von „gunicorn“ kann auch mittels pip passieren: „pip install gunicorn“.

Konfiguration von ioc-lists.py

Die Konfiguration des Hauptprogramms („ioc-lists.py“) erfolgt über die Datei „ioc-lists.conf“. Diese Konfigurationsdatei enthält alle Informationen, die für die Ausführung des Programms erforderlich sind. Sie müssen die Zeilen 3 und 6 der Datei so anpassen, dass sie den absoluten Pfad zu den beiden Verzeichnissen enthalten.

Erste Konfiguration der herunterzuladenden Blocklisten

IoC Lookup wird mit einer Vorauswahl verschiedener Blocklisten ausgeliefert, die Sie verwenden können. Wenn Sie andere Blocklisten verwenden möchten, lesen Sie bitte den Abschnitt „Anpassen“.

Konfiguration von ioc-server.py

Die Konfiguration des Flask-Servers basiert auf den Dateien „ioc-lists.conf“ und „ioc-server.service“. Außerdem müssen Sie eine Datei „token.txt“ in Ihrem Programmverzeichnis erstellen. Die Konfigurationsdatei „ioc-lists.conf“ wurde bereits in einem früheren Schritt konfiguriert, so dass hier kein Handlungsbedarf besteht.

Für „ioc-server.service“ ist jedoch eine zusätzliche Konfiguration erforderlich. In Zeile 7 müssen Sie den absoluten Pfad zu „ioc-lists.conf“ und in Zeile 8 den absoluten Pfad zu der neu erstellten Datei „token.txt“ angeben. In den Zeilen 9 und 10 müssen Sie den Benutzer und die Gruppe angeben, die den Server betreiben soll. Außerdem müssen Sie Zeile 15 an den absoluten Pfad des Arbeitsverzeichnisses anpassen. Standardmäßig läuft der Server auf Port 5000, wenn Sie den Port ändern möchten, passen Sie Zeile 16 an. Abhängig vom Installationsordner von „gunicorn“ muss der Pfad zu diesem in Zeile 16 ebenfalls angepasst werden.

Schließlich müssen Sie „token.txt“ bearbeiten. Diese Datei enthält das für die API-Endpunkte erforderliche Autorisierungs-Token. Erstellen Sie einfach ein neues und sicheres Token und fügen Sie es in diese Datei ein.

Daemon für Flask server

  1. Legen Sie die Datei „ioc-server.service“ in das Verzeichnis „/etc/systemd/system“.
  2. Starten Sie den Server mit „systemctl start ioc-server“.
  3. Aktivieren Sie den automatischen Start beim Booten: „systemctl enable ioc-server“

Cron Job

Die Erstellung eines Cron-Jobs wird empfohlen, um IoC Lookup regelmäßig auszuführen und seine Listen und den Server zu aktualisieren. Das Ausführungsintervall hängt von Ihren Bedingungen ab.

Die crontab für IoC lookup sollte dem folgenden Schema folgen:

python3 <absolute-path>/ioc-lists.py –config <absolute-path>/ioc-lists.conf && curl -XPOST -s –show-error „http://<ip:port>/reload?token=<token>“ > /dev/null

Zum Beispiel:

(Zum Vergrößern klicken)

 

Mit diesem Befehl wird das IoC Lookup jede Stunde aktualisiert und der Flask Server automatisch neu geladen.

Erstellung einer Graylog-Lookup-Tabelle

Um das IoC Lookup in Graylog zu nutzen, müssen Sie einen Lookup Table erstellen. Ein Lookup Table in Graylog besteht aus drei Teilen: der Lookup Table, einem Data Adapter und einem Cache.

Zuerst erstellen Sie den Datenadapter. Navigieren Sie dazu in Graylog über das Menü System->Lookup Tables auf die Seite Lookup Table und wählen Sie dann im Menü oben rechts Data Adapters aus. Danach klicken Sie auf Datenadapter erstellen und wählen HTTP JSONPath als Datenadapter aus. Füllen Sie das Formular wie folgt aus:

 

  1. Title: Geben Sie “Adapter: IoC Lookup” als Namen ein
  2. Lookup Url: http://<ip:port>/lookup?token=<token>&value=${key}
  3. Ersetzen Sie <ip:port> and <token> durch Ihre entsprechenden Werte.
  4. Single value JSONPath: $.ioc
  5. HTTP User-Agent: Graylog Lookup – https://www.graylog.org/

Es sollte in etwa so aussehen:

(Zum Vergrößern klicken)

 

Sie können den Datenadapter nun speichern und mit der Erstellung des Cache fortfahren. Wählen Sie im Menü oben rechts „Cache“ und dann „Cache erstellen“. Wählen Sie aus dem Dropdown „Node-local, in-memory cache“.

Konfigurieren Sie den Adapter wie folgt:

  1. Title: “Cache: IoC Cache”
  2. Maximum Entries: 1000000
  3. Expire after access: Aktivieren Sie das Kontrollkästchen und wählen Sie 45 Sekunden.

Es sollte in etwa so aussehen:

(Zum Vergrößern anklicken)

 

Schließlich konfigurieren Sie die Lookup-Tabelle selbst. Wählen Sie im Menü oben rechts Lookup Tables und dann Create lookup table. Geben Sie der Lookup Table einen Namen wie „ioc-lookup“ und wählen Sie den zuvor erstellten Data Adapter und Cache aus. Speichern Sie die Lookup-Tabelle und sie ist einsatzbereit.

Erstellung von Graylog Pipelines

Um die erstellte Lookup-Tabelle zu verwenden, müssen Sie Graylog-Pipelines verwenden. Für IoC Lookup ist mindestens eine Pipeline erforderlich. Um die Regel zu erstellen, navigieren Sie zu Pipelines über das Menü System->Pipelines und erstellen Sie eine neue Regel. Geben Sie der Regel eine Beschreibung und tragen Sie folgenden Code in den Abschnitt „Rule source“ ein:

rule „ioc_lookup“
when
  has_field(„ioc_lookup_value“)
then
  set_field(„ioc_lookup_result“,
  to_string(lookup_value(„ioc-lookup“,
  $message.ioc_lookup_value)));
end

Das sollte in etwa so aussehen:

(Zum Vergrößern anklicken)

 

Die Regel setzt voraus, dass das Feld „ioc_lookup_value“ vorhanden ist und den zu suchenden Wert (IP, Domäne oder URL) enthält. Ist dieses Feld vorhanden, wird die Lookup-Tabelle aufgerufen und das Ergebnis in ein neu erstelltes Feld namens „ioc_lookup_result“ geschrieben. Die erstellte Regel muss an eine Pipeline angehängt werden. Die Pipeline, an die sie angehängt wird, hängt von Ihren Anforderungen ab. Sie kann mit einer Vielzahl von Protokollen verwendet werden, die lediglich eine IP, Domäne oder URL enthalten müssen.

Wie das Feld „ioc_lookup_value“ erstellt und ausgefüllt wird, hängt von Ihrer Graylog-Einrichtung ab. Es kann zum Beispiel mit anderen Pipelines gemacht werden und ist nicht Teil dieser Anleitung.

Anpassen

IoC Lookup ist hinsichtlich der verwendeten Blocklisten in hohem Maße anpassbar. Es wird mit einer Vorauswahl an Blocklisten und Parsern für diese geliefert.

Hinzufügen einer neuen Blockliste

Wenn Sie weitere Blocklisten zur Überwachung weiterer Anwendungsfälle benötigen oder hinzufügen möchten, können Sie die neue Blockliste mit folgendem Format zu „downloads.json“ hinzufügen:

{
„url“: <Full URL to the blocklist>,
„source“: <Source of the blocklist>,
„type“: <Type of file („text/plain“ or „text/csv“)>,
„content“: <Content of file (ip/domain/url)>,
„parser“: <Parser to be used>
}

In den vordefinierten Blocklisten finden Sie weitere Hinweise und Informationen zu den vorhandenen Parsern.

Hinzufügen eines neuen Parsers

Für das Parsen der Blocklisten wird ein abstraktes factory pattern (siehe https://en.wikipedia.org/wiki/Abstract_factory_pattern für weitere Informationen) verwendet. Der gesamte Code für die Parser ist im Ordner „ioc“ zu finden. Der Ordner „ioc“ enthält einen Ordner „parsers“, der Unterordner für die unterstützten Dateitypen (text, csv, json) enthält. Die Struktur der relevanten Ordner/Dateien ist die folgende:

  • ioc/parsers
    • _init_.py
    • parser_factory.py
    • csv
      • _init_.py
      • factory.py
      • parser.py
    • json
      • _init_.py
      • factory.py
      • parser.py
    • text
      • _init_.py
      • factory.py
      • parser.py

Schreiben eines neuen Parsers für einen vorhandenen Dateityp

Wenn Sie einen neuen Parser für einen bestehenden Dateityp benötigen, müssen Sie die Dateien „factory.py“ und „parser.py“ im entsprechenden Unterordner bearbeiten.

  1. Der erste Schritt besteht darin, eine neue Klasse in der Datei „parser.py“ zu erstellen.
    • Die Klasse muss die statische Methode „parse(text_file, source)“ implementieren, die die IoC-Daten zurückgibt.
  2. Anschließend müssen Sie die Datei „factory.py“ bearbeiten, um die neue Klasse zu registrieren.
    • Fügen Sie einen neuen „elif“-Fall für den Parser hinzu und rufen Sie die „parse“-Funktion des Parsers auf.

Zur weiteren Orientierung sehen Sie sich an, wie die anderen Parser implementiert sind.

Schreiben eines Parsers für einen neuen Dateityp

Wenn Sie einen neuen Dateityp parsen müssen, müssen Sie einen neuen Unterordner für diesen Typ hinzufügen und drei Dateien „__init__.py“, „factory.py“ und „parser.py“ in diesem Unterordner erstellen.

  1. Der erste Schritt besteht darin, den benötigten Parser in der Datei „parser.py“ zu erstellen (siehe Beschreibung unter Schreiben eines neuen Parsers für einen bestehenden Dateityp).
  2. Danach muss der Parser in die Datei „factory.py“ importiert werden, dies kann geschehen mit „from .parser import *“. Dies importiert alle Parser aus ihrer Datei.
  3. Nun müssen Sie die Werksklasse für diesen Dateityp in „factory.py“ erstellen und die statische Methode „create_<Dateityp>_parser(file)“ definieren. Ersetzen Sie <Dateityp> durch Ihren entsprechenden Dateityp. Diese Funktion wird verwendet, um die Parser des Dateityps aufzurufen.
  4. Exportieren Sie das neu erstellte Werk in die Datei „__init__.py“. Dies kann mit „from .factory import <factory-name>“ geschehen.
  5. Importieren Sie das neue Werk in „parser_factory.py“. Schauen Sie, wie die anderen Fabriken importiert werden, um sich zu orientieren.
  6. Registrieren Sie das neue Werk und den Dateityp in der Methode „create_parser(file)“ in der Datei „parser_factory.py“.

Für weitere Anleitungen und Informationen sehen Sie sich an, wie die anderen Parser implementiert sind und wiederholen Sie den gleichen Prozess.

FAQ

Frage: Ist IoC-Lookup mit Graylog Enterprise kompatibel?

Antwort: Ja.

Frage: Auf welchem Betriebssystem kann IoC-Lookup laufen?

Antwort: IoC-Lookup wurde auf Ubuntu Linux getestet. Da der Flask-Server als systemd-Daemon laufen soll, benötigt er ein Linux-Betriebssystem. Der Einsatz auf anderen Betriebssystemen wird nicht unterstützt.

Frage: Was sind die Voraussetzungen für die Verwendung von IoC Lookup?

Antwort: Eine stabile Internetverbindung, Python in Version 3.6 oder neuer und die Bibliotheken „requests“, „validators“ und „Flask“. Außerdem benötigen Sie Logs, die IP-Adressen, Domains oder URLs enthalten. Der Flask-Server basiert auf „gunicorn“, dieses muss ebenfalls installiert sein.

Frage: Wird auch Python 2 unterstützt?

Antwort: Nein. Da Python 2 sein EOL im Januar 2020 erreicht hat, wird es nicht unterstützt.

Frage: Welche Graylog-Version wird benötigt?

Antwort: IoC Lookup funktioniert mit allen Graylog-Versionen, wenn sie einen HTTP JSONPath Data Adapter bereitstellen.

Frage: Welche Welche Dateitypen können die Blocklisten haben?

Antwort: IoC Lookup unterstützt standardmäßig Textdateien (.txt), csv-Dateien (.csv) und json-Dateien (.json). Wenn Sie andere Dateien unterstützen müssen, können Sie das Programm mit Ihren eigenen Parsern für diesen Dateityp erweitern.

Frage: Werden auch lokale Dateien unterstützt?

Antwort: Ja! Die Blockliste muss nicht unbedingt eine Online-Ressource sein. Es werden auch lokale Pfade als Datei-URL unterstützt.

Frage: Welche Daten werden an jede von IoC Lookup markierte Nachricht angehängt?

Antwort: Die folgenden zusätzlichen Felder sind in den Nachrichten enthalten:

  • ioc_lookup_field: zeigt an, in welchem Log-Feld der IoC gefunden wurde, zum Beispiel server_ip.
  • Ioc_lookup_result: zeigt das Ergebnis der API-Anfrage an, d.h. welche Blockliste die bösartige IP, Domain, URL enthält.
  • Ioc_lookup_value: enthält den gefundenen IoC
  • Ioc_lookup_value_sanitized: enthält eine bereinigte Version des gefundenen IoC

Frage: Kann ich das IoC-Lookup anpassen?

Antwort: Ja, Sie können die verwendeten Blocklists anpassen. Sie können auch frei festlegen, für welche Protokolle Sie die IoC-Suche verwenden. Weitere Informationen finden Sie unter „Anpassen“.

Frage: Kann IoC Lookup in einem Graylog-Cluster verwendet werden?

Antwort: IoC Lookup kann mit einem einzelnen Graylog-Server oder einem ganzen Graylog-Cluster arbeiten. Da IoC Lookup auf einem anderen System als Graylog läuft und Graylog einen Data Adapter verwendet, um die Informationen zu holen, funktioniert dies mit einer beliebigen Anzahl von Graylog-Knoten.

Frage: Welche Endpunkte stellt die API zur Verfügung?

Antwort: Die folgenden Endpunkte werden von der API bereitgestellt:

  • /lookup [GET]: Zum Abrufen des Ergebnisses eines IoC-Lookups
    • Erfordert Token und Wert
    • Zum Beispiel: http://<ip:port>/lookup?token=<auth token>&value=<lookup value>
  • /reload [POST]: Zum erneuten Laden des Servers, um neue Informationen bereitzustellen
    • Erfordert Token
    • Zum Beispie: http://<ip:port>/reload?token=<auth token>

Frage: Wie ist die Software lizenziert?

Antwort: Die Software wird in der jeweils angebotenen Version gekauft und kann für ein Cluster genutzt werden. Für neue Versionen ist ein Upgrade notwendig.