octoleo/telegram-bot-bash
1
1
Fork 0
mirror of https://github.com/octoleo/telegram-bot-bash.git synced 2024-12-30 21:31:47 +00:00
Code Issues Projects Releases Wiki Activity

some more doc cleanup for release

Browse Source
This commit is contained in:
Kay Marquardt (Gnadelwartz) 2019-04-16 16:45:26 +02:00
parent 1bf26b9caf
commit 591c5834fa
8 changed files with 53 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
README.md
View File

@ -68,9 +68,9 @@ This has the advantage that you can create any type of keyboard supported by Tel
- numpad style keyboard: "[ \\"1\\" , \\"2\\" , \\"3\\" ] , [ \\"4\\" , \\"5\\" , \\"6\\" ] , [ \\"7\\" , \\"8\\" , \\"9\\" ] , [ \\"0\\" ]" - numpad style keyboard: "[ \\"1\\" , \\"2\\" , \\"3\\" ] , [ \\"4\\" , \\"5\\" , \\"6\\" ] , [ \\"7\\" , \\"8\\" , \\"9\\" ] , [ \\"0\\" ]"
## Security Considerations ## Security Considerations
Running a Telegram Bot means it is conneted to the public and you never know whats send to your Bot. Running a Telegram Bot means it is connected to the public and you never know whats send to your Bot.
Bash scripts in general are not designed to be bullet proof, so consider this Bot as a proof of concept. More concret examples of security problems is bash's 'quoting hell' and globbing. [Implications of wrong quoting](https://unix.stackexchange.com/questions/171346/security-implications-of-forgetting-to-quote-a-variable-in-bash-posix-shells) Bash scripts in general are not designed to be bullet proof, so consider this Bot as a proof of concept. More concret examples of security problems are bash's 'quoting hell' and globbing. [Implications of wrong quoting](https://unix.stackexchange.com/questions/171346/security-implications-of-forgetting-to-quote-a-variable-in-bash-posix-shells)
Whenever you are processing input from from untrusted sources (messages, files, network) you must be as carefull as possible, e.g. disable globbing (set -f) and quote everthing. Whenever you are processing input from from untrusted sources (messages, files, network) you must be as carefull as possible, e.g. disable globbing (set -f) and quote everthing.
@ -79,23 +79,23 @@ A powerful tool to improve your scripts robustness is ```shellcheck```. You can
### Run your Bot as a restricted user ### Run your Bot as a restricted user
**It's important to run your bot as a user, with almost no access rights.** **It's important to run your bot as a user, with almost no access rights.**
All files your Bot write access to are in danger to be overwritten/deleted if your bot is hacked. All files your Bot have write access to are in danger to be overwritten/deleted if your bot is hacked.
For the same reason ervery file your Bot can read is in danger of being disclosed. So please restict your Bots access rigths to the absolute minimum. For the same reason ervery file your Bot can read is in danger of being disclosed. So please restict your Bots access rigths to the absolute minimum.
**Never run your Bot as root, this is the most dangerous you can do!** Usually the user 'nobody' has almost no rigths on Unix/Linux systems. See Expert use on how to run your Bot as an other user. **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 on how to run your Bot as an other user.
### Secure your Bot installation ### Secure your Bot installation
**Your Bot configuration should not be readable from other users.** If someone can read your Bots token he can act as your Bot and has access to all chats you bot is in! **Your Bot configuration should not be readable from other users.** If someone can read your Bots token he can act as your Bot and has access to all chats you 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. No one exept you should have write access to the Bot files. The Bot must be restricted to have write access to ```count``` and ```tmp-bot-bash``` only, all other files should be write protected. 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. No one exept you should have write access to the Bot files. The Bot must be restricted to have write access to ```count``` and ```tmp-bot-bash``` only, all other files should be write protected.
To set access rights for your telegram-bot-bash directory to reasonable default values you must run ```sudo ./bashbot.sh init``` after every update or change to your installation directory. To set access rights for your telegram-bot-bash directory to reasonable default values you must run ```sudo ./bashbot.sh init``` after every update or change to your installation directory.
### Is this Bot insecure? ### Is this Bot insecure?
Bashbot is no more (in)secure as any other Bot written in any other language. But since YOU change your bots commands and run the Bot, you should know about the implications ... Bashbot is no more (in)secure as any other Bot written in any other language. But since YOU are responsible for your bots commands and run the Bot, you should know about the implications ...
## That's it! ## That's it!
If you feel that there's something missing or if you found a bug, feel free to submit a pull request! If you feel that there's something missing or if you found a bug, feel free to submit a pull request!
#### $$VERSION$$ v0.60-rc2-3-g4a944d9 #### $$VERSION$$ v0.60-rc2-4-g1bf26b9

16
README.txt
View File

@ -90,12 +90,12 @@ _Example Keyboards_:
Security Considerations Security Considerations
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
Running a Telegram Bot means it is conneted to the public and you never Running a Telegram Bot means it is connected to the public and you never
know whats send to your Bot. know whats send to your Bot.
Bash scripts in general are not designed to be bullet proof, so consider Bash scripts in general are not designed to be bullet proof, so consider
this Bot as a proof of concept. More concret examples of security this Bot as a proof of concept. More concret examples of security
problems is bash's 'quoting hell' and globbing. problems are bash's 'quoting hell' and globbing.
https://unix.stackexchange.com/questions/171346/security-implications-of-forgetting-to-quote-a-variable-in-bash-posix-shells[Implications https://unix.stackexchange.com/questions/171346/security-implications-of-forgetting-to-quote-a-variable-in-bash-posix-shells[Implications
of wrong quoting] of wrong quoting]
@ -114,13 +114,13 @@ Run your Bot as a restricted user
*It's important to run your bot as a user, with almost no access *It's important to run your bot as a user, with almost no access
rights.* rights.*
All files your Bot write access to are in danger to be All files your Bot have write access to are in danger to be
overwritten/deleted if your bot is hacked. For the same reason ervery overwritten/deleted if your bot is hacked. For the same reason ervery
file your Bot can read is in danger of being disclosed. So please file your Bot can read is in danger of being disclosed. So please
restict your Bots access rigths to the absolute minimum. restict your Bots access rigths to the absolute minimum.
*Never run your Bot as root, this is the most dangerous you can do!* *Never run your Bot as root, this is the most dangerous you can do!*
Usually the user 'nobody' has almost no rigths on Unix/Linux systems. Usually the user 'nobody' has almost no rights on Unix/Linux systems.
See Expert use on how to run your Bot as an other user. See Expert use on how to run your Bot as an other user.
Secure your Bot installation Secure your Bot installation
@ -128,7 +128,7 @@ Secure your Bot installation
*Your Bot configuration should not be readable from other users.* If *Your Bot configuration should not be readable from other users.* If
someone can read your Bots token he can act as your Bot and has access someone can read your Bots token he can act as your Bot and has access
to all chats you bot is in! to all chats you Bot is in!
Everyone with read access to your Bot files can extract your Bots data. Everyone with read access to your Bot files can extract your Bots data.
Especially your Bot Token in `token` must be protected against other Especially your Bot Token in `token` must be protected against other
@ -144,8 +144,8 @@ Is this Bot insecure?
^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^
Bashbot is no more (in)secure as any other Bot written in any other Bashbot is no more (in)secure as any other Bot written in any other
language. But since YOU change your bots commands and run the Bot, you language. But since YOU are responsible for your bots commands and run
should know about the implications ... the Bot, you should know about the implications ...
That's it! That's it!
~~~~~~~~~~ ~~~~~~~~~~
@ -153,5 +153,5 @@ That's it!
If you feel that there's something missing or if you found a bug, feel If you feel that there's something missing or if you found a bug, feel
free to submit a pull request! free to submit a pull request!
latexmath:[\[VERSION\]] v0.60-rc2-3-g4a944d9 latexmath:[\[VERSION\]] v0.60-rc2-4-g1bf26b9
++++++++++++++++++++++++++++++++++++++++++++ ++++++++++++++++++++++++++++++++++++++++++++

13
doc/1_firstbot.md
View File

@ -58,17 +58,8 @@ group. This step is up to you actually.
13. @botfather replies with `Success! The new status is: DISABLED. /help` 13. @botfather replies with `Success! The new status is: DISABLED. /help`
### Install bashbot
1. Go to the directory you want to install bashbot, e.g.
- your $HOME directory (install and run with your user-ID) #### [Next Getting started](2_usage.md)
- /usr/local if you want to run as service
2. Clone the repository: #### $$VERSION$$ v0.60-rc2-4-g1bf26b9
```
git clone --recursive https://github.com/topkecleon/telegram-bot-bash
```
3. Change to directory ```telegram-bot.bash```, run ```./bashbot.sh init``` and follow the instructions. At this stage you are asked for your Bots token given by botfather.
#### $$VERSION$$ v0.60-rc2-3-g4a944d9

4
doc/2_usage.md
View File

@ -154,6 +154,8 @@ Allowed values: typing for text messages, upload_photo for photos, record_video
send_action "${CHAT[ID]}" "action" send_action "${CHAT[ID]}" "action"
``` ```
#### $$VERSION$$ v0.60-rc2-3-g4a944d9 #### [Prev Getting started](2_usage.md)
#### [Next Advanced Usage](3_advanced.md)
#### $$VERSION$$ v0.60-rc2-4-g1bf26b9

6
doc/3_advanced.md
View File

@ -21,7 +21,7 @@ user_is_botadmin "${USER[ID]}" && send_markdown_message "${CHAT[ID]}" "You are *
user_is_admin "${CHAT[ID]}" "${USER[ID]}" && send_markdown_message "${CHAT[ID]}" "You are *CHATADMIN*." user_is_admin "${CHAT[ID]}" "${USER[ID]}" && send_markdown_message "${CHAT[ID]}" "You are *CHATADMIN*."
``` ```
In addtion the bot can check individual capabilities of users as defined in the ```./botacl``` file: In addition you can check individual capabilities of users as defined in the ```./botacl``` file:
```bash ```bash
# file: botacl # file: botacl
# a user not listed here, will return false from 'user_is_allowed' # a user not listed here, will return false from 'user_is_allowed'
@ -153,6 +153,8 @@ To send stickers through an *inline query*:
```bash ```bash
answer_inline_query "$iQUERY_ID" "cached_sticker" "identifier for the sticker" answer_inline_query "$iQUERY_ID" "cached_sticker" "identifier for the sticker"
``` ```
#### [prev Advanced Usage](3_advanced.md)
#### [Next Expert Use](4_expert.md)
#### $$VERSION$$ v0.60-rc2-3-g4a944d9 #### $$VERSION$$ v0.60-rc2-4-g1bf26b9

20
doc/4_expert.md
View File

@ -5,7 +5,7 @@ UTF-8 is a variable length encoding of Unicode. UTF-8 is recommended as the defa
The first 128 characters are regular ASCII, so it's a superset of and compatible with ASCII environments. The next 1,920 characters need The first 128 characters are regular ASCII, so it's a superset of and compatible with ASCII environments. The next 1,920 characters need
two bytes for encoding and covers almost all ```Latin``` alphabets, also ```Greek```, ```Cyrillic```, two bytes for encoding and covers almost all ```Latin``` alphabets, also ```Greek```, ```Cyrillic```,
```Hebrew```, ```Arabic``` and more. See [Wikipedia](https://en.wikipedia.org/wiki/UTF-8) for more deatils. ```Hebrew```, ```Arabic``` and more. See [Wikipedia](https://en.wikipedia.org/wiki/UTF-8) for more details.
#### Setting up your Environment #### Setting up your Environment
In general ```bash``` and ```GNU``` utitities are UTF-8 aware if you to setup your environment In general ```bash``` and ```GNU``` utitities are UTF-8 aware if you to setup your environment
@ -36,13 +36,13 @@ export 'LANGUAGE=den_US.UTF-8'
To display all availible locales on your system run ```locale -a | more```. [Gentoo Wiki](https://wiki.gentoo.org/wiki/UTF-8) To display all availible locales on your system run ```locale -a | more```. [Gentoo Wiki](https://wiki.gentoo.org/wiki/UTF-8)
#### Bashbot UTF-8 Support #### Bashbot's UTF-8 Support
Bashbot handles all messages transparently, regardless what charset is used. One exception is the conversation from JSON data to strings. Bashbot handles all messages transparently, regardless of the charset in use. The only exception is when converting from JSON data to strings.
Telegram use JSON to send / recieve data. Characters not ASCII *(>127)* are escaped as sequences of ```\uxxxx``` to be regular ASCII. In addition multibyte characters, *e.g. Emoticons or Arabic characters*, are send in double byte UTF-16 notation. Telegram use JSON to send / recieve data. JSON encodes strings as follow: Characters not ASCII *(>127)* are escaped as sequences of ```\uxxxx``` to be regular ASCII. In addition multibyte characters, *e.g. Emoticons or Arabic characters*, are send in double byte UTF-16 notation.
The Emoticons ``` 😁 😘 ❤️ 😊 👍 ``` are encoded as: ``` \uD83D\uDE01 \uD83D\uDE18 \u2764\uFE0F \uD83D\uDE0A \uD83D\uDC4D ``` The Emoticons ``` 😁 😘 ❤️ 😊 👍 ``` are encoded as: ``` \uD83D\uDE01 \uD83D\uDE18 \u2764\uFE0F \uD83D\uDE0A \uD83D\uDC4D ```
**This mixed JSON encoding needs special handling and can not decoded from** ```echo -e``` or ```printf '%s\\n'``` **This "mixed" JSON encoding needs special handling and can not decoded from** ```echo -e``` or ```printf '%s\\n'```
To to fully support decoding of multibyte characters you need a working python2 installation on your system. To to fully support decoding of multibyte characters you need a working python2 installation on your system.
If no python is detected bashbot falls back to a **internal pure bash implementaion which may not work for some corner cases**. If no python is detected bashbot falls back to a **internal pure bash implementaion which may not work for some corner cases**.
@ -51,8 +51,6 @@ If no python is detected bashbot falls back to a **internal pure bash implementa
### Run as other user or system service ### Run as other user or system service
Bashbot is desingned to run manually by the user who installed it. Nevertheless it's possible to run it by an other user-ID, as a system service or sceduled from cron. This is onyl recommended for experiend linux users. Bashbot is desingned to run manually by the user who installed it. Nevertheless it's possible to run it by an other user-ID, as a system service or sceduled from cron. This is onyl recommended for experiend linux users.
#### Running bashbot as an other user is only possible with sudo rigths.
Setup the environment for the user you want to run bashbot and enter desired username, e.g. nobody : Setup the environment for the user you want to run bashbot and enter desired username, e.g. nobody :
```bash ```bash
sudo ./bashbot.sh init sudo ./bashbot.sh init
@ -77,13 +75,13 @@ name='' # your bot name as given to botfather, e.g. mysomething_bot
# END Configuration # END Configuration
####################### #######################
``` ```
From now on always use bashbot.rc to start/stop your bot: From now on use 'bashbot.rc' to manage your bot:
```bash ```bash
sudo ./bashbot.rc start sudo ./bashbot.rc start
``` ```
Type ```ps -ef | grep bashbot``` to verify your Bot is running as the desired user. Type ```ps -ef | grep bashbot``` to verify your Bot is running as the desired user.
If you started bashbot by bashbot.rc you must use bashbot.rc also to manage your Bot! The following commands are availible: If your Bot is started by 'bashbot.rc', you must use 'bashbot.rc' also to manage your Bot! The following commands are availible:
```bash ```bash
sudo ./bashbot.rc start sudo ./bashbot.rc start
sudo ./bashbot.rc stop sudo ./bashbot.rc stop
@ -102,6 +100,8 @@ An example crontab is provided in ```bashbot.cron```.
- If you are running bashbot with your user-ID, copy the examples lines to your crontab and remove username ```nobody```. - If you are running bashbot with your user-ID, copy the examples lines to your crontab and remove username ```nobody```.
- if you run bashbot as an other user or a system service edit ```bashbot.cron``` to fit your needs and replace username```nobody``` with the username you want to run bashbot. copy the modified file to ```/etc/cron.d/bashbot``` - if you run bashbot as an other user or a system service edit ```bashbot.cron``` to fit your needs and replace username```nobody``` with the username you want to run bashbot. copy the modified file to ```/etc/cron.d/bashbot```
#### [Prev Expert Use](4_expert.md)
#### [Next Best Practice](5_practice.md)
#### $$VERSION$$ v0.60-rc2-3-g4a944d9 #### $$VERSION$$ v0.60-rc2-4-g1bf26b9

11
doc/5_practice.md
View File

@ -24,8 +24,8 @@ If a command need more than 2-3 lines of code, you should use a function to sepe
source "mycommands.inc.sh" source "mycommands.inc.sh"
case "$MESSAGE" in case "$MESSAGE" in
'/process') # logic for /report is done in process_message '/process') # logic for /process is done in process_message
result="$(process_message "$MESSAGE") result="$(process_message "$MESSAGE")"
send_normal_message "${CHAT[ID]}" "$result" send_normal_message "${CHAT[ID]}" "$result"
;; ;;
@ -105,8 +105,11 @@ In bashbot.sh line 490:
CONTACT[USER_ID]="$(sed -n -e '/\["result",'$PROCESS_NUMBER',"message","contact","user_id"\]/ s/.*\][ \t]"\(.*\)"$/\1/p' <"$TMP")" CONTACT[USER_ID]="$(sed -n -e '/\["result",'$PROCESS_NUMBER',"message","contact","user_id"\]/ s/.*\][ \t]"\(.*\)"$/\1/p' <"$TMP")"
^-- SC2034: CONTACT appears unused. Verify it or export it. ^-- SC2034: CONTACT appears unused. Verify it or export it.
``` ```
Here are two warnings in bashbots scripts. The first is a hint you may use shell substitions instead of sed, this is really possible and much faster! The example show two warnings in bashbots scripts. The first is a hint you may use shell substitions instead of sed, this is fixed and much faster as the "echo | sed" solution.
The second warning is about an unused variable, this is true because in our examples CONTACT is not used but assigned in case you want to use it :-) The second warning is about an unused variable, this is true because in our examples CONTACT is not used but assigned in case you want to use it :-)
#### $$VERSION$$ v0.60-rc2-3-g4a944d9 #### [Prev Best Practice](5_practice.md)
#### [Next Functions Reference](6_reference.md)
#### $$VERSION$$ v0.60-rc2-4-g1bf26b9

22
doc/6_reference.md
View File

@ -152,12 +152,12 @@ If your Bot is Admin of a chat he can kick and ban a user.
##### unban_chat_member ##### unban_chat_member
If your Bot is Admin af a chat he can unban a kicked user. If your Bot is Admin of a chat he can unban a kicked user.
*usage:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}" *usage:* unban_chat_member "${CHAT[ID]}" "${USER[ID]}"
##### leave_chat ##### leave_chat
Bot will leave chat. Bot will leave given chat.
*usage:* leave_chat "${CHAT[ID]}" *usage:* leave_chat "${CHAT[ID]}"
@ -171,14 +171,14 @@ fi
---- ----
##### user_is_creator ##### user_is_creator
Returns true (0) if user is creator of chat or chat is a private chat. Return true (0) if user is creator of given chat or chat is a private chat.
*usage:* user_is_creator "${CHAT[ID]}" "${USER[ID]}" *usage:* user_is_creator "${CHAT[ID]}" "${USER[ID]}"
*alias:* _is_creator *alias:* _is_creator
##### user_is_admin ##### user_is_admin
Returns true (0) if user is admin or creator of chat. Return true (0) if user is admin or creator of given chat.
*usage:* user_is_admin "${CHAT[ID]}" "${USER[ID]}" *usage:* user_is_admin "${CHAT[ID]}" "${USER[ID]}"
@ -193,8 +193,8 @@ fi
``` ```
##### user_is_botadmin ##### user_is_botadmin
Returns true (0) if user is owner / admin of bot. Return true (0) if user is owner / admin of bot.
botadmin is stored in file './botadmin' Name or ID botadmin must be placed in './botadmin' file.
*usage:* user_is_botadmin "${CHAT[ID]}" "${USER[ID]}" *usage:* user_is_botadmin "${CHAT[ID]}" "${USER[ID]}"
@ -220,7 +220,7 @@ fi
### Interactive and backgound jobs ### Interactive and backgound jobs
##### startproc ##### startproc
```startproc``` tarts a script (or C or python program etc.) running in parallel to your Bot. The text that the script outputs is sent time to the user or chat, user input will be sent back to the script. see [Advanced Usage](3_advanced.md#Interactive-Chats) ```startproc``` starts a script (or C or python program etc.) running in parallel to your Bot. The text that the script outputs is sent to the user or chat, user input will be sent back to the script. see [Advanced Usage](3_advanced.md#Interactive-Chats)
*usage:* startproc "./script" *usage:* startproc "./script"
@ -230,7 +230,7 @@ startproc './calc'
``` ```
##### checkproc ##### checkproc
Returns true (0) if an interactive script active in the given chat. Return true (0) if an interactive script active in the given chat.
*usage:* checkprog *usage:* checkprog
@ -272,7 +272,7 @@ background "./notify" "notify"
``` ```
##### checkback ##### checkback
Returns true (0) if an background job is active in the given chat. Return true (0) if an background job is active in the given chat.
*usage:* checkback "jobname" *usage:* checkback "jobname"
@ -346,5 +346,7 @@ The name of your bot is availible as bash variable "$ME", there is no need to ca
##### inproc ##### inproc
Send Input from Telegram to waiting Interactive Chat. Send Input from Telegram to waiting Interactive Chat.
#### $$VERSION$$ v0.60-rc2-3-g4a944d9 #### [Prev Best Practice](5_practice.md)
#### $$VERSION$$ v0.60-rc2-4-g1bf26b9