matrix-eno-bot

matrix-eno-bot is a Matrix bot based on the Python 3 bot template nio-template which in turn is based on the Matrix Python SDK called matrix-nio. The bot, the template and the SDK are all written in Python 3. The commands that the matrix-eno-bot comes with are written in bash and in python3.

Naming: Eno?

Why eno? It is a word play. Yes, another word play. Matrix is a word play on the Matrix movies. matrix-nio one would guess is a word play on the character Neo, in the Matrix movies. Both Neo and nio sound the same. They are homophones. And eno is just a randomized version of Neo, an anagram of Neo.

Eno is also another name for the Ibibio tribe in Nigeria. Have a look at their unusual symbols.

Hence, the "logo" which is nothing more than an Nsibidi symbol taken from Wikipedia. To me the Nsibidi symbol chosen for the logo resembles a stylized E. E of course for eno.

And a month after creating this repo by pure chance, this Urban Dictionary link for eno popped up. Here, the word eno is defined as: Totally awesome, Wicked cool. Hyperbole of awesome/cool. E.g. Dude, that round of speedball was so eno! What a fitting coincidence! Perfect fit! So cool, oops, so eno!

History and Past

The first version of the bot was tiny-matrix-bot plus which was based on matrix-python-sdk. Since matrix-python-sdk is no longer actively supported and end-to-end-encryption comes out of the box in matrix-nio, the switch to nio-template was made. tiny-matrix-bot plus is now abandonded and all efforts are put into matrix-eno-bot.

Due to this history, you will find strong similarieties in the Bash scripts in tiny-matrix-bot plus and eno.

eno includes various modifications and enhancements in comparison to nio-template. nio-template was forked in summer of 2020. Since then my fork has drifted apart from the original nio-template. The framework files of nio-template used by eno have these enhancements:

use of access token instead of password
option to trust own devices
option to change device name
emoji verification and handling of to_device messages
sending of images and files (audio, video, pdf, etc.)

Installation and Setup

# install dependencies, matrix-nio
# for more detail see https://github.com/poljar/matrix-nio
sudo apt install python3 python3-requests libolm-dev
pip install "matrix-nio[e2e]" Markdown PyYAML
# install matrix-eno-bot
git clone https://github.com/8go/matrix-eno-bot
# https://github.com/8go/matrix-eno-bot includes the nio-template files.
# no need to clone nio-template repo
cd matrix-eno-bot
# configure bot basics
cp config.yaml.example config.yaml
vim config.yaml # adjust the config file to your needs
# configure bot command dictionary (thanks to @wolterhv)
cp commands.yaml.example commands.yaml
vim commands.yaml # adjust the commands config file to your needs
# make scripts executable
chmod 755 eno/scripts/*
# configure bot as service
cd eno
cp matrix-eno-bot.service.example matrix-eno-bot.service
vim matrix-eno-bot.service # adjust service to your setup
sudo cp matrix-eno-bot.service /etc/systemd/system/matrix-eno-bot.service
# read the comments in matrix-eno-bot.service, it tells you what to do
systemctl enable matrix-eno-bot # create bot service
systemctl start matrix-eno-bot # start bot
systemctl stop matrix-eno-bot # stop bot

Other hints:

Create an account for your bot in some client, e.g. in Element
Use this account (username, password) in config.yaml and let the bot create a brand-new device
- If device is not new e2ee will not work.
Verify the bot via emoji-verify
If desired reconfigure config.yaml to replace password with access token for added security

Installation as Docker Container

Since a couple of Python packages require to be compiled, you might want to not install gcc on your server. An alternate way to quickly deploy the bot is to compile it in a docker container and then install the Docker container.

To build the Docker image (~500mb): docker build -t matrix-eno-bot --rm .
To run the container: docker run --rm -ti matrix-eno-bot bash

Thanks to @apiraino for this contribution!

Usage

intended audience/users:
- small homeserver set up for a few friends
- tinkerers who want to learn how a bot works
- people who want to play around with Python code and Matrix
create a Matrix account for the bot, name it bot for example
configure the bot software
create the bot service and start the bot or the bot service
log in to the before created Matrix bot account e.g. via Element web page
manually send invite from bot account to a friend (or to yourself)
once invite is accepted, reset the bot service (so that the new room will be added to bot service)
- if you as admin already have a room with the bot, you can reset the bot by sending it restart bot as a message in your Matrix bot room
have the newly joined invitee send a hello command to the bot for a first test
bot can do emoji verify
bot can handle encrypted rooms by default
bot can handle texts, images, and arbitrary files (send audio, PDF, video, etc.)

Feedback

If you like the matrix-eno-bot please give it a ⭐ on Github right away. Thanks ❤️ Raise issues or contribute a PR.

Debugging

Run something similar to

cd matrix-eno-bot # go to your installation directory
vim config.yaml # modify the logging parameters, increase logging
systemctl restart matrix-eno-bot # restart server in case it is running
# observe debug output and look at the log files

Bot as Personal Assistant: Example bot commands provided

Commands useful to average users:

btc: gives Bitcoin BTC price info
ddg: search the web with DuckDuckGo search
eth: gives Ethereum price info
hello: gives you a friendly compliment
help: to list available bot commands
hn: read Hacker News, fetches front page headlines from Hacker News
mn: read Messari News, fetches the latest news articles from Messari
motd: gives you the Linux Message Of The Day
rss: read RSS feeds
s2f: print Bitcoin Stock-to-flow price info
tides: get today's low and high tides of your favorite beach
totp: get 2FA Two-factor-authentication TOTP One-Time-Password PIN via bot message (like Google Authenticator)
twitter: read latest user tweets from Twitter (does not work most of the time as info is scraped from web)
waves: get the surf report of your favorite beach
weather: get the weather forecast for your favorite city
web: surf the web, get a web page (JavaScript not supported)
easily extendable via command dictionary in convenient commands.yaml file

Bot as Admin Tool: Example bot commands provided to Matrix or system administrators

With these commands a system administrator can maintain his Matrix installation and keep a watchful eye on his server all through the Matrix bot. Set the permissions accordingly in the config file to avoid unauthorized use of these bot commands!

alert: shows if any CPU, RAM, or Disk thresholds have been exceeded (best to combine with a cron job, and have the cron job send the bot message to Matrix admin rooms)
backup: runs your backup script to backup files, partitions, etc.
check: check status, health status, updates, etc. of bot, Matrix and the operating system
cputemp: monitor the CPU temperatures
date: gives date and time of server
disks: see how full your disks or mountpoints are
firewall: list the firewall settings and configuration
platform: gives hardware and operating system platform information
ps: print current CPU, RAM and Disk utilization of server
restart: restart the bot itself, or Matrix services
top: gives 5 top CPU and RAM consuming processes
update: update operating sytem and other software environments
users: list user accounts that exist on your server
wake: wake up other PCs on the network via wake-on-LAN
easily extendable via command dictionary in convenient commands.yaml file

Other Features

sample scripts are in bash and in python3, but can be in any language (JavaScript, Go, etc.)
easily extendable via command dictionary in convenient commands.yaml file (thanks to @wolterhv)
matrix-eno-bot combines well with matrix-commander. Configure matrix-commander as another eno bot device.
matrix-commander can then be used very easily for monitoring the system. An admin can set up a cron job that runs every 15 minutes, e.g. to check CPU temperature, or to check a log file for signs of an intrusion (e.g. SSH or Web Server log files). If anything abnormal is found by the cron job, the cron job fires off a bot message to the admin.

Legal

There is no support and no warranty.

Final Thoughts

Thanks a lot to the people that have already contributed! It is so appreciated! ❤️
Enjoy and have fun with it, it is cool, and easily extensible. Adjust it to your needs!
Pull Requests are welcome :)

More on the Nio Template

The nio-template is a template for creating bots with matrix-nio. The documentation for matrix-nio can be found here.

For up-to-date info on nio-template go to https://github.com/anoadragon453/nio-template. Give them a star if you like it.

Project structure

`main.py`

Initialises the config file, the bot store, and nio's AsyncClient (which is used to retrieve and send events to a matrix homeserver). It also registering some callbacks on the AsyncClient to tell it to call some functions when certain events are received (such as an invite to a room, or a new message in a room the bot is in).

It also starts the sync loop. Matrix clients "sync" with a homeserver, by asking constantly asking for new events. Each time they do, the client gets a sync token (stored in the next_batch field of the sync response). If the client provides this token the next time it syncs (using the since parameter on the AsyncClient.sync method), the homeserver will only return new event since those specified by the given token.

This token is saved and provided again automatically by using the client.sync_forever(...) method.

It can also change its device name and it can trust its own devices, if so configured.

`config.py`

This file reads a config file at a given path (hardcoded as config.yaml in main.py), processes everything in it and makes the values available to the rest of the bot's code so it knows what to do. Most of the options in the given config file have default values, so things will continue to work even if an option is left out of the config file. Obviously there are some config values that are required though, like the homeserver URL, username, access token etc. Otherwise the bot can't function.

`storage.py`

Creates (if necessary) and connects to a SQLite3 database and provides commands to put or retrieve data from it. Table definitions should be specified in _initial_setup, and any necessary migrations should be put in _run_migrations. There's currently no defined method for how migrations should work though.

`callbacks.py`

Holds callback methods which get run when the bot get a certain type of event from the homserver during sync. The type and name of the method to be called are specified in main.py. Currently there are two defined methods, one that gets called when a message is sent in a room the bot is in, and another that runs when the bot receives an invite to the room.

The message callback function, message, checks if the message was for the bot, and whether it was a command. If both of those are true, the bot will process that command.

The invite callback function, invite, processes the invite event and attempts to join the room. This way, the bot will auto-join any room it is invited to.

The device callback function, device, handles all aspects of an emoji verification.

`bot_commands.py`

Where all the bot's commands are defined. New commands should be defined in process with an associated private method. echo and help commands are provided by default.

A Command object is created when a message comes in that's recognised as a command from a user directed at the bot (either through the specified command prefix (defined by the bot's config file), or through a private message directly to the bot. The process command is then called for the bot to act on that command.

`message_responses.py`

Where responses to messages that are posted in a room (but not necessarily directed at the bot) are specified. callbacks.py will listen for messages in rooms the bot is in, and upon receiving one will create a new Message object (which contains the message text, amongst other things) and calls process() on it, which can send a message to the room as it sees fit.

A good example of this would be a Github bot that listens for people mentioning issue numbers in chat (e.g. "We should fix #123"), and the bot sending messages to the room immediately afterwards with the issue name and link.

`chat_functions.py`

A separate file to hold helper methods related to messaging. Mostly just for organisational purposes. Currently just holds send_text_to_room, a helper method for sending formatted messages to a room.

Other helper functions allow sending of images and arbitrary files like audio, video, PDFs, etc.

`errors.py`

Custom error types for the bot. Currently there's only one special type that's defined for when a error is found while the config file is being processed.

`config.yaml.example`

The sample configuration file. People running your bot should be advised to copy this file to config.yaml, then edit it according to their needs. Be sure never to check the edited config.yaml into source control since it'll likely contain sensitive details like passwords!

dsuni/matrix-eno-bot