diff --git a/README.md b/README.md index 6ce81c7..96098f8 100644 --- a/README.md +++ b/README.md @@ -1,143 +1,59 @@ -
- -![TeleOps banner](docs/assets/banner.svg) - # TeleOps -**A unified NOC platform for Telegram — monitor agents, discover SNMP devices, run a live dashboard, and manage Linux and Windows hosts from chat commands.** - -Stars -Last commit -License -Python 3.10+ -Flask-SocketIO -Docker Compose - -
+> Telegram-fronted NOC console — monitors Linux and Windows hosts with cross-platform agents, discovers SNMP devices, and serves a live dashboard, for small NOC and homelab operators who want alerts and host control from chat. -![TeleOps dashboard](docs/assets/screenshot.png) +[![License](https://img.shields.io/github/license/OneByJorah/TeleOps?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/TeleOps) +[![Top Language](https://img.shields.io/github/languages/top/OneByJorah/TeleOps?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/TeleOps) +[![Stars](https://img.shields.io/github/stars/OneByJorah/TeleOps?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/TeleOps/stargazers) +[![Last Commit](https://img.shields.io/github/last-commit/OneByJorah/TeleOps?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/TeleOps/commits) +[![CI](https://img.shields.io/github/actions/workflow/status/OneByJorah/TeleOps/ci.yml?style=for-the-badge&color=FFB300&labelColor=0a0a09)](https://github.com/OneByJorah/TeleOps/actions) ## What This Is -TeleOps turns Telegram into a network operations console. A bot fronts a set of cross-platform agents, an SNMP discovery engine, and a live web dashboard, so you can check host health, run signed commands, and get threshold alerts without opening a terminal or a monitoring portal. - -It is built for small NOC and homelab operators who want lightweight, self-hosted infrastructure monitoring that reaches them where they already are — chat. +Full monitoring stacks are heavy for a handful of servers, and their dashboards are another tab you forget to open. TeleOps moves the control plane to Telegram: a bot fronts a set of cross-platform agents, an SNMP discovery engine, and a live web dashboard, so you can check host health, run signed commands, and receive threshold alerts where you already are — chat. It is built for small NOCs and homelab operators running a mixed Linux/Windows fleet. ## Quick Start ```bash -git clone https://github.com/OneByJorah/TeleOps.git -cd TeleOps - -cp .env.example .env # set TELEGRAM_BOT_TOKEN and ADMIN_CHAT_IDS +git clone https://github.com/OneByJorah/TeleOps.git && cd TeleOps +cp .env.example .env # set TELEGRAM_BOT_TOKEN and ADMIN_CHAT_IDS docker compose up -d ``` -Open **http://localhost:5000** for the dashboard. The agent server listens on **http://localhost:8080**. - -> [!WARNING] -> The `bot` service needs a valid Telegram token to stay up. Check `docker logs netbot` after editing `.env`. On first run the entrypoint seeds `config/config.yaml` from `.env`. +Open **http://localhost:5000** for the dashboard; the agent server listens on **:8080**. Host agents install from `agents/linux/install.sh` or `agents/windows/install.ps1`. ## Features -- **Telegram control plane** — admin-gated commands for status, agents, SNMP, and per-host actions. -- **Cross-platform agents** — a stdlib Linux agent and a PowerShell 5.1 Windows agent with HMAC-SHA256 signed command dispatch. -- **SNMP discovery** — automated device discovery and polling over SNMP v1/v2c/v3. -- **Live dashboard** — Flask + SocketIO API with REST polling fallback. -- **Alert management** — CPU/memory/disk thresholds, cooldown, and agent offline detection. -- **Agent server** — self-registration, heartbeat, and installer downloads over HTTP. -- **Windows host management** — AD, DNS, and DHCP actions from the Windows agent. -- **Redis-backed state** — durable job/state storage with append-only persistence. +- Admin-gated Telegram commands for status, agents, SNMP devices, and per-host actions +- Stdlib-only Linux agent and PowerShell 5.1 Windows agent with self-registration and 25 s heartbeats +- HMAC-SHA256 signed command dispatch (`stats`, `services`, `firewall`, `docker_ps`; AD/DNS/DHCP actions on Windows) +- SNMP v1/v2c/v3 device discovery and polling, plus subnet host scanning +- Flask + SocketIO live dashboard with REST polling fallback +- CPU/memory/disk alert thresholds with cooldown and agent-offline detection +- Redis-backed durable job/state storage with append-only persistence ## Architecture +```mermaid +%%{init: {'theme':'base','themeVariables':{'primaryColor':'#0a0a09','primaryTextColor':'#FFB300','lineColor':'#FFB300'}}}%% +flowchart LR + TG["Telegram admin"] --> BOT["NetBot (python-telegram-bot)"] + BOT -->|HMAC-signed commands| AG["Agents: Linux / Windows"] + BOT --> SCAN["Network + SNMP scanners"] + AG --> REG["Agent server :8080"] + BOT --> DASH["Flask dashboard :5000"] + BOT --> REDIS["Redis state"] + BOT -->|alerts| TG ``` -Telegram Admin ──commands──▶ NetBot ──HMAC-signed commands──▶ Agents (Linux/Windows) - │ - NetworkScanner ──────────▶│ probes http://:7845/info - SNMPScanner ──────────────▶│ polls v2c communities - ▼ - Agent Server (:8080) · Dashboard (:5000) · Alerts → Telegram -``` - -Agents register themselves (`POST /agent/register`) or are discovered by subnet scan, report heartbeats every 25 s, and execute signed commands (`stats`, `services`, `firewall`, `docker_ps`, AD/DNS/DHCP on Windows, `cmd` on Linux). - -## Configuration - -Primary configuration lives in **`config/config.yaml`** (copy from `config/config.yaml.example`): discovery networks, SNMP communities, alert thresholds, and heartbeat intervals all live there. Environment variables are read by `bot/main.py` and seeded into YAML by the entrypoint. - -| Variable | Default | Description | -|----------|---------|-------------| -| `TELEGRAM_BOT_TOKEN` | *(empty)* | Bot token from BotFather (overrides YAML) | -| `ADMIN_CHAT_IDS` | *(empty)* | Comma-separated Telegram user IDs with admin access | -| `SECRET_KEY` | *(empty)* | HMAC secret shared with agents (overrides YAML) | -| `REDIS_HOST` / `REDIS_PORT` | `redis` / `6379` | Redis connection | -| `REDIS_PASSWORD` | *(generated)* | Redis auth password | -| `DASHBOARD_PORT` | `5000` | Web dashboard port | -| `AGENT_PORT` | `8080` | Agent server port | -| `SNMP_COMMUNITY` | `public` | Default SNMP community | -| `SCAN_INTERVAL_MINUTES` | `60` | Network discovery interval | - -## Telegram Commands -| Command | Description | -|---------|-------------| -| `/start` | Initialize the bot (admin menu) | -| `/status` | Agent & SNMP device status overview | -| `/agents` | List registered agents | -| `/dashboard` | Get dashboard URL | -| `/win [action]` | Windows agent menu or action | -| `/lx [action]` | Linux agent menu or action | -| `/snmp list\|scan\|` | SNMP devices, scan, or poll one device | -| `/alert` | Alert configuration info | +## Stack -## API & Endpoints - -| Endpoint | Method | Description | -|----------|--------|-------------| -| `/` | GET | Dashboard UI | -| `/api/agents` | GET | Registered agents | -| `/api/snmp` | GET | Discovered SNMP devices | -| `/api/summary` | GET | Aggregated status summary | -| `/agent/register` | POST | Agent self-registration | -| `/agent/download/linux` | GET | Linux agent installer script | -| `/agent/download/windows` | GET | Windows agent installer script | -| `/install/linux` | GET | Linux install helper | -| `/install/windows` | GET | Windows install helper | -| `/health` | GET | Agent server health | - -## Use Cases - -1. **Homelab operators** — monitor a mixed Linux/Windows fleet from Telegram. -2. **Small NOCs** — combine agent metrics and SNMP devices in one dashboard. -3. **Remote admins** — run signed host commands without a VPN into a jump box. - -## Tech Stack - -Python 3.10+, python-telegram-bot, aiohttp, Flask + Flask-SocketIO, pysnmp, Redis, SQLAlchemy, PowerShell (Windows agent), Docker Compose. - -## Screenshots - -| Dashboard | Overview | -|---|---| -| ![Dashboard](docs/screenshots/dashboard-full.png) | ![Overview](docs/screenshots/dashboard-overview.png) | - -More captures live in [`docs/screenshots/`](docs/screenshots/). - -## Security - -Agent `/command` endpoints require HMAC-SHA256 signatures over `timestamp:body` with a ±5-minute freshness window. The dashboard and agent server expose operational data without authentication — do not expose ports 5000/8080 to untrusted networks. See [SECURITY.md](SECURITY.md). +Python 3.10+, python-telegram-bot, aiohttp, Flask + Flask-SocketIO, pysnmp, Redis, SQLAlchemy, APScheduler, PowerShell (Windows agent), Docker Compose. ## Contributing -Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). [Open an issue](https://github.com/OneByJorah/TeleOps/issues) to report a bug or request a feature. +Contributions are welcome — read [CONTRIBUTING.md](CONTRIBUTING.md), then [open an issue](https://github.com/OneByJorah/TeleOps/issues). ## License -MIT — see [LICENSE](LICENSE). - -## Connect - -- [jorahone.com](https://jorahone.com) -- [GitHub Org](https://github.com/OneByJorah) -- [info@jorahone.com](mailto:info@jorahone.com) +MIT — see LICENSE. diff --git a/config/config.yaml b/config/config.yaml new file mode 100644 index 0000000..16a9d69 --- /dev/null +++ b/config/config.yaml @@ -0,0 +1,59 @@ +agents: + collect_interval: 60 + heartbeat_interval: 30 + offline_threshold: 90 +alerts: + cooldown: 300 + enabled: true + thresholds: + cpu_percent: 90 + disk_percent: 90 + memory_percent: 85 + service_down: true +bot: + admin_ids: + - 123456789 + - 987654321 + polling: true + token: YOUR_TELEGRAM_BOT_TOKEN + webhook_url: '' +dashboard: + enabled: true + host: 0.0.0.0 + port: 5000 + title: NetBot Dashboard +discovery: + enabled: true + networks: + - 192.168.1.0/24 + - 10.0.0.0/24 + ping_timeout: 1 + ping_workers: 50 + scan_interval: 300 +logging: + backup_count: 5 + file: logs/netbot.log + level: INFO + max_size_mb: 50 +redis: + db: 0 + host: redis + password: '' + port: 6379 +server: + host: 0.0.0.0 + port: 8080 + secret_key: 95afcf8822b66a164e36b404fa894d5a9030816188f2ece1ba94d38ff1ffe40d +snmp: + communities: + - public + - private + enabled: true + poll_interval: 60 + port: 161 + retries: 2 + timeout: 5 + version: 2c +windows: + domain: yourdomain.local + ps_timeout: 30