sofarr/SECURITY.md

Security Policy & Hardening Guide

Supported Versions

Version	Supported
1.4.x	✅ Yes
1.3.x	✅ Yes
1.2.x	✅ Yes
1.1.x	❌ No
1.0.x	❌ No
< 1.0	❌ No

Reporting a Vulnerability

Please do not open a public issue for security vulnerabilities. Email: gordon@i3omb.com — expect acknowledgement within 48 hours.

---

Threat Model

sofarr is a personal dashboard intended for a small trusted group (household/team). It proxies requests to *arr stack services using stored API keys and authenticates users via Emby. The primary threat surface when exposed to the public internet:

Threat	Mitigations
Credential brute-force	Rate limiting (10 fails/15 min per IP), account lockout window
Session hijacking	HMAC-signed cookies, httpOnly, secure, sameSite=strict, short TTL
CSRF	Double-submit cookie pattern (X-CSRF-Token header required on all mutations)
API key leakage via errors	sanitizeError() redacts keys/tokens from all error responses and logs
Token theft after logout	Server-side token store; Emby token revoked on logout
XSS → token theft	httpOnly cookies; CSP with per-request nonce blocks inline injection
Clickjacking	X-Frame-Options: DENY + CSP frame-ancestors 'none'
Info disclosure via headers	Helmet v7 removes X-Powered-By, sets noSniff, xssFilter, etc.
Privilege escalation (container)	Non-root user (UID 1000), no-new-privileges, all caps dropped
Unbounded log growth	Size-based rotation: 10 MB cap, 3 rotated files kept
Dependency vulnerabilities	npm audit --audit-level=high in CI on every push
Unauthorized webhook injection	SOFARR_WEBHOOK_SECRET required on X-Sofarr-Webhook-Secret header; 401 on mismatch
Webhook payload injection	validatePayload() allowlists 18 known event types; rejects non-object bodies and overlong fields
Webhook replay attacks	isReplay() tracks (eventType, instanceName, date) tuples for 5 minutes; duplicate events return 200 { duplicate: true } without cache mutation
Webhook flood / DoS	Dedicated rate limiter: 60 requests/min per IP on /api/webhook/*

---

Production Deployment Checklist

Required

• COOKIE_SECRET set to a random 32-byte hex string (openssl rand -hex 32)
• NODE_ENV=production
• TRUST_PROXY=1 set if behind a reverse proxy
• sofarr bound to 127.0.0.1 only (not 0.0.0.0) — expose via proxy
• HTTPS enforced by the reverse proxy with a valid certificate
• Firewall rules: only 443/80 open externally; 3001 not directly exposed

Webhook-Specific (if using webhook integration)

• SOFARR_WEBHOOK_SECRET set to a random 32-byte hex string (openssl rand -hex 32)
• SOFARR_BASE_URL set to the public HTTPS URL of sofarr (used by one-click setup)
• Secret stored only in .env or Docker secret — never committed to source control
• Rotate SOFARR_WEBHOOK_SECRET if you suspect it has been leaked; re-enable webhooks via the UI
• Verify Sonarr/Radarr send the exact secret value in the X-Sofarr-Webhook-Secret header
• Review webhook logs ([Webhook] WARNING) for repeated auth failures which may indicate probing

Recommended

• Reverse proxy: Nginx, Caddy, or Traefik with TLS termination
• Set Strict-Transport-Security at proxy level (sofarr also sends HSTS)
• DATA_DIR on a named Docker volume (not bind-mounted to sensitive host path)
• Rotate COOKIE_SECRET periodically (causes all users to re-login)
• Enable Docker's --read-only flag (already in docker-compose.yaml)
• Monitor /health endpoint with an uptime checker

Docker Secrets (alternative to env vars)

For production environments that support Docker secrets, you can mount secret files and reference them:

secrets:
  cookie_secret:
    file: ./secrets/cookie_secret.txt
  emby_api_key:
    file: ./secrets/emby_api_key.txt

services:
  sofarr:
    secrets:
      - cookie_secret
      - emby_api_key
    environment:
      - COOKIE_SECRET_FILE=/run/secrets/cookie_secret
      - EMBY_API_KEY_FILE=/run/secrets/emby_api_key

Since v1.2.0, sofarr natively supports the _FILE pattern. Set COOKIE_SECRET_FILE=/run/secrets/cookie_secret and sofarr will read the secret value from that file at startup. See docker-compose.yaml for a complete example.

---

Reverse Proxy Example (Caddy)

sofarr.example.com {
    reverse_proxy localhost:3001
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        X-Robots-Tag "noindex, nofollow"
    }
}

Reverse Proxy Example (Nginx)

server {
    listen 443 ssl;
    server_name sofarr.example.com;

    ssl_certificate     /etc/letsencrypt/live/sofarr.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sofarr.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Required for SSE (Server-Sent Events) — disable response buffering
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
    }
}

---

Security Headers (emitted by sofarr)

Header	Value
Content-Security-Policy	default-src 'self'; script-src 'self' 'nonce-…'; style-src 'self' 'nonce-…'; style-src-attr 'unsafe-inline'; img-src 'self' data: blob:; object-src 'none'; frame-ancestors 'none'
Strict-Transport-Security	max-age=31536000; includeSubDomains; preload (production only)
X-Content-Type-Options	nosniff
X-Frame-Options	DENY
Referrer-Policy	strict-origin-when-cross-origin
Permissions-Policy	camera=(), microphone=(), geolocation=(), payment=(), usb=()

---

Rate Limits

Endpoint	Limit
POST /api/auth/login	10 failed attempts per 15 min per IP
All /api/* routes	300 requests per 15 min per IP
POST /api/webhook/*	60 requests per 1 min per IP (webhook-specific limiter, stricter than general)

---

Supply Chain

• All dependencies pinned to minor version ranges in package.json
• npm audit --audit-level=high runs in CI on every push and pull request
• npm audit fix should be run when vulnerabilities are reported