{"id":18998770,"url":"https://github.com/foxxmd/endlessh-notify","last_synced_at":"2025-04-13T03:08:32.801Z","repository":{"id":221760367,"uuid":"755177386","full_name":"FoxxMD/endlessh-notify","owner":"FoxxMD","description":"Event notification for endlessh and endlessh-go","archived":false,"fork":false,"pushed_at":"2024-12-05T13:34:28.000Z","size":632,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-13T03:08:25.068Z","etag":null,"topics":["discord-webhook","docker","endlessh","gotify","honeypot","mapquest","notifications","ntfy","ssh"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FoxxMD.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-09T15:32:11.000Z","updated_at":"2025-02-18T09:02:15.000Z","dependencies_parsed_at":"2024-11-08T17:50:52.855Z","dependency_job_id":null,"html_url":"https://github.com/FoxxMD/endlessh-notify","commit_stats":null,"previous_names":["foxxmd/endlessh-notifications"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FoxxMD%2Fendlessh-notify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FoxxMD%2Fendlessh-notify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FoxxMD%2Fendlessh-notify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FoxxMD%2Fendlessh-notify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FoxxMD","download_url":"https://codeload.github.com/FoxxMD/endlessh-notify/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248657918,"owners_count":21140846,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discord-webhook","docker","endlessh","gotify","honeypot","mapquest","notifications","ntfy","ssh"],"created_at":"2024-11-08T17:47:52.526Z","updated_at":"2025-04-13T03:08:32.783Z","avatar_url":"https://github.com/FoxxMD.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# endlessh-notify\n\n[![Latest Release](https://img.shields.io/github/v/release/foxxmd/endlessh-notify)](https://github.com/FoxxMD/endlessh-notify/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Docker Pulls](https://img.shields.io/docker/pulls/foxxmd/endlessh-notify)](https://hub.docker.com/r/foxxmd/endlessh-notify)\n\nEvent notification for [endlessh](https://github.com/skeeto/endlessh) and [endlessh-go](https://github.com/shizunge/endlessh-go)\n\n\u003cimg src=\"/assets/discord-accept.jpg\" width=\"449\"\u003e \u003cimg src=\"/assets/discord-close.jpg\" width=\"447\"\u003e\n\n\u003c!-- TOC --\u003e\n* [What Does It Do?](#what-does-it-do)\n* [Prerequisites](#prerequisites)\n* [Quick Start](#quick-start)\n* [Install](#install)\n  * [Docker](#docker)\n      * [Logs Mount](#logs-mount)\n      * [Config Mount](#config-mount)\n      * [Linux Host](#linux-host)\n    * [Full Example](#full-example)\n  * [Local (Node)](#local-node)\n* [Configuring Endlessh](#configuring-endlessh)\n    * [endlessh](#endlessh)\n    * [endlessh-go](#endlessh-go)\n* [Configuring Notifiers](#configuring-notifiers)\n    * [Debounce Interval](#debounce-interval)\n    * [Event Types](#event-types)\n      * [Event Filters](#event-filters)\n  * [Specific Notifiers](#specific-notifiers)\n    * [Discord](#discord)\n    * [Ntfy](#ntfy)\n    * [Gotify](#gotify)\n\u003c!-- TOC --\u003e\n\n# What Does It Do?\n\nendlessh-notify tails the logs from your endlessh instance and will send notifications using [Discord webhooks](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks), [ntfy](https://ntfy.sh/), and [gotify](https://gotify.net/) when any of these events occurs:\n\n* New* IP tries to connect\n* New* IP disconnect\n\n*You can control how an IP is considered \"new\" based on when it was [last seen](#debounce-interval).\n\n# Prerequisites\n\n* A running [endlessh](https://github.com/skeeto/endlessh) or [endlessh-go](https://github.com/shizunge/endlessh-go) instance **with file logging enabled.**\n  * Access to log files\n* A [Discord webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks), running [ntfy](https://ntfy.sh/) instance, or running [gotify](https://gotify.net/) instance\n\n# Quick Start\n\nAssuming:\n\n* Using docker\n* Endlessh log files are located at `/home/user/endlessLogs` on your host system\n* A discord webhook `https://discord.com/api/webhooks/MY_WEBHOOK`\n* Notify if IP from event hasn't been seen before or was last seen more than 24 hours ago\n\n```shell\ndocker run -d -e DISCORD_WEBHOOK=\"https://discord.com/api/webhooks/MY_WEBHOOK\" -e DEBOUNCE_INTERVAL=\"1 day\" -v /home/user/endlessLogs:/endlessh foxxmd/endlessh-notify\n```\n\n# Install\n\n## Docker\n\n* [Dockerhub](https://hub.docker.com/r/foxxmd/endlessh-notify) - `docker.io/foxxmd/endlessh-notify`\n* [GHCR](https://github.com/foxxmd/endlessh-notify/pkgs/container/endlessh-notify) - `ghcr.io/foxxmd/endlessh-notify`\n\n(Optionally) Set the [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for the container using the environmental variable `TZ` ([docker](https://docs.docker.com/engine/reference/commandline/run/#env)) ([docker-compose](https://docs.docker.com/compose/compose-file/compose-file-v3/#environment))\n\n#### Logs Mount\n\nYou **must** bind the directory on the host containing the endlessh log files to `/endless` in the container.\n\n* [Using `-v` method for docker](https://docs.docker.com/storage/bind-mounts/#start-a-container-with-a-bind-mount): `-v /path/on/host/logs:/endlessh`\n* [Using docker-compose](https://docs.docker.com/compose/compose-file/compose-file-v3/#short-syntax-3): `- /path/on/host/logs:/endlessh`\n\n#### Config Mount\n\nIf you use a [Config file](#configuring-notifiers) you must bind the directory on the host containing the config file to `/config` in the container\n\n* [Using `-v` method for docker](https://docs.docker.com/storage/bind-mounts/#start-a-container-with-a-bind-mount): `-v /path/on/host/config:/config`\n* [Using docker-compose](https://docs.docker.com/compose/compose-file/compose-file-v3/#short-syntax-3): `- /path/on/host/config:/config`\n\n#### Linux Host\n\nIf you are\n\n* using [rootless containers with Podman](https://developers.redhat.com/blog/2020/09/25/rootless-containers-with-podman-the-basics#why_podman_)\n* running docker on MacOS or Windows\n\nthis **DOES NOT** apply to you.\n\nIf you are running Docker on a **Linux Host** you must specify `user:group` permissions of the user who owns the **configuration directory** on the host to avoid [docker file permission problems.](https://ikriv.com/blog/?p=4698) These can be specified using the [environmental variables **PUID** and **PGID**.](https://docs.linuxserver.io/general/understanding-puid-and-pgid)\n\nTo get the UID and GID for the current user run these commands from a terminal:\n\n* `id -u` -- prints UID\n* `id -g` -- prints GID\n\n### Full Example\n\nAssuming\n\n* Host UID is `99`\n* Host GID is `100`\n* Config using ENV\n* Discord with Mapquest\n* Logs at `/home/myUser/endlessLogs`\n\n\n```shell\ndocker run -d -e PUID=99 PGID=100 -e DISCORD_WEBHOOK=\"https://discord.com/api/webhooks/MY_WEBHOOK\" -e MAPQUEST_KEY=\"V3CPFmir2JEnj\" -v /home/myUser/endlessLogs:/endlessh foxxmd/endlessh-notify\n```\n\n* Using config-file instead of ENVs\n\n```shell\ndocker run -d -e PUID=99 PGID=100 -v /home/myUser/endlessh-notify-config:/config  -v /home/myUser/endlessLogs:/endlessh foxxmd/endlessh-notify\n```\n\n## Local (Node)\n\n```shell\nclone https://github.com/FoxxMD/endlessh-notify.git .\ncd endlessh-notify\nnpm install\nnpm run start\n```\n\nLocal install may also use ENVs instead of config files. Directory locations are controlled with ENVs:\n\n* `CONFIG_DIR` =\u003e Default `./config` =\u003e Directory location of endlessh-notify config\n* `ENDLESS_DIR` =\u003e Default `./endlessData` =\u003e Directory location of endlessh logs\n\n# Configuring Endlessh\n\nendlessh-notify parses events using log files generated by endlessh. **You must enable file logging on your instance for endlessh-notify to work.**\n\n### [endlessh](https://github.com/skeeto/endlessh)\n\n* If using [Linuxserver.io](https://docs.linuxserver.io/images/docker-endlessh/#application-setup) version add ENV `LOGFILE=true` to your run command\n* Using endlessh directly -- add `-s` to command output and setup a [config file](https://github.com/skeeto/endlessh#sample-configuration-file) with `LogLevel 1`\n\n### [endlessh-go](https://github.com/shizunge/endlessh-go)\n\nAdd these arguments to your run command (make sure `log_dir` is a viable directory):\n\n```\n-alsologtostderr -v=1 -log_dir=/config\n```\n\n# Configuring Notifiers\n\nendlessh-notify can have one or many **Notifiers.** Each Notifier has its own defined behavior on how to handle events parsed from endlessh.\n\nNotifiers can be configured with\n\n* **environmental variables** outlined in the sections below\n* using a **config file**, see [`config.yaml`](/config/config.yaml.example) for a kitchensink example\n\nCommon behavior that can be defined for all notifiers:\n\n### Debounce Interval\n\nThis duration determines how \"old\" a previously seen IP must be before it is considered \"new\". If an IP has not been seen before it is always new. The default is `1 day`.\n\nThe syntax for a duration is `[Value] [Unit]` where unit is any [available unit from Dayjs](https://day.js.org/docs/en/durations/creating#list-of-all-available-units), examples:\n\n* `18 minutes`\n* `1 hour`\n* `4 days`\n\nDebounce can be configured:\n\n* For all notifiers using ENV =\u003e Set with `DEBOUNCE_INTERVAL` env IE `DEBOUNCE_INTERVAL=\"6 hours\"`\n* Per notifier using a config file =\u003e sSee [`config.yaml` example](/config/config.yaml.example)\n\n### Event Types\n\nEach notifier can be configured to notify on one or many **Events.** An Event can be:\n\n* **Accept** -- When an IP establishes a connection with endlessh\n* **Close** -- When an IP disconnects from endlessh\n\nFor notifiers that **do not have any events configured via a config file** the type of events that are notified can be configured through ENV:\n\n```\nNOTIFY_EVENTS=accept,close\n```\n\nTo control behavior for individual notifiers or event behavior use a file config, see [`config.yaml` example](/config/config.yaml.example)\n\n#### Event Filters\n\nAdditionally, Events can be filtered based on stats for the individual Event or overall for the running session of endless-notify.\n\n* Accept\n  * `maxTotalConnections` - Notify if total connections by IP is less than this\n  * `minTotalConnections` - Notify if total connections by IP is more than this\n* Close\n  * `maxTotalConnections` - Notify if total connections by IP is less than this\n  * `minTotalConnections` - Notify if total connections by IP is more than this\n  * `maxTrappedTime` - Notify if event trapped time was less this\n  * `minTrappedTime` - Notify if event trapped time was more than this\n  * `maxTotalTrappedTime` - Notify if total trapped time for IP was less than this\n  * `minTotalTrappedTime` - Notify if total trapped time for IP was more than this\n\n## Specific Notifiers\n\n### Discord\n\nCreate a [webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) for a Discord server you have proper permissions for.\n\nOptionally, get a [Mapquest Key](https://developer.mapquest.com/documentation/) for endless-notify to generate map images of approximate IP locations in the Discord message.\n\n\n|        Name         | Required | Default |                Description                |\n|---------------------|----------|---------|-------------------------------------------|\n| `DISCORD_WEBHOOK`   | **Yes**  |         |                                           |\n| `MAPQUEST_KEY`      | No       |         | Used to generate map image of IP location |\n| `DEBOUNCE_INTERVAL` | No       | 1 hour  |                                           |\n\n\nOr see [`config.yaml` example](/config/config.yaml.example)\n\n### Ntfy\n\n|        Name         | Required | Default | Description |\n|---------------------|----------|---------|-------------|\n| `NTFY_URL`          | **Yes**  |         |             |\n| `NTFY_TOPIC`        | **Yes**  |         |             |\n| `NTFY_USER`         | No       |         |             |\n| `NTFY_PASS`         | No       |         |             |\n| `DEBOUNCE_INTERVAL` | No       | 1 hour  |             |\n\nOr see [`config.yaml` example](/config/config.yaml.example)\n\n### Gotify\n\n|        Name         | Required | Default | Description |\n|---------------------|----------|---------|-------------|\n| `GOTIFY_URL`        | **Yes**  |         |             |\n| `GOTIFY_TOKEN`      | **Yes**  |         |             |\n| `DEBOUNCE_INTERVAL` | No       | 1 hour  |             |\n\nOr see [`config.yaml` example](/config/config.yaml.example)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoxxmd%2Fendlessh-notify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoxxmd%2Fendlessh-notify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoxxmd%2Fendlessh-notify/lists"}