🤖🔒 TeleSSHBot

Bot de Telegram em Python que permite executar comandos no seu computador via SSH, diretamente pelo chat do Telegram.

⚡ Funcionalidades

Comando	Descrição
/start	Mensagem de boas-vindas
/help	Lista todos os comandos
/status	Verifica conexão SSH
/exec <cmd>	Executa um comando shell
/upload <caminho>	Envia um arquivo do servidor
/sysinfo	CPU, RAM, disco, uptime
/ip	IP público e local

💡 Qualquer texto enviado sem / é automaticamente executado como comando shell.

🔒 Segurança

• Whitelist de usuários — Apenas IDs autorizados podem usar o bot
• Bloqueio de comandos perigosos — rm -rf /, shutdown, mkfs, etc.
• Variáveis de ambiente — Credenciais nunca ficam no código
• Logging — Todos os comandos são registrados em log

🚀 Setup

1. Pré-requisitos

• uv — gerenciador de pacotes/ambientes Python
• Python 3.12+ (gerenciado automaticamente pelo uv)
• Servidor SSH ativo na máquina alvo
• Token de bot do Telegram (obtido via @BotFather)
• Seu Telegram User ID (obtido via @userinfobot)

Instalar o uv (caso ainda não tenha)

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Instalação

# Clonar o repositório
git clone https://github.com/seu-usuario/telesshbot.git
cd telesshbot

# Instalar dependências e criar ambiente virtual automaticamente
uv sync

O uv sync cria o .venv, instala o Python correto e todas as dependências em um único comando.

3. Configuração

# Copiar template de configuração
cp .env.example .env

# Editar com suas credenciais
nano .env

Preencha os seguintes campos no .env:

Variável	Descrição
TELEGRAM_BOT_TOKEN	Token do bot (do @BotFather)
AUTHORIZED_USERS	Seu Telegram User ID
SSH_HOST	Host SSH (use localhost para a própria máquina)
SSH_PORT	Porta SSH (padrão: 22)
SSH_USERNAME	Seu usuário do sistema
SSH_PASSWORD	Senha SSH (ou deixe vazio e use chave)
SSH_KEY_PATH	Caminho da chave privada (ex: ~/.ssh/id_rsa)

4. Executar

# Forma recomendada — usa o script registrado no pyproject.toml
uv run telesshbot

# Alternativa
uv run python main.py

# Ou com o módulo diretamente
uv run python -m bot.main

Não precisa ativar o .venv manualmente! O uv run cuida disso automaticamente.

🔑 Como obter o Token do Bot

1. Abra o Telegram e procure por @BotFather
2. Envie /newbot
3. Escolha um nome para o bot (ex: "Meu SSH Bot")
4. Escolha um username (ex: "meu_ssh_bot")
5. O BotFather retornará o token — copie para o .env

🆔 Como obter seu User ID

1. Abra o Telegram e procure por @userinfobot
2. Envie /start
3. O bot responderá com seu ID — copie para o .env

📁 Estrutura do Projeto

telesshbot/
├── bot/
│   ├── __init__.py       # Pacote do bot
│   ├── main.py           # Entry point
│   ├── handlers.py       # Handlers dos comandos
│   ├── ssh_client.py     # Cliente SSH (Paramiko)
│   ├── security.py       # Whitelist e bloqueio
│   └── utils.py          # Utilitários
├── main.py               # Entry point raiz (uv run python main.py)
├── pyproject.toml        # Configuração do projeto e dependências (uv)
├── uv.lock               # Lock file das dependências
├── .python-version       # Versão do Python fixada
├── .env.example          # Template de configuração
├── .gitignore
└── README.md

🛠️ Comandos úteis com uv

# Instalar dependências
uv sync

# Adicionar nova dependência
uv add <pacote>

# Adicionar dependência de desenvolvimento
uv add --dev <pacote>

# Rodar linter
uv run ruff check .

# Rodar testes
uv run pytest

# Ver pacotes instalados
uv pip list

# Atualizar todas as dependências
uv lock --upgrade

⚠️ Aviso de Segurança

Este bot dá acesso shell ao seu computador. Use com responsabilidade:

• Nunca compartilhe o token do bot
• Mantenha a whitelist atualizada
• Não rode como root
• Monitore os logs (telesshbot.log)