delphi-database/SECURITY.md

Security Guide - Delphi Consulting Group Database System

This document outlines the comprehensive security measures implemented to protect sensitive data and prevent accidental exposure of secrets.

🛡️ Security Architecture

Multi-Layer Protection

1. Environment Variables - All secrets stored in .env files
2. Git Ignore Rules - Comprehensive patterns to prevent sensitive file commits
3. Pre-commit Hooks - Automated checks before code commits
4. Docker Security - Non-root containers, secure file permissions
5. Access Control - JWT-based authentication with role separation

🔐 Environment Security

Automated Setup

# Generate secure configuration
python scripts/setup-security.py

What it creates:

• Cryptographically secure SECRET_KEY (32-byte URL-safe)
• Strong admin password (16 chars, mixed complexity)
• Proper CORS configuration
• Secure file permissions (600) on .env

Manual Security Checklist

• Change default SECRET_KEY in production
• Use strong admin passwords (16+ characters)
• Configure CORS for your domain only
• Enable HTTPS in production
• Set secure cookie flags
• Configure rate limiting
• Regular security updates

📁 File Protection

.gitignore Security Patterns

Critical files that are NEVER committed:

# Environment & Secrets
.env*
*.env

# Database files (contain customer data)
*.db
*.sqlite
*.sqlite3
delphi_database.db

# Backup files (contain sensitive data)  
backups/
*.backup
*.bak
*.dump

# Upload files (user documents)
uploads/
user-uploads/

# SSL certificates & keys
ssl/
*.pem
*.key
*.crt
*.cert

# Legacy Pascal files (old database system)
*.SC
*.SC2
*.LIB

File Attribute Security

.gitattributes ensures:

• Database files treated as binary (prevents corruption)
• SSL certificates treated as binary (security)
• Legacy Pascal files preserved in original format
• Environment files tracked for proper diff/merge

🔒 Git Hooks Protection

Pre-commit Hook Features

# Install security hooks
./scripts/install-git-hooks.sh

Automatic Protection Against:

• Environment files (.env)
• Database files (*.db, *.sqlite)
• Backup files (backups/, *.backup)
• SSL certificates (*.pem, *.key)
• Upload directories
• Large files (>1MB, potential data dumps)
• Common secret patterns in code

Hook Actions:

• ❌ BLOCKS commits with security violations
• ⚠️ WARNS about potential issues
• ✅ ALLOWS safe commits to proceed

Bypass (Emergency Only)

# NOT RECOMMENDED - only for emergencies
git commit --no-verify

🐳 Docker Security

Container Hardening

• Non-root user (UID/GID 1001)
• Minimal base image (Python slim)
• Read-only filesystem where possible
• Health checks for monitoring
• Resource limits to prevent DoS
• Secure volume mounts

Production Security

# Production environment
DEBUG=False
SECURE_COOKIES=True
SECURE_SSL_REDIRECT=True

Network Security

• Nginx reverse proxy with rate limiting
• SSL/TLS termination
• Security headers (HSTS, XSS protection, etc.)
• CORS restrictions
• API rate limiting

🚨 Incident Response

If Secrets Are Accidentally Committed

1. Immediate Actions

# Remove from staging immediately
git reset HEAD .env

# If already committed locally (not pushed)
git reset --hard HEAD~1

# If already pushed to remote
git revert <commit-hash>

2. Rotate All Compromised Secrets

• Generate new SECRET_KEY
• Change admin passwords
• Rotate API keys
• Update SSL certificates if exposed
• Notify security team

3. Clean Git History (if necessary)

# WARNING: This rewrites history - coordinate with team
git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch .env' \
  --prune-empty --tag-name-filter cat -- --all

# Force push (dangerous)
git push origin --force --all

If Database Is Compromised

1. Immediate containment - Stop all services
2. Assess scope - What data was exposed?
3. Notify stakeholders - Legal, compliance, customers
4. Restore from backup - Last known clean state
5. Forensic analysis - How did it happen?
6. Strengthen defenses - Prevent recurrence

📊 Security Monitoring

Health Checks

# Application health
curl http://localhost:6920/health

# Container health
docker ps --format "table {{.Names}}\t{{.Status}}"

# Security scan
docker scan delphi-database:latest

Log Monitoring

# Application logs
docker logs -f delphi-database

# Security events
grep -i "error\|fail\|security" logs/*.log

# Failed login attempts
grep "401\|403" access.log

Regular Security Tasks

• Weekly: Review access logs
• Monthly: Update dependencies
• Quarterly: Security assessment
• Annually: Penetration testing
• As needed: Incident response drills

🎯 Security Standards Compliance

Data Protection

• Encryption at rest (database files)
• Encryption in transit (HTTPS/TLS)
• Access logging (authentication events)
• Data retention policies
• Regular backups with encryption

Authentication & Authorization

• JWT tokens with expiration
• Password hashing (bcrypt)
• Role-based access (User/Admin)
• Session management
• Account lockout protection

Network Security

• Firewall rules
• Rate limiting
• CORS policies
• Security headers
• SSL/TLS encryption

🆘 Emergency Contacts

Security Issues

• Primary: System Administrator
• Secondary: IT Security Team
• Escalation: Management Team

Incident Reporting

1. Immediate: Stop affected services
2. Within 1 hour: Notify security team
3. Within 24 hours: Document incident
4. Within 72 hours: Complete investigation

---

✅ Security Verification Checklist

Before going to production, verify:

• Environment secrets configured securely
• Git hooks installed and working
• .gitignore prevents sensitive file commits
• SSL/HTTPS configured properly
• Database backups encrypted and tested
• Access logs enabled and monitored
• Rate limiting configured
• Security headers enabled
• Container runs as non-root user
• Firewall rules configured
• Incident response plan documented
• Team trained on security procedures

Remember: Security is everyone's responsibility!