telerembash 0.2.8
A Telegram Remote Shell Bot with HOTP authentication.
License: MIT
Requires Python: >=3.5
Keywords: telegram totp hotp authentication bot

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 <code>

command, where ``<code>`` 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 <https://github.com/kpe/telerembash/blob/master/LICENSE.txt>`_.


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