Honeygrove User Guide

About Honeygrove

Honeygrove is a modular honeypot written in python, consisting of multiple service interfaces. The interactions of an attacker with this services are logged and can be sent via Broker (optional).

Requirements

Ressources

Honeygrove originally was tested on a Raspberry Pi 3 Model B with Quad Core CPU (1.2 GHz) and 1 GB RAM, but limitations should be expected.

Operating System

Honeygrove was tested on the following Operating Systems:

• Ubuntu 16.4
• Debian 9.1

It could work on other distributions, too. If Broker is unavailable on your platform, you can disable the use of it, but then no communication with the monitoring stack or management-console will be possible.

Packages

The following packages will be installed during installation process:

• Twisted 17.5.0
• Broker (pybroker /mfischer/broker-multihop)
• Python 3 or higher

For a complete list of dependencies that will be installed, you can look at honeygrove_install. The dependencies will be installed via apt and pip3.

Installing honeygrove

• clone the repository or download and unzip it
• copy the /honeygrove directory where you want to install honeygrove (a link to /usr/bin can optionally be created automatically at the end of installation process)
• run honeygrove_install with root privileges to install all dependencies
• during installation process, choose if you want to install broker
• remember to look at config.py before you start honeygrove for the first time

Configuration

All configuration is done in config.py. Changes will be effective after restarting honeygrove.sh. To change settings of the running honeypot, the management-console must be used.

configurable variable	Description
HPID	identifies the honeypot
machine_name	host name that is used in the services (this has nothing to do with the real host name)
hp_description	describe your honeypot (e.g. location)
resources	path to the directory for various resources for the honeypot
logpath	path of the local log file
geodatabasepath	relative path (from given resources-directory, see above) to the database containing location informations regarding IP addresses
use_broker	set to "True" to use the "BrokerEndpoint" for communication with the EKStack and the management-console
use_geoip	set to "True" to use geo location lookup for ip addresses in log events, you must set the path to the database containing the information in geodatabasepath, see above
print_status	print to sdtout: includes INFO-, HEARTBEAT, RESPONSE- and ERROR-messages
print_alerts	print to stdout: includes LOGIN-, REQUEST-, FILE- and SYN-messages
log_status	write to logfile: includes INFO-, HEARTBEAT, RESPONSE- and ERROR-messages
log_alerts	write to logfile: includes LOGIN-, REQUEST-, FILE- and SYN-messages
listenServicePorts	ports on wich the "ListenService" should listen
listenServiceName	name of the "ListenService"
tcpFlagSnifferName	name of the "TcpFlagSniffer"
httpResponseHeader	header that will be send during a http response
httpHTMLDictionary	dictionary of the supported pages
httpResources	path to the resources for the "HTTPService"
httpPort	port on wich the "HTTPServive" should listen
httpName	name of the "HTTPService"
sshPort	port on wich the "SSHService" should listen
sshName	name of the "SSHService"
ssh_real_shell	if set to "True", all commands will be executed in the real shell of the host. The host system will be accessible by attackers.
SSH_conn_per_host	number of max. allowed concurrent SSH connections per host address, prevent hosts from opening too many shells
ftpPort	port on wich the "FTPService" should listen
ftpName	name of the "FTPService"
FTP_conn_per_host	number of max. allowed concurrent FTP connections per host address, prevent hosts from opening too many shells
path_to_filesys	path to the xml-filesystem, used by services with FilesystemParser
tokendir	path to the files that should be visible in the fake filesystem
tokenDatabase	path to the database containing the accepted login credentials
honeytokendbGenerating	dictionary of services that can create Honeytokens
honeytokendbProbabilities	dictionary of probabilities regarding the generation of honeytokens (see above)
sshAcceptsFiles	set to "True" to allow the "SSHService" to accept Files (e.g. via wget)
ftpAcceptsFiles	set to "True" to allow the "FTPService" to accept Files (e.g. via put)
quarantineDir	path to the directory, where the received files should be written
startupList	list of names of services, that should be started automatically on startup of honeygrove
noPortSpecificService	list of names of services, that are allowed to listen on multiple ports
tcpTimeout	time after that a SYN answered with a SYN/ACK will be considered as scan
BrokerComIp	address on wich the Broker Endpoint should listen
BrokerComPort	port on wich the Broker Endpoint should listen
init_peer	set to "True": BrokerEndpoint will initially peer with given address and port (see below). Use this if no management-console is available.
init_peer_ip	the address of the initial peering of the BrokerEndpoint
init_peer_port	the port of the initial peering of the BrokerEndpoint
honeygrove_start	set to "active": Services that are listed in startupList will be started automatically

Starting Honeygrove

Run honeygrove.sh with root privileges. If print_status or print_alerts is enabled, honeygrove will print to stdout. You can pipe the output to a file or use the output otherwise. Disable print_status and print_alerts to only write to file given in logpath.

Use cases of the services

SSH

You can connect to the "SSHService" of the honeypot simply via ssh <username>@<host> -p <portnumber>. You can look at the HoneytokenDB to test the login with accepted credentials.

FTP

You can connect to the "FTPService" of the honeypot using ftp, followed by the command open <host> <portnumber>. You can look at the HoneytokenDB to test the login with accepted credentials.

HTTP

One way to connect to the "HTTPService" is via your web browser. You can display the saved site via: <host>:<port>/<site>. New sites can be added through the management-console or by copying the file into the directory given in httpResources.