hteppl/remnawave-traffic-guard repository overview

⁠remnawave-traffic-guard

English | Русский⁠

Monitor users traffic from Remnawave⁠, detect anomalies, and send Telegram alerts.

⁠Features

• Interval Spike Detection — Alerts when a user exceeds a traffic threshold within a single check interval
• Total Limit Detection — Alerts when a user exceeds a cumulative traffic threshold over a rolling time window
• Hourly Stats Reports — Periodic Telegram summaries with active users, total traffic, and top consumer
• Per-Node Breakdown — Alerts include top nodes by traffic for each flagged user
• Telegram Notifications — HTML-formatted alerts to a channel/topic or admin DMs
• 100k+ Users Scale — Redis-backed O(1) snapshot lookups with pipelined bulk writes
• Multi-Language — Supports English and Russian notification templates
• Docker Ready — Two-container deployment (app + Redis) with Docker Compose

⁠Prerequisites

Before you begin, ensure you have the following:

• Remnawave Panel with users configured
• Remnawave API Token — Generate from your Remnawave panel settings
• Telegram Bot Token — Create with @BotFather⁠
• Docker and Docker Compose installed

⁠Configuration

Copy .env.example⁠ to .env and fill in your values:

# Remnawave panel URL and API key
REMNAWAVE_API_URL=https://panel.example.com
REMNAWAVE_API_KEY=remnawave_api_key

# Telegram bot token from @BotFather
TELEGRAM_BOT_TOKEN=your_bot_token_here
# Chat ID (get from @username_to_id_bot)
TELEGRAM_CHAT_ID=123456789
# Forum topic ID (leave empty for regular chats)
TELEGRAM_TOPIC_ID=

INTERVAL_CHECK_ENABLED=true
# How often to check traffic (minutes)
CHECK_INTERVAL_MINUTES=10
# Alert if user exceeds this in one interval (GB)
INTERVAL_THRESHOLD_GB=20

TOTAL_CHECK_ENABLED=true
# Rolling window for total check (hours)
TOTAL_CHECK_HOURS=24
# Alert if user exceeds this over the window (GB)
TOTAL_THRESHOLD_GB=100

HOURLY_STATS_ENABLED=true

# Supported languages: en, ru
LANGUAGE=en
# Timezone (e.g. UTC, Europe/Moscow, America/New_York)
TIMEZONE=Europe/Moscow
# Time format: %d-day, %m-month, %Y-year, %H-hour, %M-min, %S-sec
TIME_FORMAT="%d.%m.%Y %H:%M:%S"
# Ignore traffic diffs below this value (GB)
MIN_TRAFFIC_GB=0.5
# Max nodes shown per alert
TOP_NODES_LIMIT=5

# Users per API page (max 1000)
API_PAGE_SIZE=1000

# Redis URL (data is persisted via Redis AOF)
REDIS_URL=redis://redis:6379/0

⁠Configuration Reference

⁠Installation

⁠Docker (recommended)

1. Create the docker-compose.yml:

services:
  remnawave-traffic-guard:
    image: hteppl/remnawave-traffic-guard:latest
    container_name: remnawave-traffic-guard
    restart: unless-stopped
    env_file:
      - .env
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:8-alpine
    restart: unless-stopped
    command: redis-server --appendonly yes
    volumes:
      - traffic-guard-redis-data:/data
    healthcheck:
      test: [ 'CMD', 'redis-cli', 'ping' ]
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  traffic-guard-redis-data:

1. Create and configure your environment file:

cp .env.example .env
nano .env  # or use your preferred editor

1. Start the containers:

docker compose up -d && docker compose logs -f

⁠Manual Installation

1. Clone the repository:

git clone https://github.com/hteppl/remnawave-traffic-guard.git
cd remnawave-traffic-guard

1. Create a virtual environment (recommended):

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

1. Install dependencies:

pip install -r requirements.txt

1. Create and configure your environment file:

cp .env.example .env

1. Make sure Redis is running and REDIS_URL points to it, then run:

python -m src

⁠How It Works

1. Startup — Connects to Redis, sends a startup notification to Telegram with current thresholds

2. Periodic Check — Every CHECK_INTERVAL_MINUTES minutes, fetches all users from the Remnawave API and compares current traffic against previous snapshots stored in Redis

3. Spike Detection — If a user's traffic increase within a single interval exceeds INTERVAL_THRESHOLD_GB, sends an alert with per-node traffic breakdown

4. Total Limit Detection — If a user's cumulative traffic over TOTAL_CHECK_HOURS hours exceeds TOTAL_THRESHOLD_GB, sends an alert

5. Snapshot Update — After each check, all user snapshots are written to Redis for the next cycle

6. Hourly Reports — On each hour boundary, sends a summary with total/active users, traffic consumed, top user, and alert count

⁠Telegram Notifications

⁠Setup

1. Create a bot with @BotFather⁠ and get the token
2. Get your chat ID from @username_to_id_bot⁠
3. Add the bot to your chat/group
4. Set TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in .env

⁠Notification Types

⁠Logs

Monitor logs to diagnose issues:

docker compose logs -f

⁠License

This project is licensed under the GNU General Public License v3.0⁠.