octoleo
/
telegram-bot-bash
mirror of https://github.com/octoleo/telegram-bot-bash.git
1
1
Fork 0
Code Issues Projects Releases Wiki Activity

update documentation

This commit is contained in:
Kay Marquardt (Gnadelwartz) 2020-07-28 09:14:57 +02:00
parent 3daf84dad8
commit acf9d8432f
6 changed files with 61 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
README.html
View File

@ -191,7 +191,7 @@ It features background tasks and interactive chats, and can serve as an interfac
<p>Running a Telegram Bot means it is connected to the public and you never know what's send to your Bot.</p>
<p>Bash scripts in general are not designed to be bullet proof, so consider this Bot as a proof of concept. Bash programmers often struggle with 'quoting hell' and globbing, see <a href="https://unix.stackexchange.com/questions/171346/security-implications-of-forgetting-to-quote-a-variable-in-bash-posix-shells">Implications of wrong quoting</a></p>
<p>Whenever you are processing input from untrusted sources (messages, files, 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 examples from your Bot, e.g. scripts 'notify', 'calc', 'question', and disable all not used commands.</p>
<p><strong>Note:</strong> Until v0.941 (mai/22/2020) telegram-bot-bash had a remote code execution (RCE) bug, please update if you use an older version! see <a href="https://github.com/topkecleon/telegram-bot-bash/issues/125">Issue #125</a></p>
<p><strong>Note:</strong> Up to version v0.941 (mai/22/2020) telegram-bot-bash had a remote code execution (RCE) bug, please update if you use an older version! see <a href="https://github.com/topkecleon/telegram-bot-bash/issues/125">Issue #125</a></p>
<p>One of the most powerful features of unix shells is variable and command substitution using <code>${}</code> and <code>$()</code>, but as they are expanded in double quotes, this can lead to RCE and information disclosing bugs in complex scripts like bashbot. So it's more secure to escape or remove '$' in input from user, files or network.</p>
<p>A powerful tool to improve your scripts is <code>shellcheck</code>. You can <a href="https://www.shellcheck.net/">use it online</a> or <a href="https://github.com/koalaman/shellcheck#installing">install shellcheck locally</a>. Shellcheck is used extensive in bashbot development to ensure a high code quality, e.g. it's not allowed to push changes without passing all shellcheck tests. In addition bashbot has a <a href="doc/7_develop.md">test suite</a> to check if important functionality is working as expected.</p>
<h3>Use printf whenever possible</h3>
@ -217,12 +217,12 @@ It features background tasks and interactive chats, and can serve as an interfac
<p><strong>Never run your Bot as root, this is the most dangerous you can do!</strong> Usually the user 'nobody' has almost no rights on unix/linux systems. See <a href="doc/4_expert.md">Expert use</a> on how to run your Bot as an other user.</p>
<h3>Secure your Bot installation</h3>
<p><strong>Your Bot configuration must no be readable from other users.</strong> Everyone who can read your Bots token is able to act as your Bot and has access to all chats the Bot is in!</p>
<p>Everyone with read access to your Bot files can extract your Bots data. Especially your Bot Token in <code>token</code> must be protected against other users. No one except you should have write access to the Bot files. The Bot should be restricted to have write access to <code>count</code> and <code>tmp-bot-bash</code> only, all other files must be write protected.</p>
<p>Everyone with read access to your Bot files can extract your Bots data. Especially your Bot config in <code>vorconfig.jssh</code> must be protected against other users. No one except you should have write access to the Bot files. The Bot should be restricted to have write access to <code>count.jssh</code> and <code>data-bot-bash</code> only, all other files must be write protected.</p>
<p>To set access rights for your bashbot installation to a reasonable default run <code>sudo ./bashbot.sh init</code> after every update or change to your installation directory.</p>
<h2>FAQ</h2>
<h3>Is this Bot insecure?</h3>
<p>Bashbot is not more (in)secure as any Bot written in an 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 ...</p>
<p><strong>Note:</strong> Until v0.941 (mai/22/2020) telegram-bot-bash has a remote code execution bug, please update if you use an older version!</p>
<p><strong>Note:</strong> Up to version 0.941 (mai/22/2020) telegram-bot-bash had a remote code execution bug, please update if you use an older version!</p>
<h3>Why Bash and not the much better xyz?</h3>
<p>Well, that's a damn good question ... may be because I'm an unix admin from stone age. Nevertheless there are more reasons from my side:</p>
<ul>
@ -235,7 +235,7 @@ It features background tasks and interactive chats, and can serve as an interfac
<p>At the beginning bashbot was simply the file <code>bashbot.sh</code> you can copy everywhere and run the bot. Now we have 'commands.sh', 'mycommands.sh', 'modules/*.sh' and much more.</p>
<p>Hey no Problem, if you are finished with your cool bot run <code>dev/make-standalone.sh</code> to create a stripped down Version of your bot containing only 'bashbot.sh' and 'commands.sh'! For more information see <a href="doc/7_develop.md">Create a stripped down Version of your Bot</a></p>
<h3>Can I send messages from CLI and scripts?</h3>
<p>Of course, you can send messages from CLI and scripts, simply install bashbot as <a href="#Your-really-first-bashbot-in-a-nutshell">described here</a>, send the message '/start' to set yourself as botadmin and stop the bot with <code>./bashbot.sh kill</code>.</p>
<p>Of course, you can send messages from CLI and scripts, simply install bashbot as <a href="#Your-really-first-bashbot-in-a-nutshell">described here</a>, send the message '/start' to set yourself as botadmin and stop the bot with <code>./bashbot.sh stop</code>.</p>
<p>Run the following commands in your bash shell or script while you are in the installation directory:</p>
<div class="sourceCode" id="cb5"><pre class="sourceCode bash"><code class="sourceCode bash"><a class="sourceLine" id="cb5-1" title="1"><span class="co"># prepare bash / script to send commands</span></a>
<a class="sourceLine" id="cb5-2" title="2"><span class="bu">export</span> <span class="va">BASHBOT_HOME=</span><span class="st">&quot;</span><span class="va">$(</span><span class="bu">pwd</span><span class="va">)</span><span class="st">&quot;</span></a>
@ -269,6 +269,6 @@ It features background tasks and interactive chats, and can serve as an interfac
<p>@Gnadelwartz</p>
<h2>That's it!</h2>
<p>If you feel that there's something missing or if you found a bug, feel free to submit a pull request!</p>
<h4>$$VERSION$$ 0.99-0-g2775000</h4>
<h4>$$VERSION$$ 0.99-1-g3daf84d</h4>
</body>
</html>

10
README.md
View File

@ -129,7 +129,7 @@ Bash scripts in general are not designed to be bullet proof, so consider this Bo
Whenever you are processing input from untrusted sources (messages, files, 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 examples from your Bot, e.g. scripts 'notify', 'calc', 'question', and disable all not used commands.
**Note:** Until v0.941 (mai/22/2020) telegram-bot-bash had a remote code execution (RCE) bug, please update if you use an older version!
**Note:** Up to version v0.941 (mai/22/2020) telegram-bot-bash had a remote code execution (RCE) bug, please update if you use an older version!
see [Issue #125](https://github.com/topkecleon/telegram-bot-bash/issues/125)
One of the most powerful features of unix shells is variable and command substitution using ```${}``` and ```$()```,
@ -178,7 +178,7 @@ For the same reason every file your Bot can read is in danger to be disclosed. R
### Secure your Bot installation
**Your Bot configuration must no be readable from other users.** Everyone who can read your Bots token is able to act as your Bot and has access to all chats the 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 except you should have write access to the Bot files. The Bot should be restricted to have write access to ```count``` and ```tmp-bot-bash``` only, all other files must be write protected.
Everyone with read access to your Bot files can extract your Bots data. Especially your Bot config in ```vorconfig.jssh``` must be protected against other users. No one except you should have write access to the Bot files. The Bot should be restricted to have write access to ```count.jssh``` and ```data-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.
@ -187,7 +187,7 @@ To set access rights for your bashbot installation to a reasonable default run `
### Is this Bot insecure?
Bashbot is not more (in)secure as any Bot written in an 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 ...
**Note:** Until v0.941 (mai/22/2020) telegram-bot-bash has a remote code execution bug, please update if you use an older version!
**Note:** Up to version 0.941 (mai/22/2020) telegram-bot-bash had a remote code execution bug, please update if you use an older version!
### Why Bash and not the much better xyz?
Well, that's a damn good question ... may be because I'm an unix admin from stone age. Nevertheless there are more reasons from my side:
@ -205,7 +205,7 @@ Hey no Problem, if you are finished with your cool bot run ```dev/make-standalon
### 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),
send the message '/start' to set yourself as botadmin and stop the bot with ```./bashbot.sh kill```.
send the message '/start' to set yourself as botadmin and stop the bot with ```./bashbot.sh stop```.
Run the following commands in your bash shell or script while you are in the installation directory:
@ -261,4 +261,4 @@ bashbotBlockRecover() {
If you feel that there's something missing or if you found a bug, feel free to submit a pull request!
#### $$VERSION$$ 0.99-0-g2775000
#### $$VERSION$$ 0.99-1-g3daf84d

18
README.txt
View File

@ -170,8 +170,8 @@ globbing (set -f) and quote everything. In addition delete unused scripts and
examples from your Bot, e.g. scripts 'notify', 'calc', 'question', and disable
all not used commands.
**Note:** Until v0.941 (mai/22/2020) telegram-bot-bash had a remote code
execution (RCE) bug, please update if you use an older version!
**Note:** Up to version v0.941 (mai/22/2020) telegram-bot-bash had a remote
code execution (RCE) bug, please update if you use an older version!
see [Issue #125](https://github.com/topkecleon/telegram-bot-bash/issues/125)
One of the most powerful features of unix shells is variable and command
@ -241,10 +241,10 @@ can read your Bots token is able to act as your Bot and has access to all chats
the 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 except you should have write access to the Bot files. The Bot should be
restricted to have write access to ```count``` and ```tmp-bot-bash``` only,
all other files must be write protected.
Especially your Bot config in ```vorconfig.jssh``` must be protected against
other users. No one except you should have write access to the Bot files. The
Bot should be restricted to have write access to ```count.jssh``` and
```data-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
@ -257,7 +257,7 @@ Bashbot is not more (in)secure as any Bot written in an 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 ...
**Note:** Until v0.941 (mai/22/2020) telegram-bot-bash has a remote code
**Note:** Up to version 0.941 (mai/22/2020) telegram-bot-bash had a remote code
execution bug, please update if you use an older version!
### Why Bash and not the much better xyz?
@ -286,7 +286,7 @@ down Version of your Bot](doc/7_develop.md)
Of course, you can send messages from CLI and scripts, simply install bashbot
as [described here](#Your-really-first-bashbot-in-a-nutshell),
send the message '/start' to set yourself as botadmin and stop the bot with
```./bashbot.sh kill```.
```./bashbot.sh stop```.
Run the following commands in your bash shell or script while you are in the
installation directory:
@ -351,4 +351,4 @@ wait
If you feel that there's something missing or if you found a bug, feel free to
submit a pull request!
#### $$VERSION$$ 0.99-0-g2775000
#### $$VERSION$$ 0.99-1-g3daf84d

4
doc/2_usage.md
View File

@ -3,7 +3,7 @@
The Bots standard commands are in the commands dispatcher ```commands.sh```, Do not edit this file! Add your commands and functions to ```mycommands.sh```. In 'mycommands.sh.dist' you find examples how to add own commands and overwrite existing ones. See [Best practices](5_practice.md) for more information.
Once you're done with editing start the Bot with ```./bashbot.sh start```. To stop the Bot run ```./bashbot.sh kill```
Once you're done with editing start the Bot with ```./bashbot.sh start```. To stop the Bot run ```./bashbot.sh stop```
If something doesn't work as expected, debug with ```./bashbot.sh startbot DEBUG &```, where DEBUG can be 'debug', 'xdebug' or 'xdebugx'.
See [Bashbot Development](7_develop.md) for more information.
@ -283,5 +283,5 @@ send_action "${CHAT[ID]}" "action"
#### [Prev Create Bot](1_firstbot.md)
#### [Next Advanced Usage](3_advanced.md)
#### $$VERSION$$ 0.99-0-g2775000
#### $$VERSION$$ 0.99-1-g3daf84d

43
doc/4_expert.md
View File

@ -136,29 +136,27 @@ If you have sourced 'bashbot.sh' you have the following bashot internal variable
```bash
COMMANDS # default: ./commands.sh"
MODULEDIR # default: ./modules"
TOKENFILE # default: ./token"
BOTADMIN # default: ./botadmin"
BOTACL # default: ./botacl"
TMPDIR # default: ./data-bot-bash"
COUNTFILE # default: ./count"
COUNTFILE # default: ./count" (jsonDB file)
BOTTOKEN # default: content of ${TOKENFILE}
BOTTOKEN # your token read from bot config
URL # telegram api URL - default: https://api.telegram.org/bot${BOTTOKEN}"
```
#### Interactive use
For testing your setup or sending messages yoursel you can use bashbot functions from bash command line:
For testing your setup or sending messages yourself its possible to use bashbot functions from command line:
```bash
# are we running bash?
echo $SHELL
/bin/bash
# source bashbot.sh WITHOUT BASHBOT_HOME set
./bashbot.sh source
source ./bashbot.sh source
# output bashbot internal variables
echo $COMMANDS $MODULEDIR $TOKENFILE $BOTADMIN $BOTACL $TMPDIR $COUNTFILE
./commands.sh ./modules ./token ./botadmin ./botacl ./data-bot-bash ./count
echo $COMMANDS $MODULEDIR $BOTACL $TMPDIR $COUNTFILE
./commands.sh ./modules ./botacl ./data-bot-bash ./count
# source bashbot.sh WITH BASHBOT_HOME set
@ -166,9 +164,9 @@ export BASHBOT_HOME=/usr/local/telegram-bot-bash
source ./bashbot.sh source
# output bashbot internal variables
echo $COMMANDS $MODULEDIR $TOKENFILE $BOTADMIN $BOTACL $TMPDIR $COUNTFILE
/usr/local/telegram-bot-bash/commands.sh /usr/local/telegram-bot-bash/modules /usr/local/telegram-bot-bash/token
/usr/local/telegram-bot-bash/botadmin /usr/local/telegram-bot-bash/botacl /usr/local/telegram-bot-bash/data-bot-bash
echo $COMMANDS $MODULEDIR $BOTACL $TMPDIR $COUNTFILE
/usr/local/telegram-bot-bash/commands.sh /usr/local/telegram-bot-bash/modules
/usr/local/telegram-bot-bash/botacl /usr/local/telegram-bot-bash/data-bot-bash
/usr/local/telegram-bot-bash/count
```
@ -178,24 +176,24 @@ User or Chat you are in. See [Send Messages](2_usage.md#sending-messages).
*Examples:* You can test this by sending messages to yourself:
```bash
# fist Hello World
send_normal_message "$(< $BOTADMIN)" "Hello World! This is my first message"
send_normal_message "$(getConfigKey "botadmin")" "Hello World! This is my first message"
# now with some markdown and HTML
send_markdown_message "$(< $BOTADMIN)" '*Hello World!* _This is my first markdown message_'
send_html_message "$(< $BOTADMIN)" '<b>Hello World!</b> <em>This is my first HTML message</em>'
send_keyboard "$(< $BOTADMIN)" 'Do you like it?' '[ "Yep" , "No" ]'
send_markdown_message "$(getConfigKey "botadmin")" '*Hello World!* _This is my first markdown message_'
send_html_message "$(getConfigKey "botadmin")" '<b>Hello World!</b> <em>This is my first HTML message</em>'
send_keyboard "$(getConfigKey "botadmin")" 'Do you like it?' '[ "Yep" , "No" ]'
```
Now something more useful ...
```bash
# sending output from system commands:
send_normal_message "$(< $BOTADMIN)" "$(date)"
send_normal_message "$(getConfigKey "botadmin")" "$(date)"
send_normal_message "$(< $BOTADMIN)" "$(uptime)"
send_normal_message "$(getConfigKey "botadmin")" "$(uptime)"
send_normal_message "$(< $BOTADMIN)" '`'$(free)'`'
send_normal_message "$(getConfigKey "botadmin")" '`'$(free)'`'
# same but markdown style 'code' (monospaced)
send_markdown_message "$(< $BOTADMIN)" "\`$(free)\`"
send_markdown_message "$(getConfigKey "botadmin")" "\`$(free)\`"
```
@ -211,7 +209,7 @@ If you want to have other locations for config, data etc, define and export the
**Note: all specified directories and files must exist or running 'bashbot.sh' will fail.**
##### BASHBOT_ETC
Location of the files ```commands.sh```, ```mycommands.sh```, ```token```, ```botadmin```, ```botacl``` ...
Location of the files ```commands.sh```, ```mycommands.sh```, ```botconfig.jssh```, ```botacl``` ...
```bash
unset BASHBOT_ETC # keep in telegram-bot-bash (default)
export BASHBOT_ETC "" # keep in telegram-bot-bash
@ -225,7 +223,7 @@ Location of the files ```commands.sh```, ```mycommands.sh```, ```token```, ```bo
e.g. /etc/bashbot
##### BASHBOT_VAR
Location of runtime data ```data-bot-bash```, ```count```
Location of runtime data ```data-bot-bash```, ```count.jssh```
```bash
unset BASHBOT_VAR # keep in telegram-bot-bash (default)
export BASHBOT_VAR "" # keep in telegram-bot-bash
@ -338,7 +336,6 @@ for every poll until the maximum of BASHBOT_SLEEP ms.
```
#### Tested configs as of v0.90 release
**Note: Environment variables are not stored, you must setup them before every call to bashbot.sh, e.g. from a script.**
##### simple Unix like config, for one bot. bashbot is installed in '/usr/local/telegram-bot-bash'
```bash
@ -381,5 +378,5 @@ for every poll until the maximum of BASHBOT_SLEEP ms.
#### [Prev Advanced Use](3_advanced.md)
#### [Next Best Practice](5_practice.md)
#### $$VERSION$$ 0.99-0-g2775000
#### $$VERSION$$ 0.99-1-g3daf84d

34
doc/5_practice.md
View File

@ -10,7 +10,9 @@ In addition you should know about [BotFather, the one bot to rule them all](http
If you don't have a github account, it may time to [setup a free account now](https://github.com/pricing)
### Add commands to mycommands.sh only
To ease updates never change ```bashbot.sh```, instead your commands and functions must go to ```mycommands.sh``` . Insert your Bot commands in the ```case ... esac``` block of the 'mycommands()' function:
Do not change ```bashbot.sh``` and ```commands.sh```, instead place your commands in to ```mycommands.sh```.
To start with a clean/minimal bot copy ```mycommands.sh.clean``` to ```mycommands.sh``` and start editing
the message strings and place commands in the```case ... esac``` block of the function mycommands():
```bash
# file: mycommands.sh
# your additional bahsbot commands
@ -35,33 +37,37 @@ mycommands() {
}
```
### Overwrite, extend and disable global commands
### DIsable, replace and extend global commands
You can overwrite a global bashbot command by placing the same commands in ```mycommands.sh``` and add ```return 1```
ad the end of your command, see '/kickme' below.
Global bashbot command processing, e.g. /start, /info etc. is disabled if you return a non zero value from ```mycommands.sh```,
see /start example below.
To disable a global bashbot command place create a command simply containing 'return 1', see '/leave' below.
To replace a global bashbot command add the same command to ```mycommands.sh``` and place ```return 1``` at the end of
the case block, see /kickme example below.
In case you want to add some processing to the global bashbot command add ```return 0```, then both command will be executed.
If a command is available as a global command and in ```mycommands.sh```, plus you return a zero value (nothing or 0)
both command sections are processed. Thus you can extend global commands with additional actions, see /info example below
**Learn more about [Bot commands](https://core.telegram.org/bots#commands).**
```bash
# file: commands.sh
# file: mycommands.sh
case "$MESSAGE" in
##########
# command overwrite examples
'info'*) # output date in front of regular info
send_normal_message "${CHAT[ID]}" "$(date)"
return 0
# disable start command
'/start'*) # disable all commands starting with leave
return 1
;;
# replace command with your own actions
'/kickme'*) # this will replace the /kickme command
send_markdown_mesage "${CHAT[ID]}" "*This bot will not kick you!*"
return 1
;;
'/leave'*) # disable all commands starting with leave
return 1
# extend global command
'/info'*) # output date in front of regular info
send_normal_message "${CHAT[ID]}" "$(date)"
return 0
;;
esac
```
@ -152,5 +158,5 @@ The second warning is about an unused variable, this is true because in our exam
#### [Prev Best Practice](5_practice.md)
#### [Next Functions Reference](6_reference.md)
#### $$VERSION$$ 0.99-0-g2775000
#### $$VERSION$$ 0.99-1-g3daf84d