second-brain/05_Resources/Immich Access Revisit Plan.md

Immich Access Revisit Plan

Context

We migrated several apps from Nginx to Pangolin on the VPS. Pangolin uses Traefik underneath as the reverse proxy. At least one test route, immich-test-2.frusetik.com, is publicly reachable over HTTPS through Pangolin/Traefik and works functionally.

An OWASP ZAP baseline scan against https://immich-test-2.frusetik.com showed mostly passive header and hardening findings, not critical exploit findings.

Main findings:

• Strict-Transport-Security header not set
• Missing anti-clickjacking header (X-Frame-Options or CSP frame-ancestors)
• X-Content-Type-Options missing
• Content-Security-Policy not set
• Permissions-Policy not set
• Cross-Origin-Resource-Policy missing or invalid
• X-Powered-By leaks implementation details
• Minor cache-control warnings
• Minor Content-Type issue for favicon.ico

Important decision context:

• Do not start by changing Immich app behavior.
• Prefer fixing this at the reverse proxy edge, meaning Traefik under Pangolin.
• Pangolin may not expose first-class UI support for response security headers, so implementation may require Traefik middleware directly or a Pangolin-compatible middleware layer.
• Goal for the next pass is a practical rollout plan first, not immediate implementation.

Recommended implementation plan

1. Prioritize these headers first

Tier 1, high value, low risk

Implement these first at the reverse proxy layer:

• Strict-Transport-Security (HSTS), starting conservatively
• X-Content-Type-Options: nosniff
• Anti-clickjacking protection, preferably Content-Security-Policy: frame-ancestors 'self' if supported cleanly, otherwise X-Frame-Options: SAMEORIGIN
• Remove or overwrite X-Powered-By where possible

Reason:

• These usually deliver real hardening value
• They are unlikely to break a normal Immich deployment when rolled out carefully
• They address the clearest ZAP findings first

Tier 2, useful but needs care

• Permissions-Policy
• Referrer-Policy (even if ZAP did not call it out, it is often worth setting while touching edge headers)
• Cross-Origin-Resource-Policy

Reason:

• Useful cleanup and defense-in-depth
• More likely to have edge-case behavior depending on how the app serves media, embeds resources, or uses browser APIs

Tier 3, highest risk / most annoying

• Full Content-Security-Policy

Reason:

• CSP is valuable, but also the most likely to break Immich UI, API calls, previews, maps, workers, WebSockets, or third-party assets if applied too aggressively
• Do not enable a strict CSP early without observing actual resource usage first

2. Where to implement in Pangolin + Traefik

Target layer: Traefik response middleware at the edge, attached only to the Immich router/service first.

Preferred order of implementation options:

1. Pangolin-supported middleware or advanced config, if Pangolin exposes a stable way to attach Traefik headers middleware to a specific route
2. Traefik dynamic configuration file/provider mounted into the Traefik container and referenced by the Immich router
3. Docker labels on the relevant service/router, if that is how Pangolin composes Traefik config internally and if custom labels are supported safely

Practical principle:

• Start route-specific, not global
• Prove the header set on immich-test-2.frusetik.com
• Only later consider promoting a safe subset to a shared middleware for other apps

3. Safe testing sequence after each change

For every header change:

1. Apply one small change or one tightly related bundle
2. Reload/redeploy Traefik/Pangolin config
3. Validate headers manually:
   • curl -I https://immich-test-2.frusetik.com
   • browser devtools network tab
4. Validate Immich behavior manually:
   • login page loads
   • login works
   • photo thumbnails load
   • full image/video views load
   • search/basic navigation works
   • mobile app or external clients still connect, if relevant
5. Re-run OWASP ZAP baseline scan
6. Check browser console for CSP, CORP, mixed-content, frame, or MIME warnings
7. Keep rollback simple, ideally by removing a single middleware reference or reverting one dynamic-config block

Recommended rollout bundles:

• Bundle A: X-Content-Type-Options, clickjacking header, remove X-Powered-By
• Bundle B: HSTS with conservative settings
• Bundle C: Permissions-Policy + optional Referrer-Policy
• Bundle D: CORP if still useful after observing actual asset behavior
• Bundle E: CSP in report-first or minimal mode

4. Headers that may be risky or annoying to enable immediately

Content-Security-Policy

Highest risk. Possible breakage areas:

• inline scripts/styles
• API endpoints
• media blobs
• WebSockets
• map tiles / third-party origins
• workers / object URLs

Safer approach later:

• start with very small policy pieces such as frame-ancestors 'self'
• or use Content-Security-Policy-Report-Only first if feasible

Strict-Transport-Security

Useful, but do not jump immediately to a long max-age with includeSubDomains and preload. Safer start:

• modest max-age, confirm no HTTP fallback dependencies remain, then increase later

Cross-Origin-Resource-Policy

Can interfere with media/resource loading depending on how Immich serves assets and whether anything cross-origin is intentional. Start only after confirming actual request patterns.

Permissions-Policy

Usually not dangerous, but easy to over-tighten if Immich or browser features rely on camera, microphone, geolocation, fullscreen, etc. Needs app-aware review.

5. What to inspect before implementation

Before touching config, inspect these exact areas:

A. Pangolin deployment and compose files

Need to locate:

• Pangolin docker-compose.yml / compose stack
• Traefik container definition
• mounted config volumes
• environment variables controlling Traefik/Pangolin integration
• whether Pangolin regenerates or overwrites Traefik config automatically

Questions to answer:

• Is Traefik running as its own container or embedded in the Pangolin stack?
• Where does dynamic config live?
• What survives container restarts or stack updates?

B. Traefik static and dynamic config

Need to inspect:

• static Traefik config file (traefik.yml / traefik.toml / command args)
• dynamic config directory or file provider
• existing middlewares
• existing routers/services for the Immich test route

Questions to answer:

• How is immich-test-2.frusetik.com mapped today?
• Can a custom headers middleware be attached cleanly to only that router?
• Is there already a shared security middleware that should be extended instead of duplicated?

C. Pangolin route/resource definitions

Need to inspect:

• how Pangolin stores public-resource definitions
• whether there is a UI/API/config field for advanced middleware, headers, or Traefik labels
• whether Pangolin regenerates routes from an internal database/config API

Questions to answer:

• Is custom middleware supported directly?
• If not, what is the least fragile escape hatch?

D. Immich upstream service definition

Need to inspect:

• compose/service definition for Immich and related containers
• whether responses already include any app-set headers
• whether WebSockets or special upstream behavior need to be preserved

Questions to answer:

• Are any headers already being set upstream and potentially overwritten?
• Does the route use WebSockets, SSE, special caching, or asset paths that constrain proxy hardening?

E. Current public response behavior

Capture a baseline before changes:

• curl -I https://immich-test-2.frusetik.com
• full response headers for key pages and asset URLs
• browser devtools export or notes for console/network behavior
• current ZAP baseline output

This gives a clean before/after comparison and rollback confidence.

Suggested first implementation later

When revisiting, the safest first real pass is:

1. Inspect Pangolin + Traefik config locations and how route-specific middleware is attached
2. Add a route-specific middleware for:
   • X-Content-Type-Options: nosniff
   • clickjacking protection (frame-ancestors 'self' or X-Frame-Options: SAMEORIGIN)
   • suppress X-Powered-By
3. Test manually
4. Re-run ZAP baseline
5. Add conservative HSTS
6. Test again
7. Leave CSP for a separate deliberate pass

Decision rule

If Pangolin does not provide a stable, update-safe way to express these headers, prefer a Traefik dynamic-config middleware over ad-hoc hacks inside the app container.