likwid/docs/admin/security.md

# Security Best Practices

Securing your Likwid instance.

## Authentication

### JWT Tokens

- Use a strong, random `JWT_SECRET` (64+ characters)
- Tokens expire after 24 hours by default
- Refresh tokens are not stored server-side

### Password Policy

- Minimum 8 characters (configurable)
- Bcrypt hashing with cost factor 12
- No password in logs or error messages

### Two-Factor Authentication

Enable 2FA support for users:

- TOTP (Time-based One-Time Password)
- Backup codes for recovery

## Network Security

### HTTPS

Always use HTTPS in production:

- Obtain certificates (Let's Encrypt recommended)
- Configure reverse proxy for TLS termination
- Enable HSTS headers

### Security Headers

The backend sets a small set of security headers on responses by default:

- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: DENY`
- `Referrer-Policy: no-referrer`
- `Permissions-Policy: camera=(), microphone=(), geolocation=()`
- `X-Permitted-Cross-Domain-Policies: none`

Set `Strict-Transport-Security` (HSTS) on your reverse proxy, because the backend does not know whether requests arrived via HTTPS.

### CORS

Restrict CORS in production:

```bash
CORS_ALLOWED_ORIGINS=https://likwid.example.org
```

For multiple origins, use a comma-separated list:

```bash
CORS_ALLOWED_ORIGINS=https://openlikwid.org,https://staging.openlikwid.org
```

### Rate Limiting

Protect against abuse:

- 300 requests/minute per IP (default)
- 1200 requests/minute per authenticated user
- 30 requests/minute per IP for auth endpoints

## Database Security

### Connection

- Use SSL for database connections
- Dedicated database user with minimal privileges
- Strong, unique password

### Backups

- Regular automated backups
- Encrypted backup storage
- Test restore procedures

## API Security

### Input Validation

All inputs are validated:

- Type checking
- Length limits
- Sanitization

### SQL Injection

- Parameterized queries only (SQLx)
- No raw SQL string concatenation

### XSS Prevention

- HTML escaping in templates
- Content Security Policy headers
- No inline scripts in production

## Moderation Audit Trail

All moderation actions are logged:

- Who performed the action
- What action was taken
- Why (reason required)
- When it happened

Logs are immutable and tamper-evident.

## Updates

Keep Likwid updated:

- Watch the repository for security announcements
- Apply patches promptly
- Test updates in staging first

## Incident Response

If you discover a security issue:

1. Document the incident
2. Assess impact
3. Contain the breach
4. Notify affected users if required
5. Report to Likwid security team

## Reporting Vulnerabilities

Report security issues to: [security@likwid.org](mailto:security@likwid.org)

We follow responsible disclosure practices.