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 you enable this feature, psLens blocks requests from addresses outside the allowlist. It returns an HTTP 403 Forbidden response before session authentication or routing runs.

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)
    trustedProxies:             # Optional: explicit reverse proxy CIDRs/IPs allowed to send proxy headers
      - "10.0.0.0/8"
      - "172.16.0.0/12"

Reverse Proxy & Cloud Ingress (trustForwardHeaders)

When psLens runs behind a reverse proxy, load balancer, or cloud provider (such as Fly.io, Cloudflare, or AWS ALB), client requests terminate at the proxy.

To prevent IP spoofing, psLens inspects forwarded headers only when the direct connection socket (RemoteAddr) originates from a trusted proxy:

  • If you set trustedProxies explicitly, the direct peer must match a configured IP address or CIDR.
  • If you omit trustedProxies and set trustForwardHeaders: true, psLens trusts local and private networks (loopback, RFC 1918, RFC 4193) and Fly.io internal 6PN (fdaa::/16).

When psLens trusts the peer, it inspects headers in the following order:

  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. Infrastructure health checks (Kubernetes liveness and readiness probes, Fly.io monitors, AWS target groups) continue to report instance health without proxy IP whitelisting.

Dynamic Updates

When you manage configuration through NATS KV or the settings UI, IP allowlist changes take effect immediately on subsequent requests without server restarts.