{"id":22188416,"url":"https://github.com/vmikk/tshbot","last_synced_at":"2025-06-10T21:33:07.539Z","repository":{"id":242687895,"uuid":"810257720","full_name":"vmikk/tshbot","owner":"vmikk","description":"Execute shell commands via Telegram","archived":false,"fork":false,"pushed_at":"2025-01-04T11:56:45.000Z","size":113,"stargazers_count":2,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-04T12:41:44.321Z","etag":null,"topics":["bash","bot","linux","remote-control","shell","telegram"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vmikk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-04T10:55:07.000Z","updated_at":"2025-01-04T11:52:23.000Z","dependencies_parsed_at":"2024-08-09T20:27:45.677Z","dependency_job_id":null,"html_url":"https://github.com/vmikk/tshbot","commit_stats":null,"previous_names":["vmikk/tshbot"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmikk%2Ftshbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmikk%2Ftshbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmikk%2Ftshbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmikk%2Ftshbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vmikk","download_url":"https://codeload.github.com/vmikk/tshbot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236279470,"owners_count":19123439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","bot","linux","remote-control","shell","telegram"],"created_at":"2024-12-02T11:10:24.115Z","updated_at":"2025-01-30T00:28:00.758Z","avatar_url":"https://github.com/vmikk.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tshbot\n\n`tshbot` is a lightweight tool that enables you to execute shell commands on Linux systems via Telegram.\n\nInitially it was developed with the idea of conveniently running commands on devices like Raspberry Pi remotely, eliminating the need to use SSH. Designed for ease of use, `tshbot` does not require complex setups such as VPNs or NAT traversal, simplifying your remote management experience.\n\n\u003cp align=\"middle\"\u003e\n  \u003cimg src=\"assets/tshbot_telegram.webp\"  width=28% height=28% title=\"tshbot - Telegram screenshot\"/\u003e\n\u003c/p\u003e\n\n### Features\n\n- **Secure execution**: Send shell commands securely through your Telegram\n\n- **No complex setup**: Forget about VPNs or NAT traversal - `tshbot` simplifies remote access\n\n- **Shortcuts for commands**: Set up shortcuts to run frequently used commands quickly and easily\n\n- **Flexibility**: You have the option to run arbitrary shell commands. This can be enabled or disabled based on your preference for security\n\n# Installation\n\n## 0. Set up a Telegram bot \n\n### Create a bot\n\n1. **Start a chat with BotFather:** Open Telegram and search for \"@BotFather\". Start a chat with this bot, which is the official bot creation tool from Telegram;\n2. **Create a new bot:** Send the command `/newbot` to BotFather;\n3. **Set a name for your bot:** Follow the prompts and provide a name for your bot. This will be the public name that users see;\n4. **Set a username for your bot:** Next, you'll need to choose a unique username for your bot (this username must contain \"bot\").\n\nAfter completing these steps, BotFather will provide you with a **token**. This is your bot’s authentication token, which you’ll use to send and receive messages via the Telegram API.\n\n### Obtain chat ID\n\n1. **Start a chat with your bot:** Find your bot on Telegram using the username you set and start a conversation;\n2. **Paste the following URL into your browser**, replacing `\u003cYourBotToken\u003e` with the token you received from BotFather:\n\n   ```\n   https://api.telegram.org/bot\u003cYourBotToken\u003e/getUpdates\n   ```\n\n3. **Find your chat ID:** Look for a number labeled `\"chat\":{\"id\":` in the response.\n\n\n## 1. Download the pre-compiled binary\n\nYou can download the appropriate pre-compiled binary for your platform from the [available releases](https://github.com/vmikk/tshbot/releases).\n\n##### E.g., general Linux release (64-bit `amd64`):\n\n```sh\nmkdir -p ~/bin\nwget \\\n  -O ~/bin/tshbot \\\n  https://github.com/vmikk/tshbot/releases/download/0.2/tshbot-linux-amd64\nchmod +x ~/bin/tshbot\n```\n\n##### Or release for Raspberry Pi Zero 2 W (`arm`):\n\n```sh\nmkdir -p ~/bin\nwget \\\n  -O ~/bin/tshbot \\\n  https://github.com/vmikk/tshbot/releases/download/0.2/tshbot-linux-arm\nchmod +x ~/bin/tshbot\n```\n\n\n## 2. Create a configuration file\n\nCreate a configuration file at `~/.config/tshbot/tshbot.config` with the following content:\n\n``` yaml\nbot_log_file: \"/path/to/your/logfile.log\"\nbash_cmd: \"/bin/bash\"\ntg_bot_token: \"YOUR_TELEGRAM_BOT_TOKEN\"\ntg_bot_chat_id: \"YOUR_TELEGRAM_CHAT_ID\"\ncommand_timeout: 300\nallow_arguments: false\nallowed_cmds:\n  pingg: 'ping -c 3 8.8.8.8'\n  uptime: 'uptime'\n  runscript: 'bash ~/bin/myscript.sh'\n  shell: \"\"\nhelp_message: \"Use /commands to see available commands.\"\n```\nReplace `/path/to/your/logfile.log`, `YOUR_TELEGRAM_BOT_TOKEN`, and `YOUR_TELEGRAM_CHAT_ID` with your actual paths and credentials.  \n\nIn the `allowed_cmds` section of the config, you can configure shortcuts for various shell commands that you wish to use frequently. This section is structured as a dictionary where each entry consists of two parts:\n\n- **Shortcut Name:** The key on the left side of the colon (`:`) represents the name of the shortcut. This is a unique identifier you will use to refer to the command;\n- **Command:** The value on the right side of the colon is the actual command that will be executed in the shell when the shortcut is used.\n\nFor example, the shortcut `pingg` will execute the command `ping -c 3 8.8.8.8`.\n\nParameter `command_timeout` sets the timeout for old commands (in seconds). If the command is older than the timeout, it will be ignored. For example, setting `command_timeout: 300` will ignore commands older than 5 minutes.\n\n### Security considerations\n\n\u003e[!CAUTION]\n\u003e Allowing execution of arbitrary shell commands can be potentially dangerous. \n\u003e It may lead to unauthorized access, system compromise, or data loss. \n\u003e To mitigate these risks, you may remove the `shell` shortcut from the `allowed_cmds` configuration. \n\u003e This will **allow only the white-listed commands** specified in `allowed_cmds`.\n\u003e\n\u003e Similarly, enabling `allow_arguments` can pose security risks as it allows passing arbitrary arguments \n\u003e to white-listed commands. Only enable this feature if you trust the users and have properly sanitized \n\u003e your scripts against malicious input.\n\n## 3. Run the tool\n\n``` sh\n~/bin/tshbot\n```\n\nNow you can send command via Telegram.\n\n# Configuration\n\nThe configuration file (`tshbot.config`) should contain the following fields:\n\n- `bot_log_file`: Path to the log file\n- `bash_cmd`: Path to the bash executable\n- `tg_bot_token`: Telegram bot token\n- `tg_bot_chat_id`: Telegram chat ID for the bot\n- `command_timeout`: Timeout for old commands (in seconds)\n- `allow_arguments`: Enable or disable passing arguments to white-listed commands (default: false)\n- `allowed_cmds`: A map of command shortcuts to the actual shell commands\n- `help_message`: Message displayed when the /help command is issued\n\n# Usage\n\n## Commands\n\n- `/help`: Displays the help message\n- `/commands`: Lists all available commands\n- used-defined shortcuts (specified in `allowed_cmds`): Execute a predefined command based on the shortcut defined in the configuration (e.g., `/cmd`)\n- `/shell` [command]: Executes a shell command directly (if allowed in the configuration)\n\n## Examples\n\nUsing the example configuration file shown above, you can send the following commands via Telegram:\n\n- Sending `/uptime` via Telegram will execute `uptime` on the server.\n- Sending `/shell uname -a` will execute `uname -a` on the server.\n\n## Logging\n\nThe tool logs its activities and command executions to the specified log file. \nMake sure the bot has write permissions to the log file.\n\n# Auto-starting `tshbot` (on Linux-based systems with `systemd`)\n\nTo ensure `tshbot` starts automatically on your system, you can create a `systemd` service file. \nFollow these steps to set it up:\n\n### 1. Create the service file\n\n``` sh\nsudo nano /etc/systemd/system/tshbot.service\n```\n\nAdd the following content to the file:\n``` ini\n[Unit]\nDescription=tshbot service\nAfter=network.target\n\n[Service]\nType=simple\nUser=pi\nExecStart=/home/pi/bin/tshbot\nRestart=on-failure\n\n[Install]\nWantedBy=multi-user.target\n```\n\n- `User=pi`: Change `pi` to the user that should run the service if different\n- `ExecStart=/home/pi/bin/tshbot`: If different, change to the actual path of the `tshbot` binary\n\n### 2. Reload `systemd` and enable the service\n\n```sh\nsudo systemctl daemon-reload\n```\n\nEnable the `tshbot` service to start on boot\n``` sh\nsudo systemctl enable tshbot.service\n```\n\nStart the `tshbot` service\n``` sh\nsudo systemctl start tshbot.service\n```\n\n### 3. Verify the service\n\nTo check the status of the `tshbot` service and to ensure it is running correctly, use:\n``` sh\nsudo systemctl status tshbot.service\n```\n\nIf everything is set up correctly, you should see an active (running) status.\n\n## Managing the Service\n\nTo start the service:\n```sh\nsudo systemctl start tshbot.service\n```\n\nTo stop the service:\n```sh\nsudo systemctl stop tshbot.service\n```\n\nTo restart the service:\n```sh\nsudo systemctl restart tshbot.service\n```\n\nTo check the service logs:\n```sh\nsudo journalctl -u tshbot.service\n```\n\n# Building the binary\n\nTo manually build the `tshbot` binary for different architectures, including ARM for Raspberry Pi, follow these instructions:\n\nPrerequisites\n\n- Go programming language installed on your system. You can download it from the official [Go website](https://go.dev/doc/install)\n- Source code of `tshbot` cloned from the repository\n\n## Building for local system\n\nTo build the binary for your local system, simply run the following command in the project directory:\n\n``` sh\ngo build tshbot.go\n```\n\nThis will generate a binary named `tshbot` in the current directory.\n\n## Building for ARM (e.g., Raspberry Pi)\n\nTo build a binary for ARM architecture use the following command:\n\n``` sh\nenv GOOS=linux GOARCH=arm go build -o tshbot tshbot.go\n```\n\nThis command sets the `GOOS` and `GOARCH` environment variables to target the ARM architecture on Linux systems.\n\n## Building for ARM64\n\nIf you need to build for ARM64 architecture, use this command instead:\n\n``` sh\nenv GOOS=linux GOARCH=arm64 go build -o tshbot-linux-arm64 tshbot.go\n```\n\n\n# Acknowledgments\n\nThis project was inspired by [fnzv/trsh-go](https://github.com/fnzv/trsh-go).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmikk%2Ftshbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvmikk%2Ftshbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmikk%2Ftshbot/lists"}