A spike hits /account. Half the requests look scripted. Someone on the team suggests a one-line fix: block every VPN. That rule is tempting, and it is a good way to lock out people on a company VPN or a privacy relay, while anyone determined just switches networks.
A better pattern is middleware that looks up the client IP, attaches a few flags to the request, and steps up verification on sensitive paths. Log it, tighten a rate limit, or send a challenge. Don’t hard-block by default, and don’t treat a flag as a verdict that someone is hiding something.
This post is that middleware in Express and in FastAPI. A longer walkthrough, including a few more edge cases, is in the guide to detecting VPN traffic in Node.js and Python.
What the flags actually mean
One GET /v0/ip/{ip} call, with Authorization: Bearer, returns location, network and traits. This is not proxy detection. On a paid key, the traits that matter for live traffic are:
-
is_vpn— the IP belongs to a known VPN network, including major commercial VPN providers. Whole networks of VPN-heavy hosting providers are flagged, so other servers on those networks are flagged too. A new VPN range may still showfalse. -
is_tor— a current Tor exit node (exits only, not guards, middle relays or bridges). -
is_relay— privacy relay egress. It is kept separate fromis_vpn, so you don’t treat privacy-relay users like VPN users by mistake. -
is_hosting— hosting/datacenter detection: cloud, hosting and CDN networks where real users rarely browse from.
Behind a known VPN network, a Tor exit or a privacy relay, location is the egress, not the user’s. Use the flags as signals.
These risk flags (is_vpn, is_tor, is_relay, is_hosting) are paid-only; plans start at $9/month. A free key returns geolocation and ASN only — the flags are omitted — at 1,000 requests per UTC calendar month and 1 request/second, for personal and non-commercial use. Commercial use needs a paid plan. The flag reference is on the VPN detection API page.
Get the real client IP first
Behind Nginx, a load balancer or a CDN, the socket address is the proxy, not the visitor. In Express, set trust proxy to match your topology and use req.ip — never parse raw X-Forwarded-For yourself; a client can put any address there. In FastAPI / Uvicorn, start with --proxy-headers --forwarded-allow-ips so request.client.host is the visitor. Strip the ::ffff: prefix from IPv4-mapped IPv6 addresses before you look the IP up.
Express middleware
Keep the key in NDL_API_KEY on the server. This helper caches per IP, times out at 800 ms and fails open. Attach it after trust proxy is set:
// vpn-mw.js (Node 18+, global fetch)
const API = "https://api.networkdatalabs.com/v0/ip/";
const KEY = process.env.NDL_API_KEY;
const cache = new Map(); // swap for Redis/LRU in production
const TTL_MS = 6 * 60 * 60 * 1000;
function normalize(ip) {
return ip && ip.startsWith("::ffff:") ? ip.slice(7) : ip;
}
async function lookup(ip) {
const hit = cache.get(ip);
if (hit && hit.exp > Date.now()) return hit.data;
const res = await fetch(API + encodeURIComponent(ip), {
headers: { Authorization: `Bearer ${KEY}` },
signal: AbortSignal.timeout(800),
});
if (!res.ok) throw new Error(`lookup ${res.status}`);
const data = await res.json();
cache.set(ip, { data, exp: Date.now() + TTL_MS });
return data;
}
function vpnTraffic() {
return async (req, res, next) => {
try {
req.ipIntel = await lookup(normalize(req.ip));
} catch {
req.ipIntel = null; // fail open: never block the request
}
next();
};
}
module.exports = { vpnTraffic };
// app.js
const express = require("express");
const { vpnTraffic } = require("./vpn-mw");
const app = express();
app.set("trust proxy", 1); // one reverse proxy; see the Express guide
app.use(vpnTraffic());
app.get("/account", (req, res) => {
const t = req.ipIntel?.traits ?? {};
// Step up on known VPN networks, Tor exits or hosting IPs.
// Privacy relay (is_relay) is usually a normal user — log it, don't block.
if (t.is_tor || t.is_vpn || t.is_hosting) {
res.set("X-Step-Up", "verify");
}
res.json({ ok: true });
});
The same policy in FastAPI
Tell Uvicorn which proxy to trust, then read request.state.ip_intel in the route:
# vpn_mw.py
import os, time
from urllib.parse import quote
import httpx
from starlette.middleware.base import BaseHTTPMiddleware
API = "https://api.networkdatalabs.com/v0/ip/"
HEADERS = {"Authorization": f"Bearer {os.environ['NDL_API_KEY']}"}
_client = httpx.AsyncClient(timeout=httpx.Timeout(0.8), headers=HEADERS)
_cache: dict[str, tuple[float, dict]] = {}
TTL = 6 * 3600
def normalize(ip: str) -> str:
return ip[7:] if ip and ip.startswith("::ffff:") else ip
async def lookup(ip: str) -> dict | None:
hit = _cache.get(ip)
if hit and hit[0] > time.time():
return hit[1]
try:
r = await _client.get(API + quote(ip, safe=""))
r.raise_for_status()
except httpx.HTTPError:
return None # fail open
data = r.json()
_cache[ip] = (time.time() + TTL, data)
return data
class VpnTrafficMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request, call_next):
ip = request.client.host if request.client else ""
request.state.ip_intel = await lookup(normalize(ip))
return await call_next(request)
# app.py — FastAPI behind one trusted proxy
# uvicorn app:app --proxy-headers --forwarded-allow-ips="10.0.0.5"
from fastapi import FastAPI, Request
from vpn_mw import VpnTrafficMiddleware
app = FastAPI()
app.add_middleware(VpnTrafficMiddleware)
@app.get("/account")
async def account(request: Request):
data = request.state.ip_intel
t = (data or {}).get("traits") or {}
step_up = bool(t.get("is_tor") or t.get("is_vpn") or t.get("is_hosting"))
return {"ok": True, "step_up": step_up}
How to treat each flag
| Signal | What it means | Suggested action |
|---|---|---|
is_tor |
Current Tor exit node | Step up or challenge; don’t hard-block unless you must |
is_vpn |
Known VPN networks, including major commercial VPN providers | Log it; step up on sensitive paths (account, payment) |
is_hosting |
Hosting/datacenter IP: often scripts and bots | Tighter rate limit or a challenge |
is_relay |
Privacy relay: usually a normal, privacy-minded user | Allow; don’t treat the location as precise |
You can hard-block every known VPN network, but it usually backfires. Plenty of real users come from a known VPN network or a privacy relay. Leave is_relay alone unless you have a reason not to.
A fixture: 8.8.8.8 is hosting, not a VPN
A public US DNS resolver is a useful check. It should come back as US with is_hosting and is_anycast true, and is_vpn / is_tor / is_relay false. If your middleware would treat this IP as a VPN, the rule is too broad.
$ curl -s https://api.networkdatalabs.com/v0/ip/8.8.8.8 \
-H "Authorization: Bearer YOUR_API_KEY" \
| jq '{country_code: .location.country_code, traits}'
{
"country_code": "US",
"traits": {
"is_anycast": true,
"is_hosting": true,
"is_mobile": false,
"is_satellite": false,
"is_bogon": false,
"is_vpn": false,
"is_tor": false,
"is_relay": false
}
}
Documentation IPs like 203.0.113.10 are reserved TEST-NET addresses. The API returns them with traits.is_bogon true and no useful location. They’re fine for exercising fail-open; use a public US IP such as 8.8.8.8 when you want a real geolocation and traits fixture.
If the country looks “wrong” on a VPN, you’re seeing the egress. The IP belongs to the known VPN network, the Tor exit or the privacy relay, so location.country_code is that exit’s country, not the user’s.
Caching, timeouts and quota
- Cache per IP for a few hours. Most traffic is repeat visitors, so the cache absorbs most lookups.
- Skip paths that don’t need it — static assets, health checks — so you don’t spend quota on them.
- Fail open on timeouts and errors; log that the lookup was unavailable.
-
Backfilling logs? Use
POST /v0/bulk(paid plans) with up to 100 IPs per request. Each IP counts toward the monthly quota; a bad IP shows up undererrorswithout failing the batch.
That’s the middleware we actually shipped: flags as signals, a short cache, and a fail-open path so a lookup outage never takes the app down.
— The Network Data Labs team
Top comments (0)