Add Server readme

2025-07-06 22:04:59 -06:00
parent baa45e9d47
commit 9800de9350
1 changed files with 169 additions and 0 deletions
--- a/Server/README.md
+++ b/Server/README.md
@ -0,0 +1,169 @@
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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](https://myaccount.google.com/apppasswords)
+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
+```yaml
+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