delphi-database/docs/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
```bash
# 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:**
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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)
```bash
# 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
```bash
# 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
```bash
# 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!**