Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kpe/telerembash

Telegram Remoting Bot
https://github.com/kpe/telerembash

Last synced: about 2 months ago
JSON representation

Telegram Remoting Bot

Awesome Lists containing this project

README 

        
TeleRemBash

===========



|Build Status| |Coverage Status| |Version Status| |Python Versions| |Downloads|



``TeleRemBash`` is a `Telegram`_ `Bot`_ for executing

scripts on a remote system, baked with `TOTP`_ Authentication

for a secure and easy setup (QR codes).



To keep things simple ``TeleRamBash`` allows a single Telegram user

after a successful `TOTP`_ Authentication to execute a pre-defined

(bash) script by sending a command to the Bot in a Telegram chat, like this:



.. code:: bash



    /do some-script optional-param1



|ASCIINEMA|



Usage

-----

To install from pypi:



.. code:: bash



    pip install telerembash



First create a configuration for your Telegram Bot instance by specifying

the bot's ``API_TOKEN`` and the Telegram username of the whitelisted user:



.. code:: bash



   telerem init --api-token API_TOKEN --username USERNAME



this should create a ``telerem.config.yaml`` in the current directory

and output a QR Code to be scanned in your TOTP Authenticator App (i.e.

`Google Authenticator`_, `andOTP`_, etc).



To see all available options, try:



.. code:: bash



    telerem --help



you can edit ``telerem.config.yaml`` by hand or call ``telerem init`` multiple times,

to tweak the config.

Note the ``scripts_root`` in the config - this is the location (absolute or relative to

the current working directory) of the directory containing the script your bot will

execute.



To start the bot:



.. code:: bash



    telerem start --config config.yaml



Once your bot is running, you should add it in a chat.

It will ignore all your messages until it sees a



.. code:: bash



    /auth 



command, where ```` is the authentication code generated by

your TOTP Authenticator.



And once you are successfully authenticated, you can execute a script

by sending a Telegram message like this:



.. code:: bash



    /do some-script-name param1 param2



The bot will reply to a ``/do`` command by looking under ``scripts_root`` for

a file with the name ``some-script-name`` or ``some-script-name.sh``

and executing it (with the provided optional parameters).



Run as a Service (WIP)

----------------------

You can also create a systemd service or a daemon script for

running your bot in the background like this:



.. code:: bash



    telerem install --systemd | sudo bash  # for systemd

    telerem install --initd   | sudo bash  #   otherwise



this will:



 1. create a system user ``teleremd``

 2. setup a python venv under ``/home/teleremd/``

 3. create a service (either ``systemd`` or ``init.d``):



   * systemd service unit ``/etc/systemd/system/teleremd.service``

   * deamon script ``/etc/init.d/teleremd``



 4. populate the daemon configuration under ``/etc/teleremd.config.yaml``



and finally:



.. code:: bash



   sudo systemctl daemon-reload   # for systemd

   sudo systemctl start teleremd



NEWS

----

 - **21.Jan.2021** - available on pypi

 - **16.Jan.2021** - install as a systemd service (init.d still WIP)

 - **15.Jan.2021** - README: Usage instructions

 - **09.Jan.2021** - initial commit



LICENSE

-------



MIT. See `License File `_.



Resources

---------



- `Telegram`_ - Telegram BOT API

- `PyOTP`_ - The Python One-Time Password Library

- `python-qrcode`_ - QR code generator for text terminals



.. _`python-qrcode`: https://github.com/lincolnloop/python-qrcode

.. _`PyOTP`: https://github.com/pyauth/pyotp

.. _`TOTP`: https://en.wikipedia.org/wiki/Time-based_One-Time_Password

.. _`Telegram`: https://core.telegram.org/api

.. _`Bot`: https://core.telegram.org/bots

.. _`Google Authenticator`: https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2

.. _`andOTP`: https://play.google.com/store/apps/details?id=org.shadowice.flocke.andotp



.. |Build Status| image:: https://travis-ci.com/kpe/telerembash.svg?branch=master

   :target: https://travis-ci.com/kpe/telerembash

.. |Coverage Status| image:: https://coveralls.io/repos/kpe/telerembash/badge.svg?branch=master

   :target: https://coveralls.io/r/kpe/telerembash?branch=master

.. |Version Status| image:: https://badge.fury.io/py/telerembash.svg

   :target: https://badge.fury.io/py/telerembash

.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/telerembash.svg

.. |Downloads| image:: https://img.shields.io/pypi/dm/telerembash.svg

.. |Twitter| image:: https://img.shields.io/twitter/follow/siddhadev?logo=twitter&label=&style=

   :target: https://twitter.com/intent/user?screen_name=siddhadev

.. |ASCIINEMA| image:: telerembash.svg?raw=true&sanitize=true

   :target: https://asciinema.org/a/7p3UUcdffGQDyfBhBf5cm8tBw?t=5&speed=3