Benutzerhandbuch

Die entwickelten Projekt-Bestandteile unterteilen sich in folgende 3 Module:

Im folgenden Benutzerhandbuch wird die Handhabung dieser drei Bestandteile erläutert:

Honeygrove

Honeygrove - ein in Python geschriebener modularer Honeypot, der über verschiedene Service-Schnittstellen verfügt und die Interaktion eines Angreifers darüber loggt.

Ressourcen

Hardware

Die absoluten (!) Mindestanforderungen entsprechen denen eines Raspberry Pi 3 Model B mit Quad Core CPU 1.2 GHz und 1 GB RAM Motherboard.

Betriebssystem

Ubuntu (getestet ab Version 16.4 mit allen aktuellen Paketen)
Debian (getestet ab Version 9.1 mit allen aktuellen Paketen)

folgende Pakete sind vorher zu installieren:

Twisted 17.5.0
Broker (pybroker /mfischer/broker-multihop)
Python 3 oder höher

weitere Installationsschritte

Ordner "honeygrove" an gewünschtes Verzeichnis kopieren
honeygrove_install ausführen

Konfiguration

Alles, was in Honeygrove konfigurierbar ist, wird in der Datei config.py festgelegt.

HPID - Eindeutige ID für den Honeypot
machine_name - Gerätename, der in den Services verwendet werden soll
hp_description - Beschreibung des Honeypots wie z.B. Standort
resources - Pfad zum Ressourcenordner
logpath - Pfad an dem die lokale Logdatei abgelegt wird
listenServicePorts - Liste von Ports, auf denen der ListenService laufen soll
listenServiceName - Name, den der ListenService nutzen soll
tcpFlagSnifferName - Name, den der TCPFLagSniffer nutzen soll
httpResponseHeader - Header, der bei der HTTP Response gesendet wird
httpHTMLDictionary - Dict mit den unterstützten HTTP-Seiten. Kann durch Nutzung des HTMLLoader vereinfacht werden
httpResources - Pfad zu den Ressourcen für den HTTPService
httpPort - Port, auf dem der HTTPService laufen soll
httpName - Name, den der HTTPService nutzen soll
sshPort - Port, auf dem der SSHService laufen soll
sshName - Name, den der SSHService nutzen soll
ssh_real_shell - Gibt an, ob die Anfragen an den SSHService an die echte Shell weitergereicht werden sollen. Bietet dadurch mehr Möglichkeiten das Verhalten mitzuschneiden, öffnet das echte System jedoch komplett nach außen.
ftpPort - Port, auf dem der FTPService laufen soll
ftpName - Name, den der FTPService nutzen soll
path_to_filesys - Pfad zu dem XML-Dateisystem, das alle Services für ihre FilesystemParser nutzen
tokendir - Pfad zu den Dateien, die im vorgetäuschten Dateisystem auffindbar sein sollen
tokenDatabase - Pfad zu der Datei mit den Login-Daten
honeytokendbGenerating - Dict mit Services, welche Honeytoken generieren können
honeytokendbProbabilities - Dict mit Wahrscheinlichkeiten zur Honeytoken-Generierung
sshAcceptsFiles - Gibt an, ob der SSHService Dateien speichern darf (z.B. wget)
ftpAcceptsFiles - Gibt an, ob der FTPService Dateien speichern darf (z.B. put)
quarantineDir - Pfad zum Verzeichnis, in dem empfangene Dateien gespeichert werden sollen
startupList - Liste mit den Namen der Services, die beim Start von Honeygrove automatisch gestartet werden
noPortSpecificService - Liste mit den Namen der Services, die auf mehr als einem Port laufen dürfen
tcpTimeout - Zeit, nach der nach eine Antwort auf ACK-SYN erfolgen soll
BrokerComIP - IP auf der wir lauschen für Broker peerings
BrokerComPort - Port auf dem wir lauschen für Broker peerings
honeygrove_start - 'active' Service werden beim Start des Honeypots mit gestartet. 'passive' services bleiben ausgeschaltet

Änderungen treten erst nach einem Neustart von Honeygrove in Kraft. Einige Einstellungen lassen sich über die Management-Konsole jedoch auch im laufenden Betrieb ändern.

Defaultschlüssel

Unter resources/honeytoken/database.txt sind beispielhaft einige Login-Daten gegeben.

Starten des Honeypots

Ausführen von honeygrove.sh startet Honeygrove

Anwendungsszenarien für die Bedienung der einzelnen Services

Im folgenden soll die einfache Benutzung der einzelnen Services von Angreiferseite anhand einiger Use-Cases dokumentiert werden.

Hinweis:

Es gibt zum Zeitpunkt des Projektabschluss keine Limitierung der ansprechbaren Services.

SSH

Es kann sich regulär über SSH verbunden werden, also über das Terminal z.B. mit ssh root@localhost -p 12222. Nach der Authentifizierung kann auf üblichem Wege über SSH mit dem SSH-Service kommuniziert werden.

FTP

Es kann sich regulär über FTP verbunden werden, z.B. mit dem Terminal ftp und dann open localhost 4646. Nach der Authentifizierung kann über die gängigen FTP-Befehle mit dem Service kommuniziert werden.

HTTP

Im Browser werden die Seiten localhost:/<seiten_url> angesprochen. Diese 4 Seiten sind in den Ressourcen bereits vorkonfiguriert.
Beispiel für Port 8080 (HTTP Standard):

localhost:8080/ ---> Fritzbox Seite
localhost:8080/wp-admin ---> Wordpress Login
localhost:8080/ghost ---> Ghost Login
localhost:8080/phpmyadmin ---> phpMyAdmin Login

Auf den Login Seiten kann man direkt Login Versuche starten, welche mit einer gewissen Wahrscheinlichkeit als gültig erklärt werden. Diese Wahrscheinlichkeit kann in der config.py unter "HoneytokenDB configuration" eingestellt werden. Bei allen default Seiten, wird man bei einem erfolgreichen Login-Versuch auf eine Dashboard-Seite weitergeleitet.

Wie füge ich eine HTML Seite hinzu?

Neue Seiten können als HTML über die Managementkonsole konfiguriert werden. Hierfür in der Management-Konsole nach dem Peeren folgendes eingeben:

add_html_page -hid 1234-568-890 -url /test -dir /any/path/you/can/reach.html -dashdir /any/path/you/can/reach.html

-dashdir ist optional, -url ist der URLPfad unter dem die Seite später zu erreichen sein soll.

Eine andere Möglichkeit ist die Hinterlegung der HTML-Seiten in dem Ordner http_resources.

Management-Konsole

Die Management-Konsole dient der Interaktion des Anwenders mit einem oder mehreren Honeygrove-Honeypots. Es spielt keine Rolle ob die angesteuerten Honeypots lokal oder verteilt vorliegen, solange eine eindeutige IP-Adresse bekannt ist. Die Management-Konsole kann direkt aus der systemeigenen Konsole heraus mit Parametern gestartet und benutzt werden, wie der Benutzer es von Kommandozeilen-Programmen gewohnt ist. Damit lässt sich die Management-Konsole ohne Probleme in gewohnte Arbeitsabläufe integrieren, ohne eine umständliche neue Benutzerumgebung zu erlernen. Für noch mehr Übersichtlichkeit bietet die Management-Konsole jedoch auch eine grafisch überarbeitete UI, welche anstelle des Scripts mit Parametern verwendet werden kann um größtmöglichen Nutzerkomfort zu gewährleisten.

Ressourcen

Wichtig! Sowohl zum Betrieb als auch Entwicklung der Management-Konsole müssen folgende Vorraussetzungen erfüllt werden:

Betriebssystem Um die Management-Konsole starten zu können, wird eine dieser unterstütze Linux-Distribution benötigt:
- Debian Version 9.1 (Stretch)
  - Ubuntu 17.04 (Zesty Zapus)
Python 3.5 Das Honeygrove-Projekt wurde einheitlich in dieser Python-Version entwickelt und greift auf Funktionen zurück, welche nicht mit früheren Versionen entwickelt werden können.
Pybroker Die Kommunikation zwischen Management-Konsole und Honeypots wird durch Broker-Endpoints realisiert. Broker inklusive Python-bindings (Pybroker) kann hier bezogen werden: Broker Github (Stand: 21.12.2017)

Installation

Es ist keine weitere Installation der Management-Konsole vonnöten. Das ganze Projekt kann unabhängig von anderen Komponenten des Honeygrove-Projektes lokal abgelegt werden.

Konfiguration

Um dauerhaftes Arbeiten mit der Management-Konsole zu vereinfachen, kann eine Standard-Konfigurationsdatei angelegt werden, welche bei jedem Start der Konsole ausgelesen und verwendet wird. Hierzu muss lediglich eine Datei mit dem Namen default.conf im Hauptordner der Management-Konsole erstellt werden. Diese Konfigurationsdatei kann nun mit allen von der Konsole unterstützten Befehlen gefüllt werden. Hierbei ist zu beachten, dass zum Abschluss jedes Befehls ein Zeilenumbruch eingefügt werden muss.

Starten der Management-Konsole

Die Management-Konsole bietet zwei verschiedene Benutzeroberflächen. Zum Starten der klassischen Konsolenintegration führen Sie einfach das Script mit Paramter -cli aus:

./management-konsole.sh -cli

Um die grafische UI zu starten, muss das Script ohne Parameter ausgeführt werden.

Beispiele

Zunächst muss sichergestellt werden, dass der oder die Honeypots konfiguriert sind und laufen (bei Problemen lesen Sie hierzu den Abschnitt Honeypot des Entwicklerhandbuchs). Falls noch nicht geschehen, wechseln Sie mit der Konsole in den Ordner in dem sich das Script management-konsole.sh befindet und starten Sie dieses.

Eine direkte Verbindung aufbauen

peer -ip 127.0.0.1 -p 8888

Hier wird eine direkte Verbindung zu einem Honeypot mit der IP 127.0.0.1sowie dem Port 8888 aufgebaut. Dies kann für beliebig viele Honeypots wiederholt werden.

Die Verbindungen testen

ls -s

Der Funktionsaufruf ls -s gibt nun eine Liste aller vorhandenen Services aller verbundener Honeypots zurück.

Wie peere ich die Honeypots zum CIM?

In der Mangement-Konsole

>peer -ip HONEYPOT_IP -p 8888
>ls
Honeypot:1234-568-890
>peer -hid 1234-568-890 -ip CIM_IP -p 34445

CIM-Stack

Der Honeygrove CIM ist eine Erweiterung eines Incident Monitors um Honeypot Alerts zu betrachten. Durch Clusterbildung und Aggregation dieser Alerts können wir verschiedene Visualisierungen darstellen, welche uns beim Analysieren von Angreifer Verhalten helfen.

Ressources

Für das Incident Monitoring wurden zum größten Teil Software Produkte der Firma Elastic verwendet, sowie weitere unterstützende Software. Eine genauere Übersicht folgt in der Tabelle:

Logo	Ressource	Version	Beschreibung
	Java	1.8.0_131-b11	Entwicklungswerkzeug
	Python	3.5.2	Verwendete Programmiersprache
	Elasticsearch	5.4.0	Dient zum Verwalten und Speichern der Daten
	Kibana	5.4.0	Dient zur Visualisierung der Daten
	X-Pack	5.4.0	Plugin für Elasticsearch und Kibana. Wird für Watcher-Alerts verwendet
	Mattermost	3.9.0	Open Source, selbst gehostete Slack-Alternative
	PyBroker	0.14.5	Eine Library für Python zum Erstellen von Endpoints
	Docker	17.06.0	Eine Container Platform für den EK-Stack
	Docker-Compose	1.8.0	Ein Tool zum Definieren und Ausführen von Multi-Container Docker Anwendungen
	Team Cymru MHR	07.08.2017	Malware Hash Registry dient als Look-up Service
Honeygrove	Honeygrove	1.0	Honeypot
	Optionale Software	Version	Beschreibung
	Logstash	5.4.0	Dient zur Aggregations der Daten

Systemanforderungen:

Der Honeygrove CIM läuft nur auf einem Linux System. Folgende Systemanforderungen sind dabei zu beachten:

Linux Distributionen: Ubuntu 16.04 LTS oder Debian 9.1
RAM: mindestens 8GB (Optional: kann auf Kosten der Effizienz verkleinert werden, siehe: Konfiguration)
Prozessor: Intel &reg Core &trade / AMD64

Installation

Die Installation der oben angegebenen Pakete erfolgt automatisch über das Skript installCIMPackages.sh

Der CIM kann entweder als EK-Stack zusammen mit dem CIMBrokerEndpoint installiert und ausgeführt werden oder aber beide Komponenten getrennt voneinander. Hierbei ist zu beachten, dass vor der ersten Installation alle benötigten Packages installiert werden müssen, damit der CIM laufen kann. Außerdem unterscheiden wir zwischen einem EK-Stack Install Script für den Server und für den Desktop. Der Unterschied liegt darin, dass das Server Script im Hintergrund läuft und Log-files vom Programmablauf erstellt. Beide Scripts befinden sich im Verzeichnis /incidentmonitoring/EKStack/.

Alle EK-Stack Scripte starten eine docker-compose.yml, welche verwendet wird um ein CIM Cluster zu starten. Dieser besteht aus einem Kibana Knoten und drei Elasticsearch Knoten. Dabei teilen sich die ES Knoten in einen Master (es-master) und zwei Slaves (es-data-1, es-data-2) auf. Die Slaves sind verantwortlich für anhaltende Daten und gespiegelte Kopien voneinander. Umgebungsvariablen werden verwendet, um den Zweck eines Clusterknotens zu bestimmen.

Standardmäßig benötigt Elasticsearch eine ziemlich große mmap-Zählung. Damit ES in der Lage ist zu starten, muss der folgende Befehl auf dem ES-Hostsystem ausgeführt werden (nicht innerhalb des Containers, echter Host): sysctl -w vm.max_map_count = 262144. Weitere Informationen finden sich in der offiziellen Dokumentation. Diese Eigenschaft wird automatisch in allen Start Scripts gesetzt. Um zu überprüfen, ob der CIM korrekt gestartet wurde, kann sudo docker ps verwendet werden. Die Erstellung des Index und Mappings läuft im CIM komplett automatisch und muss nicht vom Benutzer manuell ausgeführt werden. Im Konfigurationsabschnitt unter Elasticsearch wird weiter darauf eingegangen.

Komplette Installation

cd incidentmonitoring/
sudo sh installCIMPackages.sh (Nur bei erst Installation)
sudo sh runCIMFull.sh (CIMEndpoint mit EKStack Desktop Version)

Komponentenweise Installation

cd incidentmonitoring/
sudo sh installCIMPackages.sh (Nur bei erst Installation)
sudo sh runCIMBrokerEndpoint.sh (Führt Endpoint aus)
cd EKStack/
sudo sh runEKStack.sh (Desktop version)
sudo sh runEKStackServer.sh (Server Version)

Man kann den EK-Stack auch manuell mit der docker-compose.yml und dem Befehl docker-compose up --build starten, die ebenfalls im EK-Stack Verzeichnis liegt. Im Benutzerhandbuch finden sich weitere Informationen zur Verwendung des EK-Stacks.

Konfiguration

Docker

CIM-Slaves: Sollte in der Vergangenheit bereits einmal eine CIM Stack installiert worden sein so kann man die Einstellung mittels Konsolenbefehl

curl -XDELETE 'localhost:9200/*

die Konfiguration resetten.

BrokerEndpoint:

CIMBroker IP & Port: Die IP und den Port auf dem der CIMBrokerEndpoint angesprochen wird, kann in der CIMBrokerConfig.py verändert werden.
Abonnieren von Topics: Das Anlegen und Abonnieren von neuen Topics geschieht im CIMBrokerEndpoint.py mit dem wir im CIM die Logs und Dateien von Honegrove erhalten. Ein Topic wird wie nachfolgend abonniert, wobei <Topic> der Name des zu abonnierenden Topics ist:

<NameQueue> = message_queue("<Topic>", listenEndpoint)

Um den Content des Topics zu erhalten ist noch eine Funktion notwendig, die wie folgt, aufgebaut ist:

@staticmethod
def <NameFunktion>():
return CIMBrokerEndpoint.<NameQueue>.want_pop()

Kibana:

Kibana Erreichbarkeit: Kibana ist Standardmäßig erreichbar unter localhost:5601 bzw. <serverIP>:5601. Im Falle einer Server IP kann Kibana erst aufgerufen werden, wenn eine SSH Verbindung zu diesem Server besteht und ein Tunnel hergestellt wurde. Außerdem muss bei Verwendung der Port Zugänglichkeit die IP in der docker-compose.yml ebenfalls verändert werden.
SSH: ssh -p <serverPort> <Benutzername>@<serverIP>
Tunnel: ssh -L 8080:localhost:5601 -l <Benutzername> <serverIP>
Port Zugänglichkeit: Es ist möglich, von einem lokal exponierten Port zu einem öffentlich exponierten Port zu wechseln, indem man die folgende Änderung in der docker-compose.yml macht.

     ports:
       - "127.0.0.1:5601:5601"

     ändern zu:

     ports:
       - "5601:5601"

Indexing: In Kibana unter Management -> Index Patterns auf das blaue Plus Symbol, oben Links, klicken. Als Index Name honeygrove eintippen und als Time-field Name @Timestampauswählen. Dann auf Create klicken. Der Index wurde nun erstellt. (Optional: Bevorzugten Index als Favorit wählen).
Dashboard: Das Honeygrove Dashboard kann in Kibana unter Management -> Saved Objects importiert werden. Es befindet sich im Verzeichnis /incidentmonitor/EKStack/kibana/. In der folgenden Abbildung wird das genutzte Kibana Dashboard beispielhaft gezeigt:

Elasticsearch:

Elasticsearch Erreichbarkeit: Elasticsearch ist Standardmäßig unter localhost:9200 erreichbar bzw. <serverIP>:9200. Im Falle einer Server IP, siehe Abschnitt Konfiguration Kibana. Außerdem muss bei einer Änderung der IP in der CIMBrokerConfig.py die ElasticIp verändert werden, wenn man weiterhin Logs vom CIMBrokerEndpoint empfangen möchte.
Mapping: Das Mapping wird in Elasticsearch verwendet, um einen Index zu erstellen und Datentypen, wie den Zeitstempel, korrekt zu deklarieren. Um sein eigenes Mapping zu verwenden, kann man in der ElasticsearchMapping.py unter /incidentmonitoring/EkStack/elasticsearch/config/scripts/ in der Funktion loadMapping() Änderungen vornehmen bevor der EK-Stack gestartet wurde. Wenn ein Mapping bereits erstellt wurde, muss der Index vorher gelöscht werden. Weitere Informationen zum Mapping findet man unter Elastic.co.
Index Löschen: Wenn man bereits ein Mapping in den Index geladen hat und es nachträglich verändern möchte, muss vorher der Index gelöscht werden. Das kann man im Terminal mit curl -XDELETE 'localhost:9200/honeygrove?pretty' erreichen oder in Kibana unter Dev Tools in die Konsole DELETE /honeygrove eingeben. ACHTUNG: Sämtliche Logs gehen dabei verloren. Weitere Informationen unter Elastic.co
Neues Mapping verwenden: Um ein neues Mapping in den Index zu laden, muss im Mapping-Verzeichnis folgender Befehl ausgeführt werden: python3 ElasticsearchMapping.py.

Watcher-Alerts:

Alerts Erstellen/Ändern/Löschen: Unsere Watcher-Alerts Konfigurationsdatei ist zu finden unter /incidentmonitor/EKStack/elasticsearch/config/scripts/WatcherAlerts.py. Dort können in der Funktion putWatch() beliebig viele Alerts erstellt oder verändert werden. Die vier wesentlichen Konfigurationsmöglichkeiten sind dabei "triggers", "inputs", "conditions" und "actions". Eine Dokumentation zur Erstellung von Watcher-Alerts gibt es unter Elastic.co. Watcher-Alerts können mit python3 WatcherAlerts.py in Elasticsearch geladen werden. Eine vorherige Löschung, wie beim Mapping ist hier nicht nötig. Sollte man seinen Watcher-Alert trotzdem löschen wollen kann man dies am einfachsten in Kibana unter Management -> Watcher, den gewünschten Alerts auswählen und mit löschen bestätigen.
Honeygrove-Alerts: Für den Honeygrove Honeypot werden Alerts für Brute Force Angriffe auf die Services HTTP, FTP und SSH, sowie Malware Detection Alerts verwendet. Im Falle der Brute Force Alerts wurde eine Bedingung von 100 Fehlgeschlagenen Login Versuchen an einem Service, innerhalb 10 Sekunden definiert, um einen Alert auszulösen. Zeit und Anzahl kann in den jeweiligen Alerts für individuelle Zwecke angepasst werden.

     'input': {
         'filter': {
             'range': {
                 @timestamp': {
                     'from': 'now-10s',
                     'to': 'now'}}}}}}}}},
     'condition': {
         'compare': {
             'ctx.payload.hits.total': {
                 'gt': 100}}},

Webhooks: Zurzeit wird eine gemeinsame Weebhook URL in der WatcherAlerts.py definiert. Diese kann dort verändert werden bzw. jeder Alert einen individuellen Webhook bekommen, falls gewünscht.
Dashboard: Das Watcher Dashboard wird zusammen mit dem Honeygrove Dashboard importiert. Um es jedoch nutzen zu können, muss vorher der Watcher Index initialisiert werden. Dazu auf Management -> Index Patterns nach dem Index Namen ".watcher-history-*" suchen und als Timefield Name "trigger_event.triggered_time" auswählen. Dann auf Create klicken. Notfalls nochmal importieren.

Systemanforderungen Minimieren:

Die komplette CIM Installation benötigt mindestens 8 GB RAM. Für Testzwecke oder bei unzureichender RAM-Größe, kann auf Kosten der Effizienz des CIMs, Arbeitsspeicher reduziert werden. In der docker-compose.yml müssen dafür Änderungen vorgenommen werden. Beispielsweise kann man die Slaves es-data-1 und es-data-2 komplett auskommentieren und zusätzlich den Arbeitsspeicheranteil des es-master bis auf 256 MB reduzieren. Wichtig ist beim Löschen der Slaves, dass auch die Abschnitte BM_ES_MASTER und BM_ES_DATA auskommentiert werden, sowie die ersten beiden Zeilen in der elasticsearch.yml unter /incidentmonitor/EKStack/elasticsearch/config/. Wenn man dann den EK-Stack neu startet, läuft dieser mit deutlich geringerem Speicherbedarf.

     docker-compose.yml:
     ES_JAVA_OPTS: "-Xms256m -Xmx256m"
     # BM_ES_MASTER: "true"
     # BM_ES_DATA: "false"

     elasticsearch.yml
     # node.master: ${BM_ES_MASTER}
     # node.data: ${BM_ES_DATA

Wie starte ich den CIM-Stack

cd incidentmonitoring
./runIncidentmonitoring.sh

Kibana erreichbar unter

localhost:5601 bzw <serverIP>:5601

Wie kann ich einen SSH Tunnel zur Kibana-Oberfläche auf einem Server aufbauen?

Einen Tunnel zum CIM-Server aufbauen:

ssh -L 5600:localhost:5600 -l USER HOST [-p PORT] [-i RSA_KEY]

lokal im Browser die Visualisierung ansehen: http://localhost:5600

Home

User Guides:

Honeygrove user guide
Incident-Monitoring user guide
Management-Console user guide

Documentation:

Honeygrove documentation
Incident-Monitoring documentation
Management-Console documentation

Legacy:

Benutzerhandbuch

Benutzerhandbuch

Honeygrove

Ressourcen

Hardware

Betriebssystem

folgende Pakete sind vorher zu installieren:

weitere Installationsschritte

Konfiguration

Defaultschlüssel

Starten des Honeypots

Anwendungsszenarien für die Bedienung der einzelnen Services

Hinweis:

SSH

FTP

HTTP

Wie füge ich eine HTML Seite hinzu?

Management-Konsole

Ressourcen

Installation

Konfiguration

Starten der Management-Konsole

Beispiele

Wie peere ich die Honeypots zum CIM?

CIM-Stack

Ressources

Systemanforderungen:

Installation

Komplette Installation

Komponentenweise Installation

Konfiguration

Docker

BrokerEndpoint:

Kibana:

Elasticsearch:

Watcher-Alerts:

Systemanforderungen Minimieren:

Wie starte ich den CIM-Stack

Kibana erreichbar unter

Wie kann ich einen SSH Tunnel zur Kibana-Oberfläche auf einem Server aufbauen?

Clone this wiki locally