Package: egenix-telegram-antispam-bot
eGenix Antispam Bot for TelegramThis bot package provides a simple, yet effective way to deal with spam
signups toTelegram Messenger(TG) groups.
Unfortunately, these have grown to a level that is not manually
manageable anymore (seeMotivationbelow for details).FeaturesLow impact mode of operation: the bot tries to keep noise in the group
to a minimumSeveral challenge mechanisms to choose from, more can be added as
neededFlexible and easy to use configurationOnly needs a few MB of RAM, so can easily be put into a container or run
on a Raspberry PiCan handle quite a bit of load due to the async implementationRequirementsPython 3.9+pyrogrampackage (see
requirements.txt)only tested on LinuxPreparationIn order to run the bot and connect it to your TG group(s), you will
first have to get API tokens from TG. Please seehttps://core.telegram.org/api/obtaining_api_id#obtaining-api-idfor
details on how to obtain the two credentials API ID and hash.⚠️ The API credentials are bound to the TG account you create them with and
can be used to even delete the account, so keep them safe.Next, you need to register a bot with TG. This can be done by chatting
with the TG BotFather. Seehttps://core.telegram.org/bots#3-how-do-i-create-a-botfor details. The
BotFather will send you a Bot token.InstallationIt is best to install the bot inside avenv. You can use the
virtual env tool of your choice to set this up.Then install thePyPI
package, using
pip:pip3installtelegram_antispam_botInstallation using DockerIf you want to run the bot using Docker, have a look at thedocker/subdir in the source distribution. After configuring the bot indocker/config/tgbot_envyou can then run the bot by running:cddocker/
docker-composeup-dBe sure to check the logs usingdocker-compose tgbot logsfor any
errors that may occur. You can also without "-d" (no detach) to see the
logs written to the console for testing purposes.ConfigurationThe simplest way to configure the bot is via OS environment variables
(env vars), but you can also put the configuration into a Python modulelocal_config.pywhich Python can find on the sys.path. Seetelegram_antispam_bot/config.pyfor details.We'll go with the env var approach. All env vars use the prefix "TG_" to
avoid getting in the way with other env vars.The most important variables to set are these:TG_API_ID: Use the API ID you received from TG.TG_API_HASH: Use the API hash you received from TG. This is secret
information.TG_BOT_TOKEN: Use the Bot token you received from the BotFather.  This
is secret information.TG_SESSION_NAME: Session database name to use. Defaults to
'antispambot'. You only need to set this in case you plan to run
multiple bot instances from the same directory.Limiting the attack surfaceYou only need to pass in the real values of the authentication env vars
when first authenticating against the TG API.The underlying pyrogram package will store the session credentials in a
SQLite database (named afterTG_SESSION_NAME).Once this is in place, the secrets can be replaced with dummy values or
left unset. Do take care to protect the session database, since this can
be used to hijack TG sessions. The bot will enforce file permissions
upon startup.Additional settingsYou can also specify a few other env vars to further customize the
installation:TG_MANAGEMENT_GROUP_ID: Set this to the TG ID of the group you want to
use for receiving admin log messages. The bot will have to be made
member of this group. The bot will always log these messages to
stdout.TG_MODERATION_GROUP_IDS: Set this to a comma separated set of group
IDs to moderate. If not set, the bot will moderate all groups it gets
added to as an admin.TG_DEBUG: Set this to 1 to get debug messages, which will include
details about the messages sent to chats the bot is listening on.TG_CHALLENGES: Set this to a comma separated list of Challenge
subclass names found intelegram_antispam_bot/challenge.py. The bot
will then pick one of these randomly when sending a challenge.Getting the group IDs is not easy from the TG clients, but you can use
theTG_DEBUGsetting to find out the IDs. The log will show entries
such aschat=pyrogram.types.Chat(id=1234, type='supergroup', ...when writing messages into the group chat. In this example, the
group ID to use is 1234.It is usually best to configure the extra settings after getting the
initial setup up and running.For more details regarding the configuration and additional settings,
please have a look at thetelegram_antispam_bot/config.pyfile.Running the BotYou can run the bot inside a container, as a service on a root server or
VM, or manually from the command line.If you've setup the configuration via OS environment variables, all you
need to do is run the package:python3-mtelegram_antispam_botAdding the Bot to a TG GroupIn order for the bot to work on a group, you will have to add it as an
admin to the group. It needs the permissionsDelete messagesandBan
users. The other permissions can be disabled.Bot commandsUnlike other TG bots, this bot does not implement any bot commands (e.g.
there is no '/help').Experience has shown that implementing such commands often leads to
group members trying to interact with the bot, even though they don't
have permission to do anything. This usually creates enough noise to
make the bot operation less useful.How it worksThe bot will recognize new group signups and ask the new users to enter
a challenge string within a certain time frame. Correctly entering the
challenge then accepts the new user. Not entering the challenge in time
results in a ban. The same happens, if the user enters too many wrong
answers.The bot / user conversation is mostly deleted after either successful or
failed signup to keep the noise level low.FAQI see connection error messages in the logs. Are those something to worry about ?No, the underlying pyrogram library will automatically try to
reconnect. You should only dig deeper in case you notice that the
bot is not reacting to new signups.I changed the configuration. Will the bot automatically detect those changes ?No, you will have to restart the bot for the changes to take affect.Will restarting the bot have a negative effect ?A short downtime is not much of a problem. If you restart the bot
while it is talking to a new signup, you will have to do manual
cleanup of the chat, since the conversations are not stored in the
database.I don't want to monitor a log file. Can I point the bot to an admin TG group ?Yes, you can set up a TG admin group, make the bot a (regular) member
and then add the ID of the group asTG_MANAGEMENT_GROUP_ID.MotivationeGenix has long been running a local user group meeting in Düsseldorf
called Python Meeting Düsseldorf and we have been using a Telegram group
for group communication.In the early days, the group worked well and we only had few spammers
joining it, which we could well handle manually. More recently, this has
changed dramatically. We are seeing between 2-5 spam signups per day,
often at night. Furthermore, the signups accounts are not always easy to
spot as spammers, since they often come with profile images,
descriptions, etc.With the bot, we now have a more flexible way of dealing with the
problem.LicenseMITContributionsWe welcome contributions and will integrate them after review via the
usual PR process, provided they are MIT licensed as well.Credits / NoticesThanks go out toDanfor creating the
wonderfulpyrogramasync TG
package."Telegram" is a trademark of Telegram LLC.ResourceseGenix Antispam Bot for Telegram home pageeGenix Antispam Bot for Telegram on Githubpyrogram, the TG library used
by this botChangelog0.6.0:Upgraded to pyrogram 2.0.106, which fixes a weird error we have been
getting recently with the old version 1.4.16 (seehttps://github.com/pyrogram/pyrogram/issues/1347)Catch weird error from Telegram when deleting conversations; this
seems to sometimes fail, probably due to a glitch on their sideMade the math and char entry challenges a little harderAdded new DictItemChallenge0.5.0:Output version number when starting up the botAdded more PyPI project linksUpgraded TgCryptoAdded support for muting the bot messages and enabled this per
default; thanks to Alexander Ananchenko for bringing up that ideaAdded support for also removing the approval message after a timeout
(not enabled per default);  thanks to Alexander Ananchenko for that
ideaBot conversations are now logged before removing them; this makes it
easier to debug challenges (some may be too easy)0.4.0:Added new challenge MathMultiplyChallengeMade the MathAddChallenge and MathMultiplyChallenge a little more
difficult0.3.0:Added new challenge ListItemChallengeAdded new config variables MAX_FAILED_CHALLENGES to limit the number
of failed challenge responses. Defaults to 3.Added docker-compose config example to sourcesFixed display of the user name to always show the full name, where
available.Added work-around for pyrogram to not create session files inside
the package dir when running the bot in -m modeFixed bug to make file logging workFixed bug in ban time handling; this now works correctly0.2.0: Initial release on PyPI0.1.0: Initial release on GithubEnjoy,Marc-André LemburgeGenix.com