ByeSpy - Fail2Ban Visual Dashboard

A modern, agent-based visual dashboard system for monitoring and managing Fail2Ban logs across distributed network instances.

Features

• 🌐 Multi-Instance Support: Monitor unlimited Fail2Ban instances
• 🤖 Agent-Based Collection: Lightweight agents forward logs in real-time via REST API
• 🐳 Docker Support: Run agents as systemd services or Docker containers
• 💾 Time-Series Storage: InfluxDB for metrics and PostgreSQL for metadata
• 📊 Visual Analytics: Real-time dashboards with ban/unban tracking per host and jail
• 🔔 Alert System: SMTP, Discord, Slack, Telegram notifications with rule-based triggers
• 🔒 Authentication: Local authentication with JWT tokens and LDAP support
• 🔐 Secure: Token-based API authentication for agents
• 📱 Modern UI: React-based dashboard with Tailwind CSS

Architecture

┌─────────────────────────────────────────────────────────┐
│                    ByeSpy Dashboard                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│  │ Frontend │  │ Backend  │  │  Redis   │             │
│  │  React   │◄─┤ FastAPI  ├─►│  Cache   │             │
│  └──────────┘  └─────┬────┘  └──────────┘             │
│                      │                                  │
│                      ├──► PostgreSQL (metadata)         │
│                      └──► InfluxDB (time-series)        │
└─────────────────────┬───────────────────────────────────┘
                      │ REST API (Bearer Token)
                      │
        ┌─────────────┼─────────────┬──────────────┐
        │             │             │              │
   ┌────▼────┐   ┌───▼────┐   ┌───▼────┐   ┌─────▼─────┐
   │ Agent   │   │ Agent  │   │ Docker │   │  Docker   │
   │ systemd │   │systemd │   │ Agent  │   │  Agent    │
   └─────────┘   └────────┘   └────────┘   └───────────┘
   Host 1        Host 2       Host 3        Host 4

Deployment Methods

Agent (systemd)

• Standalone Python script installed as a systemd service
• Direct log file monitoring with inode tracking
• Best for: Traditional Linux servers

Docker

• Same agent script running in a container
• Configuration via environment variables
• Log directory mounted as read-only volume
• Best for: Containerized environments, Docker hosts

Quick Start

1. Deploy Dashboard

# Clone repository
git clone <repo>
cd byespy

# Configure environment
cp .env.example .env
# Edit .env with your database and InfluxDB settings

# Start dashboard services
docker compose up -d

# Access dashboard at http://localhost:3000
# Default credentials: admin / admin (change immediately)

2. Add a Host

1. Log into the dashboard
2. Navigate to Hosts → Add Host
3. Enter hostname and select connection type (Agent or Docker)
4. Copy the installation command provided

3. Install Agent on Target Host

Option A: systemd Service (traditional Linux)

# Run the installation command from the dashboard
# It will:
# 1. Download byespy-agent.py to /usr/local/bin/
# 2. Create /etc/byespy/agent.conf with your host's token
# 3. Install and enable systemd service

# Check agent status
sudo systemctl status byespy-agent

Option B: Docker Container

# Run the Docker command from the dashboard
# Example:
docker run -d --name byespy-agent \
  -v /var/log/fail2ban.log:/var/log/fail2ban.log:ro \
  -e BYESPY_SERVER_URL=https://byespy.example.com \
  -e BYESPY_API_TOKEN=your-host-token \
  -e BYESPY_HOST_ID=host-uuid \
  -e BYESPY_LOG_PATH=/var/log/fail2ban.log \
  --restart unless-stopped \
  sluberskihomelab/byespy-agent:latest

Configuration

Dashboard Environment Variables (.env)

# Database
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=byespy
POSTGRES_USER=byespy
POSTGRES_PASSWORD=changeme

# InfluxDB
INFLUXDB_URL=http://influxdb:8086
INFLUXDB_TOKEN=your-token
INFLUXDB_ORG=byespy
INFLUXDB_BUCKET=fail2ban

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# Authentication
JWT_SECRET_KEY=generate-secure-key

Agent Configuration

systemd mode: /etc/byespy/agent.conf

{
  "server_url": "https://byespy.example.com",
  "api_token": "host-specific-token",
  "host_id": "uuid-from-dashboard",
  "log_path": "/var/log/fail2ban.log",
  "check_interval": 60
}

Docker mode: Environment variables (BYESPY_SERVER_URL, BYESPY_API_TOKEN, BYESPY_HOST_ID, BYESPY_LOG_PATH)

Documentation

• Installation Guide - Detailed setup instructions
• Configuration Guide - Advanced configuration options
• API Documentation - REST API reference

License

MIT