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)
    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 (e.g. Fly.io, Cloudflare, AWS Application Load Balancer), client requests terminate at the proxy.

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

  • If trustedProxies is explicitly specified, the direct peer must match one of the configured IP addresses or CIDRs.
  • If trustedProxies is omitted and trustForwardHeaders: true, psLens defaults to trusting local/private networks (loopback, RFC 1918, RFC 4193) and Fly.io internal 6PN (fdaa::/16).

When the peer is trusted, psLens inspects headers 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.