StorageSecurity/Server/README.md

Webhook Server

Secure Flask-based webhook service for receiving and processing security alerts from Particle IoT devices, with enterprise-grade features including authentication, rate limiting, and comprehensive logging.

🎯 Overview

This webhook service provides:

• Dual Authentication: HMAC signatures for generic webhooks, Bearer tokens for Particle webhooks
• Security Hardening: Rate limiting, security headers, input validation
• Enterprise Integration: Docker containerization, Traefik reverse proxy support
• Monitoring Ready: Comprehensive logging, health checks, metrics endpoints
• Notification Support: Email/SMS alerts with rich formatting

🏗️ Architecture

Internet ──▶ Traefik ──▶ Webhook Service ──▶ Notifications
             (SSL)      (Docker)           (Email/SMS)
                │
                ├─ Rate Limiting
                ├─ Security Headers  
                ├─ Authentication
                └─ Health Checks

Key Components

• Flask Application: Lightweight webhook processor
• Gunicorn WSGI Server: Production-grade application server
• Docker Container: Isolated, reproducible deployment
• Traefik Integration: Automatic SSL, load balancing, monitoring
• Health Monitoring: Built-in health checks and status endpoints

🔐 Security Features

Authentication Methods

1. Particle Webhooks: Bearer token authentication

   Authorization: Bearer your-particle-secret
   User-Agent: ParticleBot/1.0
   

2. Generic Webhooks: HMAC-SHA256 signature verification

   X-Hub-Signature-256: sha256=computed-hmac-signature
   

Security Hardening

• Rate Limiting: 10 requests/minute average, 20 burst
• Security Headers: XSS protection, content type sniffing prevention
• Input Validation: JSON schema validation, required field checking
• Non-root Container: Runs as unprivileged user
• Minimal Attack Surface: Only required packages installed

Network Security

• TLS Termination: Handled by Traefik reverse proxy
• Internal Networks: Container-to-container communication only
• No Direct Exposure: No ports directly exposed to internet

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• Traefik reverse proxy (with external network)
• Gmail account with app password
• Domain name pointing to your server

1. Clone and Setup

# Clone the repository
git clone https://github.com/yourusername/security-device-system.git
cd security-device-system/webhook-server

# Copy environment template
cp .env.example .env

2. Configure Environment

# Edit environment variables
nano .env

# Required variables:
FLASK_SECRET_KEY=your-flask-secret-key
WEBHOOK_SECRET=your-hmac-webhook-secret  
PARTICLE_WEBHOOK_SECRET=your-particle-bearer-secret
SMTP_EMAIL=your-email@gmail.com
SMTP_PASSWORD=your-gmail-app-password
RECIPIENT_EMAIL=your-phone@carrier.com

3. Deploy Service

# Build and start the service
docker compose up -d --build

# Check service status
docker compose ps

# Monitor logs
docker compose logs -f webhook-service

4. Verify Deployment

# Test health endpoint
curl https://webhook.yourdomain.com/health

# Should return:
# {"status": "healthy", "timestamp": "2024-01-07T..."}

📝 Configuration

Environment Variables

Variable	Description	Example
FLASK_SECRET_KEY	Flask session encryption key	openssl rand -hex 32
WEBHOOK_SECRET	HMAC secret for generic webhooks	openssl rand -hex 32
PARTICLE_WEBHOOK_SECRET	Bearer token for Particle webhooks	openssl rand -hex 32
SMTP_EMAIL	Gmail address for notifications	alerts@yourdomain.com
SMTP_PASSWORD	Gmail app password (not regular password)	abcd efgh ijkl mnop
RECIPIENT_EMAIL	SMS gateway email for notifications	5551234567@vtext.com

Generating Secrets

# Generate secure random secrets
FLASK_SECRET=$(openssl rand -hex 32)
WEBHOOK_SECRET=$(openssl rand -hex 32)
PARTICLE_SECRET=$(openssl rand -hex 32)

echo "FLASK_SECRET_KEY=$FLASK_SECRET"
echo "WEBHOOK_SECRET=$WEBHOOK_SECRET"
echo "PARTICLE_WEBHOOK_SECRET=$PARTICLE_SECRET"

Gmail Setup

1. Enable 2-Factor Authentication on your Google account
2. Go to Google App Passwords
3. Generate app password for "Webhook Service"
4. Use the 16-character password (not your regular password)

SMS Gateway Setup

Common SMS gateway formats:

• Verizon: number@vtext.com
• AT&T: number@txt.att.net
• T-Mobile: number@tmomail.net
• Sprint: number@messaging.sprintpcs.com

🌐 Traefik Integration

Docker Compose Labels

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.webhook.rule=Host(`webhook.yourdomain.com`)"
  - "traefik.http.routers.webhook.entrypoints=websecure"
  - "traefik.http.routers.webhook.tls.certresolver=letsencrypt"
  - "traefik.http.services.webhook.loadbalancer.server.port=5000"
  
  # Security middleware
  - "traefik.http.routers.webhook.middlewares=webhook-headers,webhook-ratelimit"
  
  # Rate limiting
  - "traefik.http.middlewares.webhook-ratelimit.ratelimit.average=10"
  - "traefik.http.middlewares.webhook-ratelimit.ratelimit.burst=20"

External Network