Add security fixes and comprehensive documentation
Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
+323
@@ -0,0 +1,323 @@
|
||||
# Security Policy
|
||||
|
||||
## Supported Versions
|
||||
|
||||
We take security seriously and actively maintain the latest version of Quizzical Beats.
|
||||
|
||||
| Version | Supported |
|
||||
| ------- | ------------------ |
|
||||
| Latest | :white_check_mark: |
|
||||
| < Latest| :x: |
|
||||
|
||||
## Reporting a Vulnerability
|
||||
|
||||
If you discover a security vulnerability in Quizzical Beats, please report it responsibly:
|
||||
|
||||
1. **DO NOT** open a public GitHub issue
|
||||
2. Email security details to: christian@kaufdeinquiz.com
|
||||
3. Include:
|
||||
- Description of the vulnerability
|
||||
- Steps to reproduce
|
||||
- Potential impact
|
||||
- Suggested fix (if available)
|
||||
|
||||
We will respond within 48 hours and work with you to understand and address the issue.
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### Deployment Security
|
||||
|
||||
#### 1. Environment Variables
|
||||
|
||||
**CRITICAL**: Never use default values in production!
|
||||
|
||||
```bash
|
||||
# Generate secure secrets
|
||||
python -c 'import secrets; print(secrets.token_hex(32))' # For SECRET_KEY
|
||||
python -c 'import secrets; print(secrets.token_urlsafe(32))' # For AUTOMATION_TOKEN
|
||||
```
|
||||
|
||||
**Required secure variables:**
|
||||
- `SECRET_KEY`: Flask session encryption (32+ bytes hex)
|
||||
- `AUTOMATION_TOKEN`: API authentication (32+ bytes URL-safe)
|
||||
|
||||
#### 2. HTTPS Configuration
|
||||
|
||||
**REQUIRED for production:**
|
||||
|
||||
```env
|
||||
USE_HTTPS=True
|
||||
PREFERRED_URL_SCHEME=https
|
||||
DEBUG=False
|
||||
```
|
||||
|
||||
Use a reverse proxy (nginx, Traefik, Caddy) for SSL termination.
|
||||
|
||||
#### 3. Database Security
|
||||
|
||||
- Use PostgreSQL or MySQL in production (not SQLite)
|
||||
- Enable database encryption at rest
|
||||
- Use strong database passwords
|
||||
- Restrict database network access
|
||||
- Regular backups with encryption
|
||||
|
||||
#### 4. OAuth Configuration
|
||||
|
||||
**Redirect URI Security:**
|
||||
- Use HTTPS redirect URIs in production
|
||||
- Never use wildcards in redirect URIs
|
||||
- Validate all OAuth state parameters
|
||||
|
||||
**Token Storage:**
|
||||
- OAuth tokens are encrypted in the database
|
||||
- Use secure session storage (Redis recommended)
|
||||
- Set appropriate token expiration times
|
||||
|
||||
#### 5. API Keys Protection
|
||||
|
||||
**Storage:**
|
||||
- Store API keys in `.env` file only
|
||||
- Never commit `.env` to version control
|
||||
- Use secret management services (e.g., AWS Secrets Manager, HashiCorp Vault)
|
||||
|
||||
**Rotation:**
|
||||
- Rotate Spotify/Deezer API credentials regularly
|
||||
- Update OAuth client secrets periodically
|
||||
- Monitor API key usage for anomalies
|
||||
|
||||
### Application Security
|
||||
|
||||
#### 1. Authentication
|
||||
|
||||
- Use strong passwords (12+ characters, mixed case, numbers, symbols)
|
||||
- Enable multi-factor authentication via OAuth providers
|
||||
- Implement account lockout after failed login attempts
|
||||
- Use secure password hashing (werkzeug PBKDF2-SHA256)
|
||||
|
||||
#### 2. Session Management
|
||||
|
||||
- Sessions expire after inactivity
|
||||
- Use secure, httponly cookies
|
||||
- CSRF protection enabled (Flask-WTF)
|
||||
- Session data encrypted with SECRET_KEY
|
||||
|
||||
#### 3. Input Validation
|
||||
|
||||
- All user inputs are validated
|
||||
- SQL injection protected via SQLAlchemy ORM
|
||||
- XSS protection via template auto-escaping
|
||||
- File upload validation (type, size limits)
|
||||
|
||||
#### 4. Rate Limiting
|
||||
|
||||
**Recommendations:**
|
||||
```python
|
||||
# Add to production deployment
|
||||
- Login endpoints: 5 attempts per minute
|
||||
- API endpoints: 100 requests per minute
|
||||
- File uploads: 10 per hour
|
||||
```
|
||||
|
||||
#### 5. Dependency Management
|
||||
|
||||
**Current Known Issues:**
|
||||
- ~~authlib < 1.6.5~~ (FIXED: upgraded to 1.6.5+)
|
||||
|
||||
**Maintenance:**
|
||||
```bash
|
||||
# Check for vulnerabilities
|
||||
pip install safety
|
||||
safety check
|
||||
|
||||
# Update dependencies
|
||||
pip list --outdated
|
||||
pip install --upgrade <package>
|
||||
```
|
||||
|
||||
### Infrastructure Security
|
||||
|
||||
#### 1. Docker Security
|
||||
|
||||
**Best practices:**
|
||||
```dockerfile
|
||||
# Use non-root user
|
||||
USER musicround
|
||||
|
||||
# Minimize attack surface
|
||||
FROM python:3.11-slim
|
||||
|
||||
# Security updates
|
||||
RUN apt-get update && apt-get upgrade -y
|
||||
```
|
||||
|
||||
#### 2. Network Security
|
||||
|
||||
- Use firewall rules (only expose ports 80, 443)
|
||||
- Implement DDoS protection (Cloudflare, AWS Shield)
|
||||
- Use VPN for administrative access
|
||||
- Enable audit logging
|
||||
|
||||
#### 3. File System Security
|
||||
|
||||
```bash
|
||||
# Secure file permissions
|
||||
chmod 600 .env
|
||||
chmod 700 data/
|
||||
chmod 755 musicround/
|
||||
|
||||
# Restrict write access
|
||||
chown -R musicround:musicround /app
|
||||
```
|
||||
|
||||
#### 4. Backup Security
|
||||
|
||||
- Encrypt backups at rest and in transit
|
||||
- Store backups in separate location/region
|
||||
- Test backup restoration regularly
|
||||
- Implement retention policies (30-90 days)
|
||||
|
||||
### Monitoring and Logging
|
||||
|
||||
#### 1. Security Logging
|
||||
|
||||
**Log these events:**
|
||||
- Failed login attempts
|
||||
- Password changes
|
||||
- OAuth token creation/refresh
|
||||
- API key usage
|
||||
- Admin actions
|
||||
- File uploads/downloads
|
||||
|
||||
#### 2. Alerting
|
||||
|
||||
**Configure alerts for:**
|
||||
- Multiple failed logins
|
||||
- Unusual API traffic patterns
|
||||
- Database errors
|
||||
- Backup failures
|
||||
- Certificate expiration
|
||||
|
||||
#### 3. Audit Trail
|
||||
|
||||
```python
|
||||
# Enable comprehensive logging
|
||||
import logging
|
||||
logging.basicConfig(
|
||||
level=logging.INFO,
|
||||
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
|
||||
)
|
||||
```
|
||||
|
||||
## Security Checklist for Production
|
||||
|
||||
- [ ] Generated secure SECRET_KEY (32+ bytes)
|
||||
- [ ] Generated secure AUTOMATION_TOKEN (32+ bytes)
|
||||
- [ ] Set DEBUG=False
|
||||
- [ ] Enabled HTTPS (USE_HTTPS=True)
|
||||
- [ ] Using production database (PostgreSQL/MySQL)
|
||||
- [ ] Database credentials are strong and unique
|
||||
- [ ] All OAuth redirect URIs use HTTPS
|
||||
- [ ] API keys rotated from defaults
|
||||
- [ ] Reverse proxy configured (nginx/Traefik)
|
||||
- [ ] Firewall rules enabled
|
||||
- [ ] SSL certificate valid and auto-renewing
|
||||
- [ ] Automated backups configured
|
||||
- [ ] Backup encryption enabled
|
||||
- [ ] Security monitoring enabled
|
||||
- [ ] Logs reviewed regularly
|
||||
- [ ] Dependencies up to date
|
||||
- [ ] File permissions restricted
|
||||
- [ ] Running as non-root user
|
||||
- [ ] Rate limiting implemented
|
||||
- [ ] CSRF protection enabled
|
||||
|
||||
## Security Updates
|
||||
|
||||
We recommend:
|
||||
1. Subscribe to security advisories for Python, Flask, and dependencies
|
||||
2. Review [GitHub Security Advisories](https://github.com/christianlouis/QuizzicalBeats/security/advisories)
|
||||
3. Monitor the [CHANGELOG](https://quizzicalbeats.readthedocs.io/changelog.html) for security updates
|
||||
4. Join our security mailing list (coming soon)
|
||||
|
||||
## Compliance
|
||||
|
||||
### Data Protection
|
||||
|
||||
- User data stored securely with encryption
|
||||
- OAuth tokens encrypted at rest
|
||||
- Personal information minimization
|
||||
- Data retention policies implemented
|
||||
|
||||
### GDPR Considerations
|
||||
|
||||
- User data export available
|
||||
- Account deletion supported
|
||||
- Privacy policy available
|
||||
- Cookie consent implemented
|
||||
|
||||
## Security Tools
|
||||
|
||||
### Recommended Tools
|
||||
|
||||
```bash
|
||||
# Static analysis
|
||||
pip install bandit
|
||||
bandit -r musicround/
|
||||
|
||||
# Dependency scanning
|
||||
pip install safety
|
||||
safety check
|
||||
|
||||
# Secret detection
|
||||
git-secrets --scan
|
||||
|
||||
# Container scanning
|
||||
docker scan quizzicalbeats:latest
|
||||
```
|
||||
|
||||
### CI/CD Security
|
||||
|
||||
**GitHub Actions recommended checks:**
|
||||
- Dependency vulnerability scanning
|
||||
- Static code analysis (CodeQL)
|
||||
- Secret scanning
|
||||
- Container image scanning
|
||||
- License compliance
|
||||
|
||||
## Known Security Considerations
|
||||
|
||||
### Current Limitations
|
||||
|
||||
1. **SQLite in Development**: Not suitable for concurrent production use
|
||||
2. **File System Storage**: MP3 files stored locally (consider S3 for scale)
|
||||
3. **Session Storage**: In-memory sessions don't scale (use Redis)
|
||||
4. **Rate Limiting**: Not implemented (add nginx/Cloudflare)
|
||||
|
||||
### Future Improvements
|
||||
|
||||
- [ ] Add two-factor authentication (TOTP)
|
||||
- [ ] Implement rate limiting middleware
|
||||
- [ ] Add security headers middleware
|
||||
- [ ] Content Security Policy (CSP)
|
||||
- [ ] Subresource Integrity (SRI)
|
||||
- [ ] Add honeypot fields to forms
|
||||
- [ ] Implement IP reputation checking
|
||||
- [ ] Add user session management dashboard
|
||||
|
||||
## Resources
|
||||
|
||||
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
|
||||
- [Flask Security Guide](https://flask.palletsprojects.com/en/latest/security/)
|
||||
- [Python Security Best Practices](https://python.readthedocs.io/en/latest/library/security_warnings.html)
|
||||
- [Docker Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html)
|
||||
|
||||
## Contact
|
||||
|
||||
For security concerns, contact:
|
||||
- Email: christian@kaufdeinquiz.com
|
||||
- Maintainer: Christian Krakau-Louis
|
||||
- Response Time: Within 48 hours
|
||||
|
||||
---
|
||||
|
||||
*Last updated: February 2026*
|
||||
Reference in New Issue
Block a user