From 9800de9350dff604c5c8f06ff7abdacaed6fba84 Mon Sep 17 00:00:00 2001 From: stephenminakian Date: Sun, 6 Jul 2025 22:04:59 -0600 Subject: [PATCH] Add Server readme --- Server/README.md | 169 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 Server/README.md diff --git a/Server/README.md b/Server/README.md new file mode 100644 index 0000000..544ebd0 --- /dev/null +++ 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 \ No newline at end of file