Quick Start
In this quick start, we’ll start a HoneyTrap with the help of Docker. We will start a Docker container with an image of Honeytrap, automatically downloaded from the docker hub.
The configuration file we’ll use for this quick start is described in the Basic config section. We’ll concentrate on implementing only one service, a ssh-simulator with only one channel, the console.
Step 1: Get Docker
To check if you have Docker type the following in a terminal window:
> docker -vThis should show the version of Docker you currently have.
Step 2: Start HoneyTrap
In a terminalwindow type:
> docker run -p 8022:8022 honeytrap/honeytrap:latestThis pulls the latest version of the HoneyTrap docker and publishes port 8022 to the host.
If you get a message starting with:
docker: Got permission denied while trying to connect to the Docker daemon socketYou need sudo-permission, run the command with prefix sudo.
Step 3: Test your HoneyTrap
Keep the container running, and open a new terminal window to simulate a ssh connection attempt.
Open a new terminal and enter this command:
> ssh -p 8022 root@127.0.0.1The following message should be displayed:
The authenticity of host '[127.0.0.1]:8022 ([127.0.0.1]:8022)' can't be established.
RSA key fingerprint is SHA256:************************************.
Are you sure you want to continue connecting (yes/no)?Answer by typing ‘yes’.
You are now asked for the password of the root user which is ‘password’ if you did not change the configuration file.
> root@127.0.0.1's password:You should now see the ssh motd indicating you successfully logged in and this prompt:
> root@host:~$Every command entered into the ssh-simulator will now be logged in your console.
What just happened?
A little explanation on what just happened if you followed all previous steps.
You may have a look at the basic config used to start this HoneyTrap. This could help you for a better understanding of the following sections.
The Docker command explained:
> docker run -p 8022:8022 honeytrap/honeytrap:latestWhat happened when you entered this command?
# This will start a new docker container.
docker run
# -p xxxx:yyyy will expose the internal port yyyy of the container to the port xxxx of the host interface.
-p 8022:8022
# image:tag Image created by HoneyTrap developers from which the container will be derived. The tag can be seen as a "version" of the image.
honeytrap/honeytrap:latestWhen you run this command, Docker starts a container derived from the image honeytrap/honeytrap:latest.
In the config file used to run the HoneyTrap Server, only one service is declared: the ssh-simulator, to the port 8022 of the container. That’s why we wrote “-p xxxx:8022”.
Then, we decided to “link” the port 8022 of our host interface to this port 8022 of the container. That’s what we meant by “expose the internal port yyyy to the port of the host xxxx interface”.
If we want to “open” the port 8023 of our host interface instead of 8022, we just need to use “-p 8023:8022”.
The result is a Docker-container running HoneyTrap with a ssh-simulator.
This HoneyTrap explained:
When HoneyTrap starts, you should see something similar to this:
2018/09/11 08:53:07 Using config file /config/config.toml
Honeytrap starting (bebo4sshmp500090i230)...
Version: 2018-08-14T18:04:25Z (32d1df97390a)
08:53:07.953 honeytrap/server ▶ DEBU 002 Using datadir: /data
08:53:11.170 services ▶ DEBU 004 Could not load private-key, generating one.
08:53:11.341 honeytrap/server ▶ INFO 005 Configured service ssh-simulator (ssh-simulator)
08:53:11.341 honeytrap/server ▶ INFO 007 Configured port tcp/:8022
08:53:11.342 listeners/socket ▶ INFO 00b Listener started: tcp/:8022Honeytrap needs a config file to start. In this example, the config file is provided by the Dockerfile.
2018/09/11 08:53:07 Using config file /config/config.tomlWhen HoneyTrap succesfully starts:
Honeytrap starting (bebo4sshmp500090i230)...“bebo4sshmp500090i230” represents a token to identify this HoneyTrap-deployment. (Your token is different.)
This is the release date of the version of HoneyTrap used to build the docker image and the first 12 characters from the last commit id.
Version: 2018-08-14T18:04:25Z (32d1df97390a)This is a DEBUG event. We have this event because in the config file, we declared we want this minimum level. It informs us about the path used to store data.
08:53:07.953 honeytrap/server ▶ DEBU 002 Using datadir: /dataAs you can see with the services ▶, this event concern our unique service, ssh-simulator which needs a RSA Key.
Since HoneyTrap could not find one in the storage it created one.
08:53:11.170 services ▶ DEBU 004 Could not load private-key, generating one.These two lines inform us that our service and the associated port are well-configured.
08:53:11.341 honeytrap/server ▶ INFO 005 Configured service ssh-simulator (ssh-simulator)
08:53:11.341 honeytrap/server ▶ INFO 007 Configured port tcp/:8022Lastly, this line inform us with listeners/socket ▶ that HoneyTrap opened the port tcp/:8022.
08:53:11.342 listeners/socket ▶ INFO 00b Listener started: tcp/:8022Every 30 seconds, an event called “heartbeat” is logged. Check heartbeat for more informations.
honeytrap > heartbeat > category=heartbeat, date=...The SSH Simulator
What happened when we did:
> ssh -p 8022 root@127.0.0.1As soon as HoneyTrap detects a connection attempt, it sends an event to the channel configured in the config file:
services > ssh > category=ssh, date=2018-10-08 17:33:54.895403 +0200 CEST m=+30.350666354,
destination-ip=127.0.0.1, destination-port=8023, sensor=services, source-ip=127.0.0.1,
source-port=55128, ssh.publickey-type=ssh-rsa,
[...]
ssh.username=root, token=betnhh004aci7got46pg, type=publickey-authenticationYou can find more informations about the fields of the events in events/events.
The client will initiate a SSH handshake with the HoneyTrap to establish a connection.
The HoneyTrap Server will complete the SSH Handshake and will prompt a ssh shell.
Therefore, for each command sent by the client, all the data will be logged and forward to the channel.