trustos/SECURITY_CHECKLIST.md

# TrustOS Security Checklist

## Pre-Deployment Security Audit

### Authentication & Authorization ✅
- [x] Password hashing using bcrypt
- [x] JWT tokens with configurable expiry (60 minutes)
- [x] Role-based access control (Executive, IT Admin, TrustOS Admin)
- [x] Tenant isolation enforced at API layer
- [x] Token validation on all protected routes
- [x] HTTP-only cookies for token storage

### Data Protection ✅
- [x] Database connections use async SQLAlchemy
- [x] Parameterized queries (no SQL injection risk)
- [x] Multi-tenant data isolation enforced
- [x] Sensitive fields encrypted in transit (HTTPS required)
- [x] Database password management via environment variables

### API Security ✅
- [x] CORS configuration available
- [x] Rate limiting can be enabled
- [x] Input validation via Pydantic schemas
- [x] Output validation via response models
- [x] Error messages don't leak sensitive info
- [x] Health check endpoints available

### Frontend Security ✅
- [x] No hardcoded credentials in code
- [x] API URL configurable via environment
- [x] XSS protection via React (no dangerouslySetInnerHTML)
- [x] CSRF tokens for state-changing operations
- [x] Secure session management

### Infrastructure ✅
- [x] PostgreSQL 16 with default security
- [x] Database connection pooling configured
- [x] Environment variables for secrets management
- [x] Health checks for all services
- [x] Proper error handling without leaking details

## Deployment Checklist

### Pre-Deployment
- [ ] All environment variables documented in `.env.production.example`
- [ ] Database backups configured
- [ ] Secrets stored securely (Railway, Render, or 1Password)
- [ ] SSL certificates ready or auto-configured
- [ ] Custom domain configured
- [ ] CORS origins whitelist updated
- [ ] API rate limiting configured (if needed)

### During Deployment
- [ ] DATABASE_URL points to production database
- [ ] SECRET_KEY is strong (64+ random characters)
- [ ] OPENAI_API_KEY or ANTHROPIC_API_KEY configured (optional)
- [ ] NEXT_PUBLIC_API_URL matches production API endpoint
- [ ] All health checks passing
- [ ] Database migrations ran successfully
- [ ] Demo data seeded (if applicable)

### Post-Deployment
- [ ] Test login flow with credentials
- [ ] Verify dashboard displays real data
- [ ] Test API endpoints directly (curl)
- [ ] Check logs for errors
- [ ] Verify SSL certificate is valid
- [ ] Test across multiple devices/browsers
- [ ] Configure uptime monitoring (UptimeRobot)
- [ ] Set up error tracking (Sentry)

## Security Best Practices

### Secrets Management
```bash
# NEVER commit .env files
# Use environment-specific files:
.env                  # Never commit
.env.local           # Never commit (local development)
.env.production      # Never commit (use Railway/Render UI)
.env.example         # Commit (template with placeholders)
.env.production.example  # Commit (production template)
```

### Production Environment Variables
Store these in Railway/Render dashboard, NOT in code:
- `SECRET_KEY` - 64+ character random string
- `DATABASE_URL` - Production database connection
- `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` - API credentials
- `SMTP_PASSWORD` - Email service credentials
- `SENTRY_DSN` - Error tracking

### Password Requirements
All users must use strong passwords:
- Minimum 12 characters
- Mix of uppercase, lowercase, numbers, symbols
- Not a common word or phrase
- Changed on first login (for generated passwords)

### API Security
```bash
# Test authentication
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"password"}'

# Test token validation
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8000/api/v1/dashboard/tenant-id
```

### Database Security
```bash
# Backup database regularly
pg_dump $DATABASE_URL > trustos_$(date +%Y%m%d_%H%M%S).sql

# Test backups can restore
psql $DATABASE_URL < trustos_backup.sql
```

## Monitoring & Incident Response

### Set Up Monitoring
1. **Uptime Monitoring** (UptimeRobot)
   - Monitor: `https://api.yourdomain.com/health`
   - Alert on: Down, SSL certificate expiration

2. **Error Tracking** (Sentry)
   - Configure `SENTRY_DSN` in production
   - Set up alerts for critical errors
   - Review errors weekly

3. **Log Monitoring**
   - Railway/Render: Built-in log dashboards
   - VPS: Use systemd journalctl or ELK stack

### Incident Response
If security incident occurs:
1. Immediately rotate `SECRET_KEY`
2. Force password resets for affected users
3. Review logs for unauthorized access
4. Audit all data access in last 30 days
5. Notify affected users and stakeholders
6. Document incident for compliance

## Compliance Notes

### Data Protection
- Audit logs track all data access
- Soft deletes preserve data history
- Regular backups maintain disaster recovery

### Access Control
- Role-based access enforced (Executive, IT Admin, Admin)
- Multi-tenant isolation at database level
- Tenant-scoped API responses

### Transparency
- Users can request their data (GDPR export)
- Admin audit trail available
- Clear data retention policies

## Security Audit Trail

### Logged Events
- User logins (timestamp, IP, success/failure)
- Finding status changes (before/after, timestamp)
- Report generation and access
- Admin actions (user creation, tenant changes)

### Audit Query
```sql
-- Check all user actions in last 7 days
SELECT user_id, action, timestamp, details 
FROM audit_logs 
WHERE timestamp > NOW() - INTERVAL '7 days'
ORDER BY timestamp DESC;
```

## External Dependencies

### Third-Party Services
- **OpenAI/Anthropic** - AI risk translations (optional)
- **PostgreSQL** - Data storage
- **Railway/Render** - Cloud infrastructure
- **Let's Encrypt** - SSL certificates (free)

### Supply Chain Security
- Python dependencies: Pinned in `requirements.txt`
- Node dependencies: Pinned in `package-lock.json`
- Docker images: Specific version tags
- Regular updates via dependabot (GitHub)

## Contact & Questions

For security questions or to report vulnerabilities:
- Email: security@trustos.example.com
- Do NOT open public GitHub issues for security vulnerabilities
- Use responsible disclosure practices (30-day notice)

---

**Last Updated**: 2026-07-07
**Maintained By**: TrustOS Security Team
**Review Frequency**: Quarterly or after security incidents