AngelSix.AspNetCore.ClientIp 1.0.0

AngelSix.AspNetCore.ClientIp

Resolves the true client IP behind a reverse proxy, and decides local-network access safely.

Behind a proxy — Caddy, nginx, Traefik, especially in Docker — the connection your app can see belongs to the proxy, not the caller. The three ways that usually gets handled are all wrong, and each fails in its own direction:

• Reading Connection.RemoteIpAddress alone. In Docker that is the bridge gateway, which is an RFC1918 private address. Any "local network only" check on it therefore returns true for every caller on the internet.
• Reading X-Forwarded-For directly. Any client can set that header. IP bans and rate limits then become one header away from useless, and whatever address an attacker puts in it is the one that gets banned — so they can pick a victim.
• Deciding trust after UseForwardedHeaders has run. That middleware overwrites RemoteIpAddress with the forwarded client and consumes the header, so the peer is already gone. Checks written after it see the client where they expect the proxy, conclude nothing is trustworthy, and lock out the legitimate local network.

This package does the one thing that works: capture the peer first, believe a forwarded header only when that peer is a configured proxy, and refuse rather than guess when it cannot tell.

Usage

app.UseAngelSixClientIp();   // FIRST — before logging, rate limiting, bans, auth

ClientIpResolver.GetClientIp(context);            // logs, bans, rate-limit partition keys
ClientIpResolver.IsLocalNetworkRequest(context);  // admin / setup gates — fails closed
ClientIpResolver.IsPrivateOrLoopback(address);

Configuration

Set KNOWN_PROXY to the address your app sees inbound traffic as. In Docker that is the bridge gateway (e.g. 172.30.0.1) — not the host the proxy runs on, because the published port NAT rewrites the source before it arrives. This catches people out constantly.

KNOWN_PROXY=172.30.0.1

Loopback is always trusted. Multiple values are comma-separated. Or configure in code:

var options = ClientIpOptions.FromEnvironment();
options.KnownProxies.Add(IPAddress.Parse("10.0.0.5"));
ClientIpResolver.Configure(options);

Surface it in your health check

Getting this wrong is silent: nothing throws, nothing logs, every client IP just collapses onto one value and stays that way until somebody notices by accident.

var (healthy, detail) = ProxyTrustReport.Describe();

When it is wrong, detail names the exact KNOWN_PROXY value to set — so the alert carries its own fix.

Licence

MIT.