{"id":21502932,"url":"https://github.com/pyenb/fail2telegram","last_synced_at":"2025-07-15T23:31:01.930Z","repository":{"id":168836427,"uuid":"603047868","full_name":"Pyenb/fail2telegram","owner":"Pyenb","description":"Receive telegram notifications whenever an IP gets banned/unbanned from fail2ban.","archived":false,"fork":false,"pushed_at":"2024-05-22T10:32:39.000Z","size":51,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-22T11:41:20.950Z","etag":null,"topics":["fail2ban","fail2ban-action","fail2ban-telegram-notification","notifications","python3","telegram","telegram-bot","telegram-bot-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Pyenb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","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},"funding":{"github":"Pyenb","ko_fi":"Pyenb"}},"created_at":"2023-02-17T14:08:16.000Z","updated_at":"2024-05-22T10:32:40.000Z","dependencies_parsed_at":null,"dependency_job_id":"88af9e23-95de-465f-bd2c-b23c62dc72dd","html_url":"https://github.com/Pyenb/fail2telegram","commit_stats":null,"previous_names":["pyenb/fail2telegram"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pyenb%2Ffail2telegram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pyenb%2Ffail2telegram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pyenb%2Ffail2telegram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pyenb%2Ffail2telegram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Pyenb","download_url":"https://codeload.github.com/Pyenb/fail2telegram/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226078028,"owners_count":17570231,"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":["fail2ban","fail2ban-action","fail2ban-telegram-notification","notifications","python3","telegram","telegram-bot","telegram-bot-api"],"created_at":"2024-11-23T18:18:34.142Z","updated_at":"2024-11-23T18:18:34.683Z","avatar_url":"https://github.com/Pyenb.png","language":"Python","funding_links":["https://github.com/sponsors/Pyenb","https://ko-fi.com/Pyenb"],"categories":[],"sub_categories":[],"readme":"# fail2telegram\n\nfail2telegram is a simple action for the [fail2ban](https://github.com/fail2ban/fail2ban) project that can send telegram notifications whenever an IP gets banned/unbanned.\n\nEasy to install and easy to use.\n\n## Prerequisites\n\n- python3+\n- fail2ban installed on server\n\n## Installation\n\n### 1. Downloading\n\nUse `git clone` to download the repository to your local machine / server:\n\n```bash\n\u003e git clone https://github.com/Pyenb/fail2telegram\n```\n\nThen use the package manager [pip](https://pip.pypa.io/en/stable/) to install the packages from the `requirements.txt`.\n\n```bash\n\u003e pip3 install -r requirements.txt\n```\n\n### 2. Moving the files\n\nMove the files `telegram.py` and `telegram_config.json` into the `action.d` folder inside of your fail2ban installation location. (e.g. `/etc/fail2ban/action.d`)\n\n###### Note: If your installation location differs from the default `/etc/fail2ban/action.d`, edit the `self.installpath` variable inside the `telegram.py`\n\n### 3. Editing\n\nEdit your `jail.local` config and add the line:\n\n```\naction = telegram.py\n```\n\nto your `# JAILS`. e.g:\n\n```\n#\n# JAILS\n#\n\n[sshd]\n\nenabled = true\naction = telegram.py\nmaxretry = 5\nfindtime = 6h\nbantime = 12h\nport    = ssh\nlogpath = %(sshd_log)s\nbackend = %(sshd_backend)s\n```\n\nand save the changes of course.\n\n### 4. Telegram Bot\n\nNow we need to create a new telegram bot. For that open a new chat with [BotFather](https://telegram.me/botfather), type in the command `/newbot` and follow the instructions. In the end you should see a message like this:\n\n![success](https://i.imgur.com/ugOzB1B.png)\n\nNow copy the token to access the HTTP API and paste it into the `telegram_api_token` entry inside of the `telegram_config.json`. (Don't worry about the `telegram_chat_id`)\n\n### 5. Chatting\n\nStart a chat with your newly created bot and send a message (can be whatever).\n\n### 6. Starting\n\nRestart the fail2ban service using:\n\n```bash\n\u003e service fail2ban restart\n```\n\nand check if the bot got the chat ID using:\n\n```bash\n\u003e service fail2ban status\n```\n\nthe expected output should look something like this:\n\n![status](https://i.imgur.com/wArFf0Q.png)\n\nIf everything is working, you should start getting telegram notifications whenever someone gets banned or unbanned.\n\n![texts](https://i.imgur.com/GcAVd5R.png)\n\n###### Note: will send everyone that got banned/unbanned in the timeframe defined by `findtime` at startup. After that just new stuff.\n\n## Usage\n\nThe telegram bot will send you everything automatically. But if you only want to receive a message when an IP gets banned or unbanned (not both), edit the `telegram_config.json` again and set the variables `receive_banned` and `receive_unbanned` to `false`. Only the variables set to `true` will be send as a telegram notification. e.g:\n\n![config](https://i.imgur.com/OjWNHwl.png)\n\nAfter that just execute to reload fail2ban and load the new configuration.\n\n```bash\n\u003e service fail2ban restart\n```\n\n## Contributing\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\n## Disclaimer\nThis repository is for research purposes only, the use of this code is your responsibility.\n\nI take NO responsibility and/or liability for how you choose to use any of the source code available here. By using any of the files available in this repository, you understand that you are AGREEING TO USE AT YOUR OWN RISK. Once again, ALL files available here are for EDUCATION and/or RESEARCH purposes ONLY.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyenb%2Ffail2telegram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyenb%2Ffail2telegram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyenb%2Ffail2telegram/lists"}