pebbles-bot 0.3.3

Description:

pebblesbot 0.3.3

Table of content

Table of content
Introduction

What It Can Do Now
What It Will Do In The Future
Is it secure to run a public bot with direct access to a server?


Deploy
Run Pebbles
Command Guide
Prefix

Running Pebbles in a Docker container
Configuration file



Introduction
Pebbles 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:

Ask BotFather to 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 my blog post.
What It Can Do Now
At 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 Future

More 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 😅
Deploy

Ask BotFather to create a bot, then save it's API key
Install the bot with pip python -m pip install pebbles_bot
Note Alternatively the bot can be ran in a container, see Prefix
Define 2 environment variables:

PEBBLES_BOT_TOKEN - the API key of the bot
PEBBLES_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 /start command on it.


Optionally a yaml configuration file can be used to list users and set other options.
See Configuration file for more details.

Run Pebbles
Pebbles 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:
pebot

Send notifications with Pebbles:
echo 'Testing Notifications!' | pebot --notify

Command Guide

/start -> start interacting with Pebbles.
/help -> print all available commands.
/mode -> choose Pebbles mode

local: run commands on the server it's deployed
remote: 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:

hostname
should be the same as in ~/.ssh/config
confirmation
select Yes to establish a connection, No to 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 returned

Prefix
Running Pebbles in a Docker container
Note This is not the recommended installation method, more like a fun alternative 😉
Create a $HOME/.pebbles/pebbles.yaml configuration file first
(.pebbles will be mounted to the container) and run:
docker run -d --name pebot \
--volume $HOME/.pebbles:/root/.pebbles \
labbratnet/pebbles:0.1.1

Alternatively, there is a Docker image for this bot in Docker/Dockerfile
which can be customized. To use it, navigrate to Docker and run:
docker build -t pebbles .
docker run -d --name pebot \
--volume $HOME/.pebbles:/root/.pebbles \
pebbles

Configuration file
The default location is $HOME/pebbles.yaml, but it can be changed by setting the PEBBLES_CONFIG environment variable.
Example of the configuration file:
whitelist_ids:
- 123456789
- 987654321

Note If both environment variables and configuration file are defined, the environment variables will take precedence.