DEV Community

Network Data Labs
Network Data Labs

Posted on Originally published at networkdatalabs.com

Detect Known VPN Traffic in Express and FastAPI Middleware

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 show false.
  • is_tor — a current Tor exit node (exits only, not guards, middle relays or bridges).
  • is_relay — privacy relay egress. It is kept separate from is_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 };
Enter fullscreen mode Exit fullscreen mode
// 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 });
});
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode
# 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}
Enter fullscreen mode Exit fullscreen mode

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
  }
}
Enter fullscreen mode Exit fullscreen mode

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 under errors without 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)