docs: complete API error codes, deploy troubleshooting, monitoring/security rewrite, L2+L3 building blocks
This commit is contained in:
zwitschi committed
1 parent
0f81a81029
commit
db3bf96847
5 files changed
+267
-205
No files matched your search
+64
-98
@@ -1,127 +1,93 @@
|
||||
# Security Guide
|
||||
|
||||
This document summarizes security controls and best practices for Linear Void.
|
||||
Layered security model for Linear Void.
|
||||
|
||||
## Security Model Overview
|
||||
## Threat Model
|
||||
|
||||
Security is layered across:
|
||||
```
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ Client │───▶│Cloudflare│───▶│ nginx │───▶│ Backend │
|
||||
│ (public) │ │ WAF+CDN │ │ proxy │ │ chat │
|
||||
└──────────┘ └──────────┘ └────┬─────┘ └────┬─────┘
|
||||
│ │
|
||||
┌──────┴──────┐ ┌─────┴──────┐
|
||||
│ /health │ │ /api/admin │
|
||||
│ /metrics │ │ /ws (chat) │
|
||||
│ /hls/* │ │ /api/chat/* │
|
||||
│ (public) │ │ (auth req) │
|
||||
└─────────────┘ └────────────┘
|
||||
```
|
||||
|
||||
- Cloudflare edge
|
||||
- nginx reverse proxy
|
||||
- chat/admin backend
|
||||
- container and host operations
|
||||
## Authentication & Sessions
|
||||
|
||||
## Authentication and Sessions
|
||||
- Login: `POST /api/admin/login` → cookie `linearvoid_admin_session`
|
||||
- Cookie flags: `HttpOnly`, `SameSite=Strict`, `Secure` (over HTTPS)
|
||||
- Server-side expiry via `ADMIN_SESSION_TTL_HOURS`
|
||||
- Rate limit: 5 attempts/IP/5min via Redis
|
||||
|
||||
Admin access is session-cookie based.
|
||||
## Transport Security (TLS/HSTS)
|
||||
|
||||
- Login endpoint: /api/admin/login
|
||||
- Session endpoint: /api/admin/session
|
||||
- Logout endpoint: /api/admin/logout
|
||||
- Cookie: linearvoid_admin_session
|
||||
- Cookie flags: HttpOnly, SameSite=Strict, Secure over HTTPS
|
||||
- Session expiry enforced server-side
|
||||
- Cloudflare TLS mode: **Full (strict)** — valid origin cert required
|
||||
- nginx listens on 80 internally; Cloudflare handles TLS termination
|
||||
- HSTS header set by Cloudflare: `max-age=31536000; includeSubDomains; preload`
|
||||
- WSS upgrade path: `/ws` through nginx → chat:3000
|
||||
|
||||
Best practices:
|
||||
## Network Isolation
|
||||
|
||||
- Set strong ADMIN_USERNAME and ADMIN_PASSWORD values.
|
||||
- Rotate admin credentials periodically.
|
||||
- Keep ADMIN_SESSION_TTL_HOURS aligned with operational policy.
|
||||
|
||||
## Transport Security
|
||||
|
||||
- Enforce HTTPS for app/admin endpoints.
|
||||
- Use WSS for chat WebSocket.
|
||||
- Keep Cloudflare TLS mode strict and valid at origin.
|
||||
- All backend services on internal Docker network (`linearvoid-net`)
|
||||
- Only nginx port exposed to host (443/80)
|
||||
- Database, Redis, exporters inaccessible from outside
|
||||
- `docker-compose.prod.yml` keeps ports internal via `expose:` not `ports:`
|
||||
|
||||
## Reverse Proxy Controls
|
||||
|
||||
nginx controls include:
|
||||
- `auth_request /api/admin/auth` gate on all `/admin` and `/api/admin` paths
|
||||
- Explicit `client_max_body_size 64m` for resumable upload chunks
|
||||
- WebSocket upgrade headers: `Upgrade`, `Connection` preserved
|
||||
- CORS headers on HLS: `Access-Control-Allow-Origin *`
|
||||
- XSS protection: CSP headers served by Cloudflare
|
||||
|
||||
- auth_request guard for /admin and /api/admin paths
|
||||
- dedicated unauthorized behavior for admin API responses
|
||||
- explicit websocket upgrade headers for /ws
|
||||
- upload body-size limits for resumable media chunk uploads
|
||||
## Rate Limiting
|
||||
|
||||
Best practices:
|
||||
| Resource | Limit | Window |
|
||||
| ----------------- | ----- | ------ |
|
||||
| WebSocket connect | 5/IP | 60s |
|
||||
| Chat messages | 10/IP | 10s |
|
||||
| Admin login | 5/IP | 5min |
|
||||
|
||||
- Keep proxy body-size and timeout settings aligned across all proxy layers.
|
||||
- Avoid exposing backend service ports publicly unless required.
|
||||
Implemented via Redis `INCR` + `EXPIRE`.
|
||||
|
||||
## Input Validation and Upload Safety
|
||||
## Secrets Management
|
||||
|
||||
Server-side protections include:
|
||||
- `.env` — local dev only, **gitignored**
|
||||
- Gitea Actions secrets (`CI_*` prefix) for CI/CD
|
||||
- Never commit: passwords, tokens, API keys, R2 credentials
|
||||
- Production `.env` provisioned manually on host, never checked in
|
||||
- Rotate admin password quarterly
|
||||
|
||||
- extension allow-list for media uploads
|
||||
- MIME checks
|
||||
- file-size ceiling (2GB)
|
||||
- resumable chunk bounds and chunk-index validation
|
||||
- media path safety checks on delete
|
||||
## Data Protection
|
||||
|
||||
Best practices:
|
||||
|
||||
- Keep upload chunk size bounded.
|
||||
- Reject unsupported content types consistently.
|
||||
- Monitor 4xx/5xx rates on upload routes.
|
||||
|
||||
## Rate Limiting and Abuse Controls
|
||||
|
||||
- Chat rate limiting uses Redis INCR + EXPIRE windows.
|
||||
- Current baseline: more than 10 messages in 10 seconds is throttled.
|
||||
- Moderation actions are logged for auditability.
|
||||
|
||||
Best practices:
|
||||
|
||||
- Tune thresholds by observed abuse patterns.
|
||||
- Keep moderation logs reviewed and retained per policy.
|
||||
|
||||
## Infrastructure and Secrets
|
||||
|
||||
- Store secrets in .env (not in committed source).
|
||||
- Use Gitea Actions secrets for CI/CD credentials and admin credentials.
|
||||
- Restrict Docker host control plane exposure.
|
||||
- Limit who can read deployment environment files.
|
||||
|
||||
## Cloudflare and Edge Security
|
||||
|
||||
Recommended baseline:
|
||||
|
||||
- WAF enabled
|
||||
- Rate limits on sensitive paths
|
||||
- Bot protection where appropriate
|
||||
- Cache rules scoped carefully to avoid caching private/control-plane content
|
||||
|
||||
## Data Protection and Retention
|
||||
|
||||
- Persistent data: postgres, redis append-only, chat state, playlist/media metadata
|
||||
- Backup and restore drills should be periodic
|
||||
- Restore procedures should be tested in isolated environments
|
||||
|
||||
## Logging and Monitoring for Security
|
||||
|
||||
Track and alert on:
|
||||
|
||||
- repeated failed admin login attempts
|
||||
- spikes in 401 and 403 responses
|
||||
- sudden upload errors (413/400/500 patterns)
|
||||
- unusual websocket disconnect or message-rate anomalies
|
||||
- PostgreSQL: chat history, moderation logs, media metadata
|
||||
- Redis: append-only persistence for presence, rate limits, sessions
|
||||
- HLS segments: ephemeral, regenerated by playout
|
||||
- Backups: `scripts/backup-db.sh` (daily), `scripts/backup-weekly.sh`, `scripts/verify-backups.sh`
|
||||
|
||||
## Hardening Checklist
|
||||
|
||||
- [ ] HTTPS/WSS enforced end-to-end
|
||||
- [ ] HTTPS/WSS enforced end-to-end (Cloudflare Full strict)
|
||||
- [ ] Strong admin credentials configured
|
||||
- [ ] Secrets only in env/secrets stores
|
||||
- [ ] Secrets only in env/secrets stores (never committed)
|
||||
- [ ] Proxy auth and websocket headers validated
|
||||
- [ ] Upload limits and validation active
|
||||
- [ ] Rate limiting active and tested
|
||||
- [ ] Upload limits and MIME validation active
|
||||
- [ ] Rate limiting active (WS, messages, login)
|
||||
- [ ] Cloudflare WAF/rate-limit rules active
|
||||
- [ ] Backup/restore drills completed
|
||||
- [ ] Security-related monitoring alerts routed
|
||||
- [ ] Security alerts routed (Prometheus alertmanager)
|
||||
|
||||
## Incident Response Baseline
|
||||
## Incident Response
|
||||
|
||||
1. Detect issue (alerts/logs/user reports).
|
||||
2. Triage scope (edge, proxy, app, data plane).
|
||||
3. Contain impact (rate limit, credential rotate, route disable).
|
||||
4. Recover services and verify health.
|
||||
5. Record timeline and corrective actions.
|
||||
1. Detect — alerts (ChatDown, RedisDown, HighChatLatency) or user reports
|
||||
2. Triage — edge (Cloudflare), proxy (nginx), app (chat/playout), data (Redis/Postgres)
|
||||
3. Contain — rate limit, credential rotate, service restart, slate mode activation
|
||||
4. Recover — verify health endpoints, check Prometheus targets, validate HLS output
|
||||
5. Record — timeline + corrective actions in `docs/incident-runbook.md`
|
||||
Reference in new issue
Block a user