2019-05-14 20:06:50 +00:00
|
|
|
<h2><img align="middle"
|
2019-05-14 19:47:50 +00:00
|
|
|
src="https://raw.githubusercontent.com/odb/official-bash-logo/master/assets/Logo
|
|
|
|
s/Icons/PNG/64x64.png" >
|
|
|
|
Bashbot - A Telegram bot written in bash.
|
2019-05-14 20:06:50 +00:00
|
|
|
</h2>
|
2019-04-28 07:54:51 +00:00
|
|
|
Written by Drew (@topkecleon), Daniil Gentili (@danogentili), and Kay M
|
2019-04-16 19:56:46 +00:00
|
|
|
(@gnadelwartz).
|
|
|
|
|
|
|
|
Contributions by JuanPotato, BigNerd95, TiagoDanin, and iicc1.
|
|
|
|
|
2019-04-28 07:54:51 +00:00
|
|
|
Released to the public domain wherever applicable.
|
|
|
|
Elsewhere, consider it released under the
|
|
|
|
[WTFPLv2](http://www.wtfpl.net/txt/copying/).
|
|
|
|
|
|
|
|
## Prerequisites
|
2020-06-26 09:01:56 +00:00
|
|
|
Uses [JSON.sh](http://github.com/dominictarr/JSON.sh) and the magic of sed.
|
2019-04-28 07:54:51 +00:00
|
|
|
|
2020-06-23 14:11:45 +00:00
|
|
|
Even bashbot is written in bash, it depends on commands typically available in
|
2019-05-14 17:58:59 +00:00
|
|
|
a Unix/Linux Environment.
|
2020-05-19 12:58:29 +00:00
|
|
|
More concret on the common commands provided by recent versions of
|
2019-05-14 17:58:59 +00:00
|
|
|
[coreutils](https://en.wikipedia.org/wiki/List_of_GNU_Core_Utilities_commands),
|
|
|
|
[busybox](https://en.wikipedia.org/wiki/BusyBox#Commands) or
|
2019-05-14 18:55:24 +00:00
|
|
|
[toybox](https://landley.net/toybox/help.html), see [Developer
|
|
|
|
Notes](doc/7_develop.md#common-commands)
|
2019-05-14 17:58:59 +00:00
|
|
|
|
2020-06-09 14:51:50 +00:00
|
|
|
*Note for MacOS and BSD Users:* As bashbot heavily uses modern bash and (gnu)
|
|
|
|
grep/sed features, bashbot will not run without installing additional software,
|
2020-05-19 12:58:29 +00:00
|
|
|
see [Install Bashbot](doc/0_install.md)
|
|
|
|
|
2019-04-28 07:54:51 +00:00
|
|
|
|
|
|
|
Bashbot [Documentation](https://github.com/topkecleon/telegram-bot-bash) and
|
|
|
|
[Downloads](https://github.com/topkecleon/telegram-bot-bash/releases) are
|
2020-06-23 14:11:45 +00:00
|
|
|
available on www.github.com
|
2019-04-28 07:54:51 +00:00
|
|
|
|
|
|
|
## Documentation
|
|
|
|
* [Introdution to Telegram Bots](https://core.telegram.org/bots)
|
|
|
|
* [Install Bashbot](doc/0_install.md)
|
|
|
|
* Install release
|
|
|
|
* Install from githup
|
|
|
|
* Update Bashbot
|
|
|
|
* Notes on Updates
|
2019-05-30 13:08:07 +00:00
|
|
|
* [Get Bottoken from Botfather](doc/1_firstbot.md)
|
2019-04-28 07:54:51 +00:00
|
|
|
* [Getting Started](doc/2_usage.md)
|
|
|
|
* Managing your Bot
|
2020-06-23 14:11:45 +00:00
|
|
|
* Receive data
|
2019-04-28 07:54:51 +00:00
|
|
|
* Send messages
|
|
|
|
* Send files, locations, keyboards
|
|
|
|
* [Advanced Features](doc/3_advanced.md)
|
|
|
|
* Access Control
|
|
|
|
* Interactive Chats
|
|
|
|
* Background Jobs
|
|
|
|
* Inline queries
|
2020-06-11 10:17:07 +00:00
|
|
|
* Send message errors
|
2019-04-28 07:54:51 +00:00
|
|
|
* [Expert Use](doc/4_expert.md)
|
|
|
|
* Handling UTF-8 character sets
|
|
|
|
* Run as other user or system service
|
2020-06-23 14:11:45 +00:00
|
|
|
* Schedule bashbot from Cron
|
2019-05-30 10:03:40 +00:00
|
|
|
* Use from CLI and Scripts
|
|
|
|
* Customize Bashbot Environment
|
2019-04-28 07:54:51 +00:00
|
|
|
* [Best Practices](doc/5_practice.md)
|
2019-06-01 10:41:12 +00:00
|
|
|
* Customize mycommands.sh
|
|
|
|
* Overwrite/disable commands
|
2020-06-23 14:11:45 +00:00
|
|
|
* Separate logic from commands
|
2019-04-28 07:54:51 +00:00
|
|
|
* Test your Bot with shellcheck
|
2019-05-10 10:04:49 +00:00
|
|
|
* [Function Reference](doc/6_reference.md)
|
|
|
|
* Sending Messages, Files, Keyboards
|
|
|
|
* User Access Control
|
|
|
|
* Inline Queries
|
2020-06-01 11:44:30 +00:00
|
|
|
* jsshDB Bashbot key-value storage
|
2019-05-10 10:04:49 +00:00
|
|
|
* Background and Interactive Jobs
|
2020-06-23 14:35:50 +00:00
|
|
|
* [Developer Notes](doc/7_develop.md)
|
2019-05-30 10:03:40 +00:00
|
|
|
* Debug bashbot
|
|
|
|
* Modules, addons, events
|
2019-04-28 07:54:51 +00:00
|
|
|
* Setup your environment
|
2020-06-23 14:11:45 +00:00
|
|
|
* Bashbot test suite
|
2019-05-30 10:03:40 +00:00
|
|
|
* [Examples Dir](examples/README.md)
|
2019-04-28 07:54:51 +00:00
|
|
|
|
2019-05-24 14:21:51 +00:00
|
|
|
### Your really first bashbot in a nutshell
|
2020-05-17 11:16:01 +00:00
|
|
|
|
2020-06-23 14:11:45 +00:00
|
|
|
To install and run bashbot you need access to a linux/unix command line. If you
|
|
|
|
don't know how to get access to a linux/unix/bsd like command line you should
|
2020-05-19 12:58:29 +00:00
|
|
|
stop reading here :-(
|
2019-05-24 14:21:51 +00:00
|
|
|
|
|
|
|
In addition you need a [Telegram client](https://telegram.org) and a mobile
|
|
|
|
phone to [register an
|
|
|
|
account](https://telegramguide.com/create-a-telegram-account/).
|
|
|
|
If you don't want to register for Telegram you should stop reading here ;-)
|
|
|
|
|
|
|
|
After you're registered to Telegram send a message to
|
|
|
|
[@botfather](https://telegram.me/botfather),
|
|
|
|
[create a new Telegram Bot token](doc/1_firstbot.md) and write it down. You
|
|
|
|
need the token to install the bot.
|
|
|
|
|
|
|
|
Now open a linux/unix/bsd terminal and check if bash is installed: ```which
|
|
|
|
bash && echo "bash installed!"```.
|
|
|
|
If you get an error message bash is not installed.
|
|
|
|
|
|
|
|
Create a new directory and change to it: ```mkdir tbb; cd tbb``` and download
|
|
|
|
the latest '*.tar.gz' file from
|
|
|
|
[https://github.com/topkecleon/telegram-bot-bash/releases](https://github.com/to
|
|
|
|
pkecleon/telegram-bot-bash/releases). This can be done with the commands:
|
|
|
|
```bash
|
|
|
|
wget -q https://github.com/$(wget -q
|
|
|
|
https://github.com/topkecleon/telegram-bot-bash/releases/latest -O - | egrep
|
|
|
|
'/.*/.*/.*tar.gz' -o)
|
|
|
|
```
|
|
|
|
|
|
|
|
Extract the '*.tar.gz' file and change to bashbot directory: ```tar -xzf
|
|
|
|
*.tar.gz; cd telegram-bot-bash```,
|
|
|
|
install bashbot: ```./bashbot.sh init``` and enter your bot token when asked.
|
|
|
|
All other questions can be answered
|
|
|
|
by hitting the \<Return\> key.
|
|
|
|
|
2020-06-23 14:35:50 +00:00
|
|
|
That's all, now you can start your bot with ```./bashbot.sh start``` and send
|
2019-05-24 14:21:51 +00:00
|
|
|
him messages:
|
|
|
|
```
|
|
|
|
/start
|
|
|
|
|
|
|
|
You are Botadmin
|
|
|
|
*Available commands*:
|
|
|
|
*• /start*: _Start bot and get this message_.
|
|
|
|
*• /help*: _Get this message_.
|
|
|
|
*• /info*: _Get shorter info message about this bot_....
|
|
|
|
|
|
|
|
/info
|
|
|
|
|
|
|
|
his is bashbot, the Telegram bot written entirely in bash.
|
|
|
|
It features background tasks and interactive chats, and can serve as an
|
|
|
|
interface for CLI programs.
|
|
|
|
```
|
|
|
|
For more Information on how to install, customize and use your new bot, read
|
|
|
|
the [Documentation](#Documentation)
|
|
|
|
|
2020-06-14 11:50:44 +00:00
|
|
|
### Log files
|
|
|
|
|
2020-06-23 14:11:45 +00:00
|
|
|
Since version 0.96 bashbot log commands received/send and connection errors. If
|
2020-06-18 14:20:42 +00:00
|
|
|
you start bashbot in debug mode
|
|
|
|
bash stdout, stderr and all send/received telegram message are logged also.
|
2020-06-14 11:50:44 +00:00
|
|
|
|
|
|
|
To enable debug mode start bashbot with debug as third argument: `bashbot start
|
|
|
|
debug`
|
|
|
|
|
|
|
|
```
|
|
|
|
├── logs
|
2020-06-18 14:20:42 +00:00
|
|
|
│ ├── BASHBOT.log # log what your bot is doing ...
|
2020-06-14 11:50:44 +00:00
|
|
|
│ ├── ERROR.log # connection errors from / to telegram API
|
|
|
|
│ │
|
|
|
|
│ ├── DEBUG.log # stdout/stderr of you bot (debug mode enabled)
|
2020-06-18 14:20:42 +00:00
|
|
|
│ └── MESSAGE.log # full text of all message send/received (debug mode
|
|
|
|
enabled)
|
2020-06-14 11:50:44 +00:00
|
|
|
```
|
|
|
|
|
2019-05-24 14:21:51 +00:00
|
|
|
----
|
2019-05-11 16:36:40 +00:00
|
|
|
|
2019-04-28 07:54:51 +00:00
|
|
|
## Security Considerations
|
|
|
|
Running a Telegram Bot means it is connected to the public and you never know
|
2020-06-23 14:35:50 +00:00
|
|
|
what's send to your Bot.
|
2019-04-28 07:54:51 +00:00
|
|
|
|
|
|
|
Bash scripts in general are not designed to be bullet proof, so consider this
|
2019-05-01 12:36:34 +00:00
|
|
|
Bot as a proof of concept. Bash programmers often struggle with 'quoting hell'
|
|
|
|
and globbing, see [Implications of wrong
|
2019-04-28 07:54:51 +00:00
|
|
|
quoting](https://unix.stackexchange.com/questions/171346/security-implications-o
|
|
|
|
f-forgetting-to-quote-a-variable-in-bash-posix-shells)
|
|
|
|
|
|
|
|
Whenever you are processing input from from untrusted sources (messages, files,
|
2020-06-23 14:35:50 +00:00
|
|
|
network) you must be as careful as possible, e.g. set IFS appropriate, disable
|
|
|
|
globbing (set -f) and quote everything. In addition delete unused scripts and
|
2019-05-01 12:36:34 +00:00
|
|
|
examples from your Bot, e.g. scripts 'notify', 'calc', 'question', and disable
|
|
|
|
all not used commands.
|
|
|
|
|
2020-06-18 12:00:38 +00:00
|
|
|
**Note:** Until v0.941 (mai/22/2020) telegram-bot-bash had a remote code
|
|
|
|
execution (RCE) bug, pls update if you use an older version!
|
|
|
|
see [Issue #125](https://github.com/topkecleon/telegram-bot-bash/issues/125)
|
|
|
|
|
2020-05-27 07:06:22 +00:00
|
|
|
One of the most powerful features of unix shells like bash is variable and
|
2020-06-18 12:00:38 +00:00
|
|
|
command substitution using ```${}``` and ```$()```,
|
2020-06-23 14:35:50 +00:00
|
|
|
but as they are expanded in double quotes, this can lead to RCE and information
|
2020-06-18 12:00:38 +00:00
|
|
|
disclosing bugs in complex scripts like bashbot
|
|
|
|
even bash does much to avoid this. So it's more secure to escape or remove '$'
|
|
|
|
in input from user, files or network.
|
2020-05-27 07:06:22 +00:00
|
|
|
|
2019-05-01 12:36:34 +00:00
|
|
|
A powerful tool to improve your scripts is ```shellcheck```. You can [use it
|
|
|
|
online](https://www.shellcheck.net/) or [install shellcheck
|
|
|
|
locally](https://github.com/koalaman/shellcheck#installing). Shellcheck is used
|
|
|
|
extensive in bashbot development to enshure a high code quality, e.g. it's not
|
|
|
|
allowed to push changes without passing all shellcheck tests.
|
|
|
|
In addition bashbot has a [test suite](doc/7_develop.md) to check if important
|
|
|
|
functionality is working as expected.
|
2019-04-28 07:54:51 +00:00
|
|
|
|
2020-06-09 09:57:25 +00:00
|
|
|
### use printf whenever possible
|
|
|
|
|
|
|
|
If you're writing a script and it is taking external input (from the user as
|
|
|
|
arguments, or file names from the file system...),
|
|
|
|
you shouldn't use echo to display it. [Use printf whenever
|
|
|
|
possible](https://unix.stackexchange.com/a/6581)
|
|
|
|
|
|
|
|
```bash
|
|
|
|
# very simple
|
|
|
|
echo "text with variables. PWD=$PWD"
|
|
|
|
printf '%s\n' "text with variables. PWD=$PWD"
|
|
|
|
-> text with variables. PWD=/home/xxx
|
|
|
|
|
|
|
|
# more advanced
|
|
|
|
FLOAT="1.2346777892864" INTEGER="12345.123"
|
|
|
|
echo "text with variabeles. float=$FLOAT, integer=$INTEGER, PWD=$PWD"
|
|
|
|
->text with variables. float=1.2346777892864, integer=12345.123, PWD=/home/xxx
|
|
|
|
|
|
|
|
printf "text with variables. float=%.2f, integer=%d, PWD=%s\n" "" "$INTEGER"
|
|
|
|
"$PWD"
|
|
|
|
->text with variables. float=1.23, integer=12345, PWD=/home/xxx
|
|
|
|
```
|
|
|
|
|
2020-05-17 11:51:32 +00:00
|
|
|
### Do not use #!/usr/bin/env bash
|
|
|
|
|
2020-05-17 12:02:03 +00:00
|
|
|
**We stay with /bin/bash shebang, because it's more save from security
|
|
|
|
perspective.**
|
2020-05-17 11:51:32 +00:00
|
|
|
|
2020-05-19 15:32:29 +00:00
|
|
|
Using a fixed path to the system provided bash makes it harder for attackers or
|
|
|
|
users to place alternative versions of bash
|
|
|
|
and avoids using a possibly broken, mangled or compromised bash executable.
|
2020-05-17 11:51:32 +00:00
|
|
|
|
2020-05-19 15:32:29 +00:00
|
|
|
If you are a BSD / MacOS user or must to use an other bash location, see
|
|
|
|
[Install Bashbot](doc/0_install.md)
|
2020-05-17 11:51:32 +00:00
|
|
|
|
2019-04-28 07:54:51 +00:00
|
|
|
### Run your Bot as a restricted user
|
|
|
|
**I recommend to run your bot as a user, with almost no access rights.**
|
|
|
|
All files your Bot have write access to are in danger to be overwritten/deleted
|
|
|
|
if your bot is hacked.
|
2020-06-23 14:35:50 +00:00
|
|
|
For the same reason every file your Bot can read is in danger to be disclosed.
|
|
|
|
Restict your Bots access rights to the absolute minimum.
|
2019-04-28 07:54:51 +00:00
|
|
|
|
|
|
|
**Never run your Bot as root, this is the most dangerous you can do!** Usually
|
|
|
|
the user 'nobody' has almost no rights on Unix/Linux systems. See [Expert
|
|
|
|
use](doc/4_expert.md) on how to run your Bot as an other user.
|
|
|
|
|
|
|
|
### Secure your Bot installation
|
|
|
|
**Your Bot configuration must no be readable from other users.** Everyone who
|
|
|
|
can read your Bots token can act as your Bot and has access to all chats your
|
|
|
|
Bot is in!
|
|
|
|
|
|
|
|
Everyone with read access to your Bot files can extract your Bots data.
|
|
|
|
Especially your Bot Token in ```token``` must be protected against other users.
|
2020-06-23 14:35:50 +00:00
|
|
|
No one except you must have write access to the Bot files. The Bot must be
|
2019-04-28 07:54:51 +00:00
|
|
|
restricted to have write access to ```count``` and ```tmp-bot-bash``` only,
|
|
|
|
all other files must be write protected.
|
|
|
|
|
|
|
|
To set access rights for your bashbot installation to a reasonable default run
|
|
|
|
```sudo ./bashbot.sh init``` after every update or change to your installation
|
|
|
|
directory.
|
|
|
|
|
2019-05-20 18:48:49 +00:00
|
|
|
## FAQ
|
|
|
|
|
2019-04-28 07:54:51 +00:00
|
|
|
### Is this Bot insecure?
|
|
|
|
Bashbot is not more (in)secure as any other Bot written in any other language,
|
|
|
|
we have done our best to make it as secure as possible. But YOU are responsible
|
|
|
|
for the bot commands you wrote and you should know about the risks ...
|
|
|
|
|
2020-05-27 07:06:22 +00:00
|
|
|
**Note:** Until v0.941 (mai/22/2020) telegram-bot-bash has a remote code
|
|
|
|
execution bug, pls update if you use an older version!
|
|
|
|
|
2019-04-28 07:54:51 +00:00
|
|
|
### Why Bash and not the much better xyz?
|
2020-06-23 14:35:50 +00:00
|
|
|
Well, that's a damn good question ... may be because I'm an Unix/Linux admin
|
2019-04-28 07:54:51 +00:00
|
|
|
from stone age. Nevertheless there are more reasons from my side:
|
|
|
|
|
2020-06-26 06:26:52 +00:00
|
|
|
- bashbot will run everywhere where bash and (gnu) sed is available, from
|
|
|
|
embedded linux to mainframe
|
2019-04-28 07:54:51 +00:00
|
|
|
- easy to integrate with other shell script, e.g. for sending system message /
|
|
|
|
health status
|
|
|
|
- no need to install or learn a new programming language, library or framework
|
|
|
|
- no database, not event driven, not OO ...
|
2019-04-27 19:10:55 +00:00
|
|
|
|
2019-05-21 08:53:52 +00:00
|
|
|
### Can I have the single bashbot.sh file back?
|
2019-05-20 18:48:49 +00:00
|
|
|
At the beginning bashbot was simply the file ```bashbot.sh``` you can copy
|
|
|
|
everywhere and run the bot. Now we have 'commands.sh', 'mycommands.sh',
|
|
|
|
'modules/*.sh' and much more.
|
|
|
|
|
|
|
|
Hey no Problem, if you are finished with your cool bot run
|
|
|
|
```dev/make-standalone.sh``` to create a stripped down Version of your bot
|
|
|
|
containing only
|
|
|
|
'bashbot.sh' and 'commands.sh'! For more information see [Create a stripped
|
|
|
|
down Version of your Bot](doc/7_develop.md)
|
|
|
|
|
2019-05-24 18:30:01 +00:00
|
|
|
### Can I send messages from CLI and scripts?
|
|
|
|
Of course, you can send messages from CLI and scripts, simply install bashbot
|
|
|
|
as [described here](#Your-really-first-bashbot-in-a-nutshell),
|
2020-06-23 14:35:50 +00:00
|
|
|
send the message '/start' to set yourself as botadmin and stop the bot with
|
2019-05-24 18:30:01 +00:00
|
|
|
```./bashbot.sh kill```.
|
|
|
|
|
|
|
|
Run the following commands in your bash shell or script while you are in the
|
|
|
|
installation directory:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
# prepare bash / script to send commands
|
|
|
|
export BASHBOT_HOME="$(pwd)"
|
|
|
|
source ./bashbot.sh source
|
|
|
|
|
|
|
|
# send me a test message
|
2020-07-12 11:52:03 +00:00
|
|
|
send_message "$(getConfigKey "botadmin")" "test"
|
2019-05-24 18:30:01 +00:00
|
|
|
|
|
|
|
# send me output of a system command
|
2020-07-12 11:52:03 +00:00
|
|
|
send_message "$(getConfigKey "botadmin")" "$(df -h)"
|
2019-05-24 18:30:01 +00:00
|
|
|
```
|
|
|
|
For more information see [Expert Use](doc/8_custom.md)
|
|
|
|
|
|
|
|
|
2020-06-23 14:11:45 +00:00
|
|
|
### Blocked by telegram?
|
2020-07-12 16:19:50 +00:00
|
|
|
This may happen if to many or wrong requests are sent to api.telegram.org, e.g.
|
|
|
|
using a invalid token or not existing API calls.
|
|
|
|
If the block stay for longer time you can ask telegram service to unblock your
|
|
|
|
IP-Adress.
|
2020-06-23 14:11:45 +00:00
|
|
|
|
2020-07-12 16:19:50 +00:00
|
|
|
You can check with curl or wget if you are blocked by Telegram:
|
2019-05-24 08:47:27 +00:00
|
|
|
```bash
|
|
|
|
curl -m 10 https://api.telegram.org/bot
|
|
|
|
#curl: (28) Connection timed out after 10001 milliseconds
|
|
|
|
|
|
|
|
wget -t 1 -T 10 https://api.telegram.org/bot
|
|
|
|
#Connecting to api.telegram.org (api.telegram.org)|46.38.243.234|:443...
|
|
|
|
failed: Connection timed out.
|
|
|
|
```
|
2019-05-20 18:48:49 +00:00
|
|
|
|
2020-07-12 16:19:50 +00:00
|
|
|
Since Version 0.96 bashbot offers the option to recover from broken connections
|
|
|
|
(aka blocked). Therefore you can provide a function
|
|
|
|
named `bashbotBlockRecover()` in `mycommands.sh`. If the function exists it is
|
2020-07-12 16:33:03 +00:00
|
|
|
called every time when a broken connection is detected.
|
2020-07-12 11:52:03 +00:00
|
|
|
|
2020-07-12 16:19:50 +00:00
|
|
|
Possible actions are: Check if network is working, change IP or simply wait
|
|
|
|
some time.
|
|
|
|
|
|
|
|
If everything seems OK return 0 for retry or any non 0 value to give up.
|
2020-07-12 11:52:03 +00:00
|
|
|
|
|
|
|
```bash
|
|
|
|
# called when bashbot sedn command failed because we can not connect to telegram
|
|
|
|
# return 0 to retry, return non 0 to give up
|
|
|
|
bashbotBlockRecover() {
|
|
|
|
# place your commands to unblock here, e.g. change IP or simply wait
|
|
|
|
sleep 60 && return 0 # may be temporary
|
|
|
|
return 1
|
|
|
|
}
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
2019-04-27 19:10:55 +00:00
|
|
|
@Gnadelwartz
|
2019-04-27 13:48:03 +00:00
|
|
|
|
2019-04-28 07:54:51 +00:00
|
|
|
## That's it!
|
2019-04-09 11:41:38 +00:00
|
|
|
|
2019-04-28 07:54:51 +00:00
|
|
|
If you feel that there's something missing or if you found a bug, feel free to
|
|
|
|
submit a pull request!
|
2019-04-09 11:41:38 +00:00
|
|
|
|
2020-07-12 16:33:03 +00:00
|
|
|
#### $$VERSION$$ v0.99-dev2-6-gb641a18
|