IP Allowlist Guard¶

ip_allowlist(*, allow, trusted_proxies) — restricts access to clients whose IP falls inside configured CIDR ranges.

Signature¶

def ip_allowlist(
    *,
    allow: Iterable[str],
    trusted_proxies: Iterable[str] = (),
) -> type:
    ...

Parameters:

Parameter	Type	Default	Description
`allow`	iterable	—	CIDR ranges or bare IPs, e.g. `"10.0.0.0/8"`, `"127.0.0.1"`. At least one required.
`trusted_proxies`	iterable	`()`	CIDR ranges of your proxies, e.g. `"100.64.0.0/10"`. When non-empty, `X-Forwarded-For` is honoured for clients coming from trusted proxies.

from lauren_guards import ip_allowlist

InternalGuard = ip_allowlist(allow=["10.0.0.0/8", "192.168.1.0/24"])

With a trusted reverse proxy in front (load balancer / VPN):

InternalGuard = ip_allowlist(
    allow=["10.0.0.0/8"],
    trusted_proxies=["100.64.0.0/10"],  # your proxy range
)

With trusted_proxies=() (default) the guard uses the direct socket peer address — X-Forwarded-For is ignored, so a client cannot spoof its way past the allowlist.
With trusted_proxies set, the guard inspects X-Forwarded-For only when the direct peer is within a trusted proxy range, and picks the rightmost untrusted hop. This lets deployments behind a known proxy write allowlists for the real client IP.

A client whose effective IP is not in allow → ForbiddenError (403). Allowed clients pass through unchanged.