Package: pebbles-bot
Table of contentTable of contentIntroductionWhat It Can Do NowWhat It Will Do In The FutureIs it secure to run a public bot with direct access to a server?DeployRun PebblesCommand GuidePrefixRunning Pebbles in a Docker containerConfiguration fileIntroductionPebbles is a bot which allows users to run shell commands on their Linux servers from Telegram.There are only 3 steps to get it up and running:AskBotFatherto create a bot and save its API key.Install the bot on the server where you wish to run commands using Python pip.Configure environment variables and run it!More about the usage of Pebbles can be found on myblog post.What It Can Do NowAt this stage Pebbles is not very sophisticated, it can:Run commands locally.Establish a SSH connection to another host and run commands there.Send a notification by piping stdout.Users whitelist - only whitelisted users can run commands on the bot.What It Will Do In The FutureMore built-in commands to do various tasks without entering long commands.Commands whitelist - only whitelisted commands can be run on the bot.Log parser that will block users or even shut the bot down if it detects a malicious activity.Is it secure to run a public bot with direct access to a server?The bot's channel is encrypted via Telegram's proprietary protocol - MTProto, and the API
also uses appropriate security measures, therefore there are no issues from Telegram's side.
However, the bot is still a public service, and anyone on the internet can attempt to use it
(if they find bot's handle). That is why Pebbles has a whitelisting mechanism to only allow
certain users to run commands on it.In general I'd say it's pretty safe to use, but don't use it on important production servers 😅DeployAskBotFatherto create a bot, then save it's API keyInstall the bot with pippython -m pip install pebbles_botNoteAlternatively the bot can be ran in a container, seePrefixDefine 2 environment variables:PEBBLES_BOT_TOKEN- the API key of the botPEBBLES_BOT_USERS- a comma-separated list of Telegram user IDs that will be whitelisted.
User ID can be obtained from a public bot@userinfobot, by calling/startcommand on it.Optionallya yaml configuration file can be used to list users and set other options.
SeeConfiguration filefor more details.Run PebblesPebbles provides two modes of operation: Proxy and Notification modes.
In Proxy mode, will run commands that users send from Telegram on the server it's deployed on.
And in Notification mode it will send a Linux command/service output to the user from the server.Run in proxy mode:pebotSend notifications with Pebbles:echo'Testing Notifications!'|pebot--notifyCommand Guide/start-> start interacting with Pebbles./help-> print all available commands./mode-> choose Pebbles modelocal: run commands on the server it's deployedremote: run commands on the remote server. To use this option a connection must be first established by/login./login-> establish a SSH connection to a remote host using information from~/.ssh/config. User will be prompted for:hostnameshould be the same as in~/.ssh/configconfirmationselectYesto establish a connection,Noto cancel./logout-> to terminate the SSH connection/run-> run a shell command, where it runs depends on/mode. After command call user will be prompted to enter a command, stdout or stderr will be returnedPrefixRunning Pebbles in a Docker containerNoteThis is not the recommended installation method, more like a fun alternative 😉Create a$HOME/.pebbles/pebbles.yamlconfiguration file first
(.pebbleswill be mounted to the container) and run:dockerrun-d--namepebot\--volume$HOME/.pebbles:/root/.pebbles\labbratnet/pebbles:0.1.1Alternatively, there is a Docker image for this bot inDocker/Dockerfilewhich can be customized. To use it, navigrate toDockerand run:dockerbuild-tpebbles.
dockerrun-d--namepebot\--volume$HOME/.pebbles:/root/.pebbles\pebblesConfiguration fileThe default location is$HOME/pebbles.yaml, but it can be changed by setting thePEBBLES_CONFIGenvironment variable.Example of the configuration file:whitelist_ids:-123456789-987654321NoteIf both environment variables and configuration file are defined, the environment variables will take precedence.