IP & CIDR Allowlist

Restrict hosted psLens instance access strictly to authorized corporate IP addresses and CIDR subnets.
Categories:

IP & CIDR Allowlist

psLens supports network-level IP address and CIDR subnet restrictions. When enabled, incoming HTTP requests from IP addresses outside the allowlist are immediately blocked with an HTTP 403 Forbidden response before any session authentication or application routing takes place.

Configuration

Add the security.ipAllowlist block to your config.yaml:

security:
  ipAllowlist:
    enabled: true
    allowedCIDRs:
      - "203.0.113.50"          # Single corporate static IP
      - "198.51.100.0/24"       # Office subnet
      - "10.0.0.0/8"            # Internal VPC / VPN network
      - "2001:db8::/32"         # IPv6 block
    trustForwardHeaders: true   # Enable when running behind reverse proxies / CDN (Fly.io, Cloudflare, AWS ALB)

Reverse Proxy & Cloud Ingress (trustForwardHeaders)

When psLens runs behind a reverse proxy, load balancer, or cloud provider (e.g. Fly.io, Cloudflare, AWS Application Load Balancer), client requests terminate at the proxy. Setting trustForwardHeaders: true enables client IP inspection in the following precedence:

  1. Fly-Client-IP (Fly.io edge proxy)
  2. CF-Connecting-IP (Cloudflare CDN)
  3. X-Real-IP (Nginx / standard reverse proxies)
  4. X-Forwarded-For (First IP in comma-separated proxy list)
  5. RemoteAddr (Direct TCP connection socket)

Health Check Probes Exemption

The /healthz endpoint is always exempt from IP filtering. This ensures infrastructure health checks (Kubernetes liveness/readiness probes, Fly.io health monitors, AWS target groups) continue to report accurate instance health without needing proxy IP whitelisting.

Dynamic Updates

When configuration is managed via NATS KV / settings, IP allowlist changes take effect immediately on subsequent requests without requiring server restarts.