Setting Up an SSH Honeypot with Endlessh: A Complete Guide

Trapping the Bots: How to Set Up an Endlessh SSH Tarpit

If you run a server connected to the internet, you’re familiar with the constant, mindless drumbeat of automated SSH scanners. These bots, often called “script kiddies,” relentlessly probe port 22, trying common usernames and passwords in a bid to gain access. It’s noise, it’s annoying, and it can be a real security risk.

What if you could fight back, not by blocking them, but by trapping them? What if you could waste their time, consume their resources, and distract them from your actual services?

Enter the world of the SSH tarpit, and a fantastic tool called Endlessh.

What is Endlessh?

Endlessh is not a traditional honeypot that logs credentials. It’s something cleverer and simpler. It’s an SSH tarpit that mimics an SSH server just enough to get a connection, and then it… does nothing. Very, very slowly.

When a client connects, Endlessh sends an endless, random SSH banner, character by character, with a configurable delay between each character. The attacker’s client gets stuck, waiting for a banner that never completes. They can be trapped for hours, or even days, completely oblivious.

The best part? Since this all happens before any cryptographic exchange, Endlessh is incredibly lightweight. It’s a simple, single-threaded C program with no heavy dependencies.

The Strategy: Bait and Switch

The most effective way to use Endlessh is to use it as bait. You move your real SSH server to a non-standard port (e.g., 2222) and then run Endlessh on the standard port 22. The automated bots will flock to port 22 and get stuck in the tar, while legitimate users (who you’ve told the new port to) can connect without any issues.

Step 1: Getting and Building Endlessh

Endlessh is easy to compile from source. First, grab the code from the official repository:

git clone https://github.com/skeeto/endlessh.git
cd endlessh

Now, you can build it with a simple make command:

make

This will create an executable file named endlessh.

Building on Special Systems

The source documentation notes a few quirks for less common systems:

RHEL 6 / CentOS 6: If you’re on an older system with glibc older than 2.17, you’ll need to link against librt:
```
make LDLIBS=-lrt
```
Solaris / illumos: These systems require a few extra libraries:
```
make CC=gcc LDLIBS='-lnsl -lrt -lsocket'
```
OpenBSD: The man page path is different. You’ll need to slightly modify the Makefile as shown in the project’s documentation.

Step 2: Running Endlessh - The Basics

Let’s start with a simple test run. To bind to a privileged port like 22, you’ll need root privileges.

sudo ./endlessh -v -p 2222

-v: This enables verbose logging so you can see what’s happening.
-p 2222: We’re telling it to listen on port 2222 for this test.

Now, open another terminal and try to SSH to this port:

ssh localhost -p 2222

You’ll see your SSH client hang, and in the Endlessh terminal, you’ll see a log message like new connection from .... Your client is now trapped! Press Ctrl+C in the Endlessh terminal to stop it.

Step 3: Configuration and Best Practices

Using command-line flags is fine for testing, but for a proper setup, a configuration file is much cleaner.

Move Your Real SSH Server: Edit your real SSH daemon’s configuration file (/etc/ssh/sshd_config) and change the port:
```
# Port 22
Port 2222
```
Then restart the SSH service (sudo systemctl restart sshd or sudo service ssh restart). Warning: Make sure you can connect on the new port before you close your current session!

Create an Endlessh Config: Create a configuration file at /etc/endlessh/config. The syntax is simple and similar to OpenSSH’s.

# /etc/endlessh/config
# Listen on the standard SSH port to trap bots
Port 22

# Delay in milliseconds between banner characters.
# 10 seconds is a good starting point.
Delay 10000

# Max line length of the random banner.
MaxLineLength 32

# Maximum number of clients to trap simultaneously.
MaxClients 4096

# Log level: 0=Quiet, 1=Standard, 2=Verbose
LogLevel 1

# Log to syslog instead of stdout
Syslog true

Run Endlessh with the Config: Now you can run Endlessh by pointing it to the config file:
```
sudo ./endlessh -f /etc/endlessh/config
```

Step 4: Running as a Service (systemd)

To ensure Endlessh runs continuously and starts on boot, you should run it as a system service.

Create a new systemd service file: sudo nano /etc/systemd/system/endlessh.service

Paste the following configuration into the file. This assumes you’ve placed the endlessh binary in /usr/local/bin and your config in /etc/endlessh/config.

[Unit]
Description=Endlessh SSH Tarpit
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/endlessh -f /etc/endlessh/config
Restart=always
User=nobody
Group=nogroup

# Hardening options
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_BIND_SERVICE
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/log

[Install]
WantedBy=multi-user.target

Reload the systemd daemon, enable, and start the service:

sudo systemctl daemon-reload
sudo systemctl enable endlessh.service
sudo systemctl start endlessh.service

You can check its status with sudo systemctl status endlessh.service and view its logs with sudo journalctl -u endlessh.service -f.

Monitoring Your Tarpit

With LogLevel 1 enabled in your config, Endlessh will log new connections to syslog. You can watch the bots get stuck in real-time:

sudo journalctl -u endlessh.service -f

You’ll see output like this, showing the IP address of each trapped client:

Oct 26 15:30:01 myserver endlessh[1234]: connection from 123.45.67.89:51234
Oct 26 15:31:15 myserver endlessh[1234]: connection from 203.0.113.10:55231

You can use these logs to identify persistent scanners and add them to your firewall’s blocklist.

Final Thoughts

Endlessh is a beautifully simple and effective tool for turning the tables on automated scanners. It’s low-maintenance, consumes minimal resources, and provides a small dose of satisfaction as you watch the bots get stuck.

Just remember: it’s a tarpit, not a full-featured honeypot. It won’t capture credentials or complex attack vectors. Its goal is simple: to waste time. And at that task, it is endlessly brilliant.