# Endlessh — SSH Tarpit That Traps Attackers Indefinitely

> Endlessh is a lightweight SSH tarpit that holds brute-force attackers in an infinite SSH banner handshake, wasting their time and resources. It runs on port 22 as a decoy while the real SSH daemon listens elsewhere.

## Install

Save in your project root:

# Endlessh — SSH Tarpit That Traps Attackers Indefinitely

## Quick Use
```bash
# Build from source
git clone https://github.com/skeeto/endlessh.git
cd endlessh && make
# Run on port 2222 (move real SSH elsewhere first)
./endlessh -p 2222 -v
```

## Introduction
Endlessh exploits a quirk in the SSH protocol: the server can send an arbitrarily long banner before authentication begins. Endlessh sends one random line every few seconds, trapping bots and scanners in an endless handshake that never completes.

## What Endlessh Does
- Listens on an SSH port and sends an infinite, slowly dripping banner to any connecting client
- Traps automated SSH scanners and brute-force bots, consuming their connection slots
- Runs with minimal resources: a single thread handles thousands of trapped connections
- Logs connection statistics including client IP, duration, and bytes sent
- Operates as a systemd service for unattended deployment on servers

## Architecture Overview
Endlessh is a single-file C program using epoll (Linux) or kqueue (BSD/macOS) for efficient I/O multiplexing. It maintains a list of trapped connections and periodically writes a random line to each. Connections that close are reaped and logged. The entire program compiles to a small static binary with zero dependencies beyond libc.

## Self-Hosting & Configuration
- Compile with `make` on any POSIX system; no external libraries needed
- Configure via command-line flags: `-p` for port, `-d` for delay between lines, `-m` for max clients
- Deploy as a systemd service using the included unit file
- Move your real SSH daemon to a non-standard port and point Endlessh at port 22
- Docker image available as `shizunge/endlessh-go` (Go rewrite with Prometheus metrics)

## Key Features
- Extremely low resource usage: holds thousands of connections with minimal CPU and memory
- Single-file C source with no dependencies for easy auditing and compilation
- Configurable line delay (default 10 seconds) and maximum concurrent client limit
- Compliant with RFC 4253: the banner is technically valid SSH protocol
- endlessh-go fork adds Prometheus metrics, GeoIP logging, and Grafana dashboards

## Comparison with Similar Tools
- **fail2ban** — bans IPs after failed login attempts; Endlessh wastes attacker time before they even attempt login
- **DenyHosts** — similar to fail2ban with SSH focus; Endlessh is complementary, not a replacement
- **Cowrie** — full SSH honeypot that logs attacker commands; Endlessh is lighter and does not emulate a shell
- **sshguard** — blocks brute-force attacks via firewall rules; Endlessh passively traps rather than actively blocking
- **Port knocking** — hides SSH behind a knock sequence; Endlessh is a decoy that actively wastes attacker resources

## FAQ
**Q: Does Endlessh affect legitimate SSH users?**
A: No, if configured correctly. Move your real SSH daemon to another port and only expose Endlessh on port 22. Legitimate users connect to the real port.

**Q: How many connections can it handle?**
A: Thousands. The default limit is 4096 concurrent connections, adjustable with `-m`. Each trapped connection consumes only a file descriptor and a few bytes of memory.

**Q: Does it actually reduce attacks?**
A: It ties up attacker connections, slowing their scan rate. Over time, some scanners mark the IP as unresponsive. It is most effective alongside other defenses like fail2ban.

**Q: Is there a version with metrics?**
A: Yes. The endlessh-go fork by shizunge adds Prometheus metrics and GeoIP data for monitoring trapped connections in Grafana.

## Sources
- https://github.com/skeeto/endlessh
- https://nullprogram.com/blog/2019/03/22/

---
Source: https://tokrepo.com/en/workflows/asset-bf419917
Author: AI Open Source