endlessh-go

endlessh-go

A golang implementation of endlessh exporting Prometheus metrics, visualized by a Grafana dashboard.

Introduction

Endlessh is a great idea that not only blocks the brute force SSH attacks, but also wastes attackers time as a kind of counter-attack. Besides trapping the attackers, I also want to visualize the Geolocations and other statistics of the sources of attacks. Unfortunately the wonderful original C implementation of endlessh only provides text based log, but I do not like the solution that writes extra scripts to parse the log outputs, then exports the results to a dashboard, because it would introduce extra layers in my current setup and it would depend on the format of the text log file rather than some structured data. Thus I create this golang implementation of endlessh to export Prometheus metrics and a Grafana dashboard to visualize them.

If you want a dashboard of sources of attacks and do not mind the endlessh server, besides trapping the attackers, does extra things including: translating IP to Geohash, exporting Prometheus metrics, and using more memory (about 10MB), this is the solution for you.

Getting Started

Clone the repo then build from source:

go build .
./endlessh-go &

Alternatively, you can use the docker image:

docker run -d -p 2222:2222 shizunge/endlessh-go -logtostderr -v=1

It listens to port 2222 by default.

Then you can try to connect to the endlessh server. Your SSH client should hang there.

ssh -p 2222 localhost

If you want log like the C implementation, you need to set both CLI arguments -logtostderr and -v=1, then the log will go to stderr. You can set different log destinations via CLI arguments.

Also check out examples for the setup of the full stack.

Usage

./endlessh-go --help

…

Metrics

Endlessh-go exports the following Prometheus metrics.

Metric Type Description endlessh_client_open_count_total count Total number of clients that tried to connect to this host. endlessh_client_closed_count_total count Total number of clients that stopped connecting to this host. endlessh_sent_bytes_total count Total bytes sent to clients that tried to connect to this host. endlessh_trapped_time_seconds_total count Total seconds clients spent on endlessh. endlessh_client_open_count count Number of connections of clients. Labels:

ip: Remote IP of the client

local_port: Local port the program listens to

country: Country of the IP

location: Country, Region, and City

geohash: Geohash of the location

| | endlessh_client_trapped_time_seconds | count | Seconds a client spends on endlessh. Labels:

ip: Remote IP of the client

local_port: Local port the program listens to

|

The metrics is off by default, you can turn it via the CLI argument -prometheus_enabled.

It listens to port 2112 and entry point is /metrics by default. The port and entry point can be changed via CLI arguments.

The endlessh-go server stores the geohash of attackers as a label on endlessh_client_open_count, which is also off by default. You can turn it on via the CLI argument -geoip_supplier. The endlessh-go uses service from ip-api, which may enforce a query rate and limit commercial use. Visit their website for their terms and policies.

You could also use an offline GeoIP database from MaxMind by setting -geoip_supplier to max-mind-db and -max_mind_db to the path of the database file.

Healthcheck

The endlessh-go server exposes an HTTP health endpoint when the -healthcheck_enabled flag is set. By default it listens on 127.0.0.1:51000 at /health and returns a JSON like this:

{
      "status": "ok",
      "uptime": 123.456789012
}

status is always "ok".

uptime is the number of seconds since the server started. The host and port can be changed via -healthcheck_host and -healthcheck_port.

The docker image includes a built-in HEALTHCHECK that runs every 30 seconds.

Dashboard

The dashboard requires Grafana 8.2.

You can import the dashboard from Grafana.com using ID 15156

The dashboard visualizes data for the selected time range.

The IP addresses are clickable and link you to the ARIN database.

Contacts

If you have any problems or questions, please contact me through a GitHub issue