M.I.M.I.R - Multi-agent Intelligent Memory & Insight Repository

# Mimir Security Quick Start **Time Required**: 4 hours **Cost**: $0 **Result**: Production-ready for internal/trusted networks --- ## ⚠️ Current Security Status **Mimir is currently**: - ✅ Safe for internal/trusted networks - ⚠️ **NOT SAFE** for public internet without hardening - 🔴 **NOT COMPLIANT** with HIPAA/FISMA/GDPR without additional controls **See**: [Full Enterprise Readiness Audit](./ENTERPRISE_READINESS_AUDIT.md) for comprehensive analysis --- ## 🚀 4-Hour Security Hardening ### Step 1: Add HTTPS with Nginx (2 hours) **1.1 Create Nginx configuration** ```bash mkdir -p nginx/ssl ``` **⚠️ Important**: The configuration below uses `${MIMIR_API_KEY}` for environment variable substitution. Standard Nginx doesn't support this natively. Use `envsubst` to preprocess the config or pass the variable via Docker environment (shown in docker-compose.yml below). Create `nginx/nginx.conf`: ```nginx events { worker_connections 1024; } http { # Rate limiting limit_req_zone $binary_remote_addr zone=api:10m rate=100r/m; server { listen 443 ssl; server_name mimir.yourcompany.com; # TLS Configuration ssl_certificate /etc/nginx/ssl/cert.pem; ssl_certificate_key /etc/nginx/ssl/key.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; # API Key Authentication set $api_key_valid 0; if ($http_x_api_key = "${MIMIR_API_KEY}") { set $api_key_valid 1; } if ($api_key_valid = 0) { return 401 '{"error":"Unauthorized - Invalid or missing API key"}'; } # Rate Limiting limit_req zone=api burst=20 nodelay; # Proxy to Mimir location / { proxy_pass http://mimir_server:9042; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # Timeouts proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; } } # Redirect HTTP to HTTPS server { listen 80; server_name mimir.yourcompany.com; return 301 https://$server_name$request_uri; } } ``` **1.2 Generate self-signed certificate** ```bash openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout nginx/ssl/key.pem \ -out nginx/ssl/cert.pem \ -subj "/C=US/ST=State/L=City/O=Company/CN=mimir.yourcompany.com" ``` **1.3 Update docker-compose.yml** Create `docker-compose.security.yml`: ```yaml version: '3.8' services: # Nginx Reverse Proxy nginx: image: nginx:alpine container_name: mimir_nginx restart: unless-stopped ports: - "443:443" - "80:80" volumes: - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro - ./nginx/ssl:/etc/nginx/ssl:ro environment: - MIMIR_API_KEY=${MIMIR_API_KEY} depends_on: - mimir_server networks: - mimir_network # Mimir Server (no longer exposed directly) mimir_server: # Remove ports section - only accessible via Nginx expose: - "9042" # ... rest of config from main docker-compose.yml # Neo4j (internal only) neo4j: # Remove HTTP port 7474 - only Bolt for internal use ports: - "7687:7687" # Bolt only # ... rest of config networks: mimir_network: driver: bridge ``` **1.4 Generate API key** ```bash # Generate secure API key export MIMIR_API_KEY=$(openssl rand -base64 32) echo "MIMIR_API_KEY=${MIMIR_API_KEY}" >> .env echo "Your API key: ${MIMIR_API_KEY}" ``` **1.5 Start secured services** ```bash docker-compose -f docker-compose.yml -f docker-compose.security.yml up -d ``` --- ### Step 2: Enable Audit Logging (1 hour) **2.1 Add audit middleware** Create `src/middleware/audit-logger.ts`: ```typescript import { Request, Response, NextFunction } from 'express'; export interface AuditLog { timestamp: string; ip: string; method: string; path: string; apiKey: string; userAgent?: string; statusCode?: number; duration?: number; } export function auditLogger(req: Request, res: Response, next: NextFunction) { const startTime = Date.now(); // Capture request details const log: AuditLog = { timestamp: new Date().toISOString(), ip: req.headers['x-real-ip'] as string || req.ip || 'unknown', method: req.method, path: req.path, apiKey: maskApiKey(req.headers['x-api-key'] as string), userAgent: req.headers['user-agent'], }; // Capture response res.on('finish', () => { log.statusCode = res.statusCode; log.duration = Date.now() - startTime; // Log as JSON for easy parsing console.log(JSON.stringify(log)); }); next(); } function maskApiKey(apiKey: string | undefined): string { if (!apiKey) return 'none'; if (apiKey.length <= 8) return '***'; return apiKey.substring(0, 8) + '...'; } ``` **2.2 Enable in http-server.ts** ```typescript // Add import import { auditLogger } from './middleware/audit-logger.js'; // Add middleware (before routes) app.use(auditLogger); ``` **2.3 Rebuild and restart** ```bash npm run build docker-compose restart mimir_server ``` --- ### Step 3: IP Whitelisting (30 minutes) **3.1 Update nginx.conf** Add to server block: ```nginx # IP Whitelisting (add your office/VPN IPs) allow 10.0.0.0/8; # Internal network allow 192.168.0.0/16; # Private network allow 172.16.0.0/12; # Docker network deny all; # Deny everything else ``` **3.2 Reload Nginx** ```bash docker-compose exec nginx nginx -s reload ``` --- ### Step 4: Documentation (30 minutes) **4.1 Create SECURITY.md** ```markdown # Mimir Security Policy ## Access Control **API Key Required**: All requests must include `X-API-Key` header. **Allowed IPs**: - 10.0.0.0/8 (internal network) - 192.168.0.0/16 (private network) **Rate Limit**: 100 requests/minute per IP ## Getting an API Key Contact your Mimir administrator. ## Reporting Security Issues **DO NOT** open public GitHub issues for security vulnerabilities. Email: security@yourcompany.com ## Incident Response If you suspect unauthorized access: 1. Immediately contact security team 2. Do not modify any logs 3. Document what you observed ## Compliance Current security posture: - ✅ HTTPS/TLS 1.2+ - ✅ API key authentication - ✅ Rate limiting - ✅ Audit logging - ✅ IP whitelisting For GDPR/HIPAA/FISMA requirements, see [Enterprise Readiness Audit](docs/security/ENTERPRISE_READINESS_AUDIT.md). ``` **4.2 Update README.md** Add security section: ```markdown ## 🔒 Security Mimir includes basic security controls suitable for internal/trusted networks: - HTTPS/TLS encryption - API key authentication - Rate limiting - Audit logging - IP whitelisting **For production deployments**, see: - [Security Quick Start](docs/security/SECURITY_QUICK_START.md) - 4-hour hardening guide - [Enterprise Readiness Audit](docs/security/ENTERPRISE_READINESS_AUDIT.md) - Full compliance analysis **For regulated environments (HIPAA/FISMA/GDPR)**, additional controls are required. See the Enterprise Readiness Audit for details. ``` --- ## ✅ Verification ### Test HTTPS ```bash # Should work (with valid API key) curl -k -H "X-API-Key: YOUR_API_KEY" https://localhost/health # Should fail (no API key) curl -k https://localhost/health # Expected: 401 Unauthorized # Should fail (wrong API key) curl -k -H "X-API-Key: wrong-key" https://localhost/health # Expected: 401 Unauthorized ``` ### Test Rate Limiting ```bash # Send 150 requests (should be rate limited after 100) for i in {1..150}; do curl -k -H "X-API-Key: YOUR_API_KEY" https://localhost/health done # Expected: Some requests return 503 Service Unavailable ``` ### Check Audit Logs ```bash docker-compose logs mimir_server | grep audit # Should see JSON logs with timestamp, IP, method, path, etc. ``` --- ## 📊 What You've Achieved **Security Controls**: - ✅ **Encryption in Transit**: TLS 1.2+ (HTTPS) - ✅ **Authentication**: API key validation - ✅ **Rate Limiting**: 100 req/min (DoS protection) - ✅ **Audit Logging**: All requests logged - ✅ **Network Security**: IP whitelisting **Risk Reduction**: **~70%** (from baseline) **Compliance**: - ✅ Suitable for internal/trusted networks - ⚠️ **NOT** GDPR/HIPAA/FISMA compliant (requires Phase 2/3) --- ## 🚀 Next Steps ### For Internal Use (You're Done!) Current security is sufficient for: - Internal development teams - Trusted network deployments - Non-sensitive data **Maintain security**: - Rotate API keys quarterly - Review audit logs weekly - Update dependencies monthly --- ### For Customer Data (Phase 2 - 4 weeks) Add: - OAuth 2.0 authentication - Role-based access control (RBAC) - Data retention policies - Privacy API endpoints **See**: [Enterprise Readiness Audit - Phase 2](./ENTERPRISE_READINESS_AUDIT.md#phase-2-compliance-basics-2-4-weeks) --- ### For Regulated Data (Phase 3 - 3 months) Add: - Multi-factor authentication (MFA) - FIPS 140-2 encryption - Intrusion detection - Annual penetration testing **See**: [Enterprise Readiness Audit - Phase 3](./ENTERPRISE_READINESS_AUDIT.md#phase-3-enterprise-hardening-1-2-months) --- ## 🆘 Troubleshooting ### "Connection refused" after adding Nginx **Problem**: Mimir not accessible **Solution**: ```bash # Check Nginx is running docker-compose ps nginx # Check Nginx logs docker-compose logs nginx # Verify Nginx can reach Mimir docker-compose exec nginx ping mimir_server ``` ### "Certificate not trusted" in browser **Problem**: Self-signed certificate warning **Solution**: This is expected for self-signed certs. Options: 1. Accept the warning (for internal use) 2. Add cert to system trust store 3. Use Let's Encrypt for production (see Phase 2) ### API key not working **Problem**: 401 Unauthorized with valid key **Solution**: ```bash # Check environment variable is set docker-compose exec nginx env | grep MIMIR_API_KEY # Verify key matches echo $MIMIR_API_KEY ``` --- ## 📚 Additional Resources - [Enterprise Readiness Audit](./ENTERPRISE_READINESS_AUDIT.md) - Full security analysis - [OWASP Top 10](https://owasp.org/www-project-top-ten/) - Web application security risks - [Docker Security Best Practices](https://docs.docker.com/engine/security/) - Container security - [Neo4j Security](https://neo4j.com/docs/operations-manual/current/security/) - Database security --- **Last Updated**: 2025-11-21 **Version**: 1.0.0 **Maintainer**: Security Team