claudetools/projects/msp-tools/guru-connect/PHASE1_SECURITY_INFRASTRUCTURE.md

Phase 1: Security & Infrastructure

Duration: 4 weeks Team: 1 Backend Developer + 1 DevOps Engineer Goal: Fix critical vulnerabilities, establish production-ready infrastructure

---

Week 1: Critical Security Fixes

Day 1-2: JWT Secret & Rate Limiting

SEC-1: JWT Secret Hardcoded (CRITICAL)

• Remove hardcoded JWT secret from source code
• Add JWT_SECRET environment variable to .env
• Update server/src/auth/ to read from env
• Generate strong random secret (64+ chars)
• Document secret rotation procedure
• Test authentication with new secret
• Verify old tokens rejected after rotation

SEC-2: Rate Limiting (CRITICAL)

• Install tower-governor or similar rate limiting middleware
• Add rate limiting to /api/auth/login (5 attempts/minute)
• Add rate limiting to /api/auth/register (2 attempts/minute)
• Add rate limiting to support code validation (10 attempts/minute)
• Add IP-based tracking
• Test rate limiting with automated requests
• Add rate limit headers (X-RateLimit-Remaining, etc.)

Day 3: SQL Injection Prevention

SEC-3: SQL Injection in Machine Filters (CRITICAL)

• Audit all raw SQL queries in server/src/db/
• Replace string concatenation with sqlx parameterized queries
• Focus on machine_filters.rs (high risk)
• Review user_queries.rs for injection points
• Add input validation for filter parameters
• Test with SQL injection payloads ('; DROP TABLE--, etc.)
• Document safe query patterns for team

Day 4-5: Agent & Session Security

SEC-4: Agent Connection Validation (CRITICAL)

• Implement support code validation in relay handler
• Implement API key validation for persistent agents
• Reject connections without valid credentials
• Add connection attempt logging
• Test with invalid codes/keys
• Add IP whitelisting option for agents
• Document agent authentication flow

SEC-5: Session Takeover Prevention (CRITICAL)

• Add session ownership validation
• Verify JWT user_id matches session creator
• Prevent cross-user session access
• Add session token binding (tie to initial connection)
• Test with stolen session IDs
• Add session hijacking detection (IP change alerts)
• Implement session timeout (4-hour max)

---

Week 2: High-Priority Security

Day 1: Logging & HTTPS

SEC-6: Password Logging (HIGH)

• Audit all logging statements for sensitive data
• Remove password/token logging from auth.rs
• Add [REDACTED] filter for sensitive fields
• Update tracing configuration
• Test logs don't contain credentials
• Document logging security policy

SEC-10: HTTPS Enforcement (HIGH)

• Add HTTPS redirect middleware
• Configure HSTS headers (max-age=31536000)
• Update NPM to enforce HTTPS
• Test HTTP requests redirect to HTTPS
• Add secure cookie flags (Secure, HttpOnly)
• Update documentation with HTTPS URLs

Day 2-3: Input Sanitization

SEC-7: XSS Prevention (HIGH)

• Install validator crate for input sanitization
• Sanitize all user inputs in API endpoints
• Escape HTML in machine names, notes, tags
• Add Content-Security-Policy headers
• Test with XSS payloads (<script>, onerror=, etc.)
• Review dashboard.html for unsafe innerHTML usage
• Add CSP reporting endpoint

Day 4: Password Hashing Upgrade

SEC-9: Argon2id Migration (HIGH)

• Install argon2 crate
• Replace PBKDF2 with Argon2id in auth service
• Set parameters (memory=65536, iterations=3, parallelism=4)
• Add password hash migration for existing users
• Test login with old and new hashes
• Force password reset for all users (optional)
• Document hashing algorithm choice

Day 5: Session & CORS Security

SEC-13: Session Expiration (HIGH)

• Add exp claim to JWT tokens (4-hour expiry)
• Implement refresh token mechanism
• Add token renewal endpoint /api/auth/refresh
• Update dashboard to refresh tokens automatically
• Test token expiration and renewal
• Add session cleanup job (delete expired sessions)

SEC-11: CORS Configuration (HIGH)

• Review CORS middleware settings
• Restrict allowed origins to known domains
• Remove wildcard (*) CORS if present
• Set Access-Control-Allow-Credentials properly
• Test cross-origin requests blocked
• Document CORS policy

SEC-12: CSP Headers (HIGH)

• Add Content-Security-Policy header
• Set policy: default-src 'self'; script-src 'self'
• Allow wss: for WebSocket connections
• Test dashboard loads without CSP violations
• Add CSP reporting to monitor violations

SEC-8: TLS Certificate Validation (HIGH)

• Add TLS certificate verification in agent WebSocket client
• Use rustls or native-tls with validation enabled
• Test agent rejects invalid certificates
• Add certificate pinning option (optional)
• Document TLS requirements

---

Week 3: Infrastructure Setup

Day 1-2: Systemd Service

INF-1: Systemd Service Configuration

• Create /etc/systemd/system/guruconnect-server.service
• Set User=guru, WorkingDirectory=/home/guru/guru-connect
• Configure ExecStart with full binary path
• Add Restart=on-failure, RestartSec=5s
• Set environment file EnvironmentFile=/home/guru/.env
• Enable service: systemctl enable guruconnect-server
• Test start/stop/restart
• Test auto-restart on crash (kill -9 process)
• Configure log rotation with journald
• Document service management commands

Day 3-4: Prometheus Monitoring

INF-2: Prometheus Metrics

• Install prometheus crate and metrics_exporter_prometheus
• Add /metrics endpoint to server
• Expose metrics: active_sessions, connected_agents, http_requests
• Add custom metrics: frame_latency, input_latency
• Install Prometheus on server (apt install prometheus)
• Configure Prometheus scrape config
• Test metrics endpoint returns data
• Create Prometheus systemd service
• Configure retention (30 days)

INF-3: Grafana Dashboards

• Install Grafana (apt install grafana)
• Configure Prometheus data source
• Create dashboard: GuruConnect Overview
• Add panels: Active Sessions, Connected Agents, CPU/Memory
• Add panels: WebSocket Connections, HTTP Request Rate
• Add panel: Session Duration Histogram
• Set up alerts: High error rate, No agents connected
• Export dashboard JSON for version control
• Create Grafana systemd service
• Configure Grafana HTTPS via NPM

Day 5: Alerting

INF-4: Alertmanager Setup

• Install alertmanager
• Configure alert rules in Prometheus
• Set up email notifications (SMTP config)
• Add alerts: Server Down, High Memory, Database Errors
• Test alert firing and notifications
• Document alert response procedures

---

Week 4: Backups & CI/CD

Day 1: PostgreSQL Backups

INF-5: Automated Backups

• Create backup script /home/guru/scripts/backup-postgres.sh
• Use pg_dump with compression (gzip)
• Store backups in /home/guru/backups/guruconnect/
• Add timestamp to backup filenames
• Configure cron job (daily at 2 AM)
• Implement retention policy (keep 30 days)
• Test backup creation
• Test backup restoration to test database
• Add backup monitoring (alert if backup fails)
• Document restore procedure

Day 2-3: CI/CD Pipeline

INF-6: Gitea CI/CD

• Create .gitea/workflows/ci.yml
• Add job: cargo test (run tests on every commit)
• Add job: cargo clippy (lint checks)
• Add job: cargo audit (security vulnerabilities)
• Configure Gitea runner
• Test pipeline on commit
• Add job: cargo build --release (build artifacts)
• Store build artifacts (for deployment)

INF-7: Deployment Automation

• Create deployment script deploy.sh
• Add steps: Pull latest, build, stop service, replace binary, start service
• Add pre-deployment backup
• Add smoke tests after deployment
• Test deployment script on staging
• Configure deploy job in CI/CD (manual trigger)
• Document deployment process

Day 4: Health Checks

INF-8: Health Monitoring

• Add /health endpoint to server
• Check database connection in health check
• Check Redis connection (if applicable)
• Return 200 OK if healthy, 503 if unhealthy
• Configure NPM health check monitoring
• Add health check to Prometheus (blackbox exporter)
• Test health endpoint
• Add liveness and readiness probes (Kubernetes-style)

Day 5: Documentation & Testing

DOC-1: Infrastructure Documentation

• Document systemd service configuration
• Document monitoring setup (Prometheus, Grafana)
• Document backup and restore procedures
• Document deployment process
• Create runbook for common issues
• Document alerting and on-call procedures

TEST-1: End-to-End Security Testing

• Run OWASP ZAP scan against server
• Test all fixed vulnerabilities
• Verify rate limiting works
• Verify HTTPS enforcement
• Test authentication with expired tokens
• Penetration test: SQL injection, XSS, CSRF
• Document remaining security issues (medium/low)

---

Phase 1 Completion Criteria

Security Checklist

• All 5 critical vulnerabilities fixed (SEC-1 to SEC-5)
• All 8 high-priority vulnerabilities fixed (SEC-6 to SEC-13)
• OWASP ZAP scan shows no critical/high issues
• Penetration testing passed

Infrastructure Checklist

• Systemd service operational with auto-restart
• Prometheus metrics exposed and scraped
• Grafana dashboard configured with alerts
• Automated PostgreSQL backups running daily
• Backup restoration tested successfully
• CI/CD pipeline running tests on every commit
• Deployment automation tested

Documentation Checklist

• All security fixes documented
• Infrastructure setup documented
• Deployment procedures documented
• Runbook created for common issues
• Team trained on new procedures

Performance Checklist

• Health endpoint responds in <100ms
• Prometheus scrape completes in <5s
• Backup completes in <10 minutes
• Service restart completes in <30s

---

Dependencies & Blockers

External Dependencies:

• NPM access for HTTPS configuration
• SMTP server for alerting (if not configured)
• Gitea runner setup (if not available)

Potential Blockers:

• Database schema changes may be needed for session security
• Agent code changes needed for TLS validation
• Dashboard changes needed for token refresh

Risk Mitigation:

• Test all changes on staging environment first
• Keep rollback procedure ready
• Communicate downtime windows to users (if any)

---

Phase Owner: Backend Developer + DevOps Engineer Start Date: TBD Target Completion: 4 weeks from start Next Phase: Phase 2 - Core Functionality