# IP & CIDR Allowlist

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

---

LLMS index: [llms.txt](/llms.txt)

---

## 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`:

```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.