DEV Community: Abdul Mateen

Access Log Analysis: Rank IPs by Risk, Not Volume

Abdul Mateen — Tue, 22 Sep 2026 12:22:33 +0000

Every access log analysis tool I've reached for ranks IPs the same way: by request count. GoAccess does it. The browser-based nginx log parsers do it. So does every awk | sort | uniq -c | sort -rn one-liner that has ever been pasted into a runbook.

That ranking answers "who is noisy." It does not answer "who is dangerous." In a real log, those are two different lists, and the gap between them is the whole problem.

TL;DR

Request count ranks your crawlers and your monitoring, not your attackers.
Two independent signal families exist: what an IP is (reputation) and what it did to you (behaviour). Neither works alone.
Bulk reputation lookups are one POST for up to 50,000 addresses, so enriching a whole log is cheap if you cache.
The step nobody implements is subtraction: verified crawlers and corporate gateway egress IPs need their scores pushed down, hard.
Every point in the score should carry a reason string, or you can't tune it and you can't defend it.

Sorting by hits gives you a list of noisy addresses. Joining reputation data to behaviour you measured yourself gives you a list of dangerous ones. The second list is shorter, more useful, and about forty lines of Python away from the first.

What "top offender" actually ranks

Here are four addresses from a sample log, sorted the usual way. The hit counts are from a synthetic log. The reputation column is real, and you can check every value in the API docs.

IP	Hits	Rank by hits	What the reputation data says
`87.58.66.106`	85	1	Zscaler corporate gateway, threat score 5
`4.227.36.0`	24	2	Verified ChatGPT crawler, `ai_crawler`, threat score 15
`145.223.7.7`	19	3	Residential proxy, VPN, known attacker, spam. Threat score 90
`223.197.196.92`	16	4	`brute_force` bot, known attacker, threat score 40

The top of that list is an entire company's workforce sharing one egress address. Second place is a crawler you probably want indexing you. The two entries you'd actually want to look at are at the bottom, and on a real log with a few thousand unique IPs they're on page three.

Worse, the naive fix makes it worse. Block the top offender and you've locked out every employee at whatever company routes through that Zscaler IP. Block the runner-up and you've told an AI crawler your site is gone. Both of those are quiet failures. Nothing in your log says "you just banned a customer's head office."

Two signals, and why neither works on its own

What the IP is

This is IP reputation data, and it comes from outside your system. Is the address a Tor exit node, a residential proxy, a VPN endpoint, a known attacker, a declared crawler, a shared corporate gateway?

You've got real options here: AbuseIPDB for community-reported abuse, IPGeolocation, IPQualityScore, Spur, MaxMind's Anonymous IP database, IPLocate. I used IPGeolocation's IP Security API for this because of two fields that matter specifically for log work, is_known_good_bot and is_corporate_gateway, plus a bulk endpoint that takes 50,000 addresses in one request. The second field is what makes the subtraction step below possible. I haven't found the same flag anywhere else, though I'd be glad to be wrong about that.

A single lookup, so you can see the whole shape:

curl -s 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=87.58.66.106'

{
  "ip": "87.58.66.106",
  "security": {
    "threat_score": 5,
    "is_tor": false,
    "is_proxy": false,
    "proxy_provider_names": [],
    "proxy_confidence_score": 0,
    "proxy_last_seen": "",
    "is_residential_proxy": false,
    "is_vpn": false,
    "vpn_provider_names": [],
    "vpn_confidence_score": 0,
    "vpn_last_seen": "",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": false,
    "is_known_attacker": false,
    "is_bot": false,
    "bot_confidence_score": 0,
    "bot_operator_name": "",
    "bot_type": "",
    "is_known_good_bot": false,
    "bot_last_seen": "",
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Zscaler Switzerland GmbH",
    "is_corporate_gateway": true,
    "corporate_gateway_type": "secure_web_gateway",
    "corporate_gateway_provider_name": "Zscaler"
  }
}

Note is_anonymous is false on that one even though hundreds of people share the address. That's correct: a corporate gateway isn't an anonymity service. The range is published by the vendor and belongs to an identifiable company. Treating it like a VPN is exactly the mistake this article is about.

Here's how I read the flags when deciding what to do:

Signal	Reading	Reasonable response
`is_known_attacker`	Observed attacking somebody	Block, or heavy friction
`bot_type` of `exploit`, `credential_stuffing`, `brute_force`, `worm`	Active attack automation. Always returns `is_known_attacker: true`	Block
`is_tor`	Tor exit node	Challenge on sensitive endpoints. Blanket blocking is a policy decision, not a security one
`is_residential_proxy`	Traffic laundered through somebody's home connection	Friction on sensitive actions, not a block
`is_anonymous`	VPN, proxy, relay or Tor	Extra verification before anything irreversible
`is_bot` true, `is_known_good_bot` false	Automation with no published operator	Your bot policy applies
`is_known_good_bot`	Declared, verifiable operator	Allow. Exempt from per-IP rate limits
`is_corporate_gateway`	Shared enterprise egress	Never block. Relax rate limits. Don't use for per-user identity
`is_cloud_provider` alone	The address lives in AWS, Azure, GCP or similar	Almost meaningless on its own. Crawlers live there too

That bot_type row has a trap in it. The value scanner appears in both the good and the bad list, because Censys and a reconnaissance script do literally the same thing. is_known_good_bot is the field that separates them, not bot_type.

What the IP did to you

Reputation alone is not enough, for two reasons that pull in opposite directions.

It over-flags. Plenty of ordinary people browse through a VPN. If is_vpn is your blocking rule, you've built a rule that fires on privacy-conscious customers and misses anyone attacking you from a clean residential address.

It also under-flags. An address with a threat score of zero that just made 200 failed SSH attempts against your box in four minutes is dangerous right now, whatever a global feed thinks of it. Your log knows something the feed doesn't.

So you measure behaviour yourself: failed authentication attempts, requests to paths that only a scanner would ask for, the ratio of 4xx and 5xx responses, 404 volume, request rate. None of that needs an API. It's all sitting in the file already.

Parse first, spend second

Parse before you enrich, for a boring but real reason: you pay per address, so you want the deduplicated set of public IPs, not every line.

import ipaddress
import re
from collections import defaultdict

COMBINED = re.compile(
    r'^(?P<ip>\S+) \S+ \S+ \[[^\]]+\] '
    r'"(?P<method>[A-Z]+) (?P<path>\S+)[^"]*" (?P<status>\d{3})'
)

SENSITIVE = ("/wp-login.php", "/.env", "/.git/", "/phpmyadmin", "/xmlrpc.php", "/admin")


def is_public(value: str) -> bool:
    """Private and bogon addresses get rejected with HTTP 423, so drop them here."""
    try:
        addr = ipaddress.ip_address(value)
    except ValueError:
        return False
    return not (
        addr.is_private or addr.is_loopback or addr.is_reserved
        or addr.is_multicast or addr.is_link_local or addr.is_unspecified
    )

The standard library settles the whole bogon question for you. Private, loopback, reserved, multicast, link-local and unspecified addresses are gone before they cost anything, which matters because the API charges 2 credits per valid address and rejects these with a 423 anyway.

Then accumulate per address:

def parse(path: str) -> dict[str, dict]:
    activity: dict[str, dict] = defaultdict(
        lambda: {"hits": 0, "errors": 0, "not_found": 0, "sensitive": 0, "auth_failures": 0}
    )
    try:
        handle = open(path, "r", encoding="utf-8", errors="replace")
    except OSError as exc:
        raise SystemExit(f"Cannot read {path}: {exc}") from exc

    with handle:
        for line in handle:
            match = COMBINED.match(line)
            if not match:
                continue  # unknown format or a truncated line; never kill the run over one line
            ip = match.group("ip")
            if not is_public(ip):
                continue  # saves 2 credits per address and avoids a guaranteed error response
            status = int(match.group("status"))
            row = activity[ip]
            row["hits"] += 1
            row["errors"] += status >= 400
            row["not_found"] += status == 404
            row["sensitive"] += any(p in match.group("path").lower() for p in SENSITIVE)
            if status in (401, 403):
                row["auth_failures"] += 1
    return dict(activity)

Forty-ish lines and you have per-IP behaviour for a combined-format log. Point it at auth.log instead and the shape of the output is identical, only the regex and the failure condition change.

Pitfall: if your app sits behind a load balancer or Cloudflare, match.group("ip") is your proxy, not your visitor. You want X-Forwarded-For, and specifically the left-most entry in the chain with any port suffix stripped. But only trust that header if your own proxy sets it. If anything upstream is reachable directly, a client can forge the entire chain and you will happily score an address that never sent you a packet. Getting this backwards is how people end up blocking their own CDN.

The full version of this on GitHub handles combined, common, JSON lines from nginx, Caddy, Traefik and CloudFront, plus auth.log, with format auto-detection and gzip support. The version above is the shape of it, not the whole thing.

Enrich in bulk without burning credits

Heads up: the Security API is not on the free plan. Both /v3/security and /v3/security-bulk return 401 for a free key. On a free tier you still get location and ASN data from /v3/ipgeo, but no threat signals, and nothing below this line will run. Better to know that now than forty minutes in.

Two things make the cost sane. One request handles up to 50,000 addresses. And lookups cost 2 credits per valid IP, with bogon, private and malformed addresses not counted at all, which is why filtering them locally is worth doing anyway.

import os
import time

import requests

SECURITY_BULK = "https://api.ipgeolocation.io/v3/security-bulk"
CHUNK = 500  # well under the 50,000 ceiling; smaller batches fail smaller


def enrich(ips: list[str], timeout: float = 20.0, retries: int = 3) -> tuple[dict, int]:
    """Look up security data for many IPs. Returns (by_ip, credits_charged)."""
    key = os.environ.get("IPGEOLOCATION_API_KEY")
    if not key:
        raise SystemExit("Set IPGEOLOCATION_API_KEY in your environment or .env file")

    results: dict[str, dict] = {}
    charged = 0

    for start in range(0, len(ips), CHUNK):
        batch = ips[start:start + CHUNK]
        for attempt in range(retries + 1):
            try:
                response = requests.post(
                    SECURITY_BULK,
                    params={"apiKey": key},
                    json={"ips": batch},
                    headers={"Content-Type": "application/json"},  # 415 without this
                    timeout=timeout,
                )
            except requests.RequestException:
                if attempt == retries:
                    raise
                time.sleep(1.5 ** attempt)
                continue

            if response.status_code == 401:
                raise SystemExit("401: the Security API requires a paid plan")
            if response.status_code == 429 and attempt < retries:
                time.sleep(float(response.headers.get("Retry-After", 1.5 ** attempt)))
                continue
            response.raise_for_status()

            charged += int(response.headers.get("X-Credits-Charged", 0))
            for entry in response.json():
                ip = entry.get("ip")
                if not ip:
                    continue  # bogon that slipped through: {"message": "... is a bogon IP address."}
                results[ip] = entry.get("security", {})
            break

    return results, charged

A few things in there are worth the keystrokes. The Content-Type header is not optional on the bulk endpoint, which will tell you so with a 415. Invalid entries come back as an object with only a message key and no ip, so iterate defensively. And X-Credits-Charged is how you find out what a run actually cost, which is the number you'll want in front of you the first time you point this at a month of logs.

You can also trim the payload with fields=security.threat_score,security.is_bot and friends if you only need a few flags. I don't bother, because the flags I'd have dropped are the ones the subtraction step needs.

Cache, or the second run costs the same as the first

Reputation data does not change minute to minute. A day-old answer for an address you saw yesterday is fine, and SQLite is plenty for this.

Give the table an IP, a JSON blob and a fetched_at timestamp, read anything newer than your TTL straight from disk, and only send the misses to the API. A 24-hour TTL is a reasonable default. If you're running hourly from cron, the cache is the difference between a bill and a rounding error.

The subtraction step nobody writes about

Every nginx log analyzer I looked at adds points. None of them take points away. That's the gap.

Two categories need their scores pushed down, and they need it for different reasons.

Verified good bots. Googlebot, Bingbot, the uptime monitor you're paying for, the security scanner you configured, the AI crawlers you decided to allow. These generate request volume that looks exactly like scraping, because it is scraping, with an operator who publishes their ranges and says so. is_known_good_bot comes back true with bot_operator_name filled in. I apply a credit of -45, which is enough to bury a crawler under anything genuinely interesting even when it's the noisiest thing in the file.

One condition on that credit: only apply it when is_known_attacker is false. A declared operator whose address later shows up in attack traffic should not get a permanent pass.

Corporate gateways. This is the one that will bite you. Enterprise secure web gateways like Zscaler and Netskope proxy employee browser traffic through the vendor's cloud and forward it to you from the vendor's address space. One IP, an entire workforce behind it. is_corporate_gateway is true, corporate_gateway_type tells you whether it's a standard gateway or remote browser isolation, and corporate_gateway_provider_name names the vendor.

The credit I apply is only -10, and the small number is deliberate. A gateway IP is not automatically safe. Somebody inside that company can still attack you through it. What the flag actually buys you is context: high request volume from a gateway is a hundred people reading your docs, three failed logins is somebody mistyping their password, and blocking the address is a support ticket from an enterprise customer asking why your site is down for their whole office.

Per-IP rate limits are the other thing to revisit. Whatever threshold you set for one human is wrong by two or three orders of magnitude for an address fronting a company.

Score it, and show your work

Start from the API's threat score, adjust with what you measured, clamp to 0 through 100. That final number is the IP risk score you sort on. Every adjustment appends a reason string, which is the difference between a tool you can tune and a number you have to trust.

Signal	Points
`is_known_attacker`	+35
Attack bot (`exploit`, `credential_stuffing`, `brute_force`, `worm`)	+25
Tor exit node	+15
Spam association	+12
Anonymised via VPN, proxy or relay	+10
Residential proxy	+8
Undeclared bot	+8
5 or more failed auth attempts (+10 more when sustained)	+40
Requests to sensitive paths (+10 more at 10 or more)	+30
Half or more of requests returning 4xx or 5xx	+15
25 or more 404s, so path enumeration	+10
120 or more requests per minute	+10
Verified good bot	-45
Corporate gateway	-10

Then bucket it: 80 and up is critical, 60 is high, 40 is medium, 20 is low, anything below that is informational.

ATTACK_BOTS = {"exploit", "credential_stuffing", "brute_force", "worm"}


def score(activity: dict, sec: dict) -> tuple[int, list[str]]:
    """Blend the API's view of the IP with what it did to you."""
    points = float(sec.get("threat_score", 0))
    reasons: list[str] = []

    def add(delta: int, why: str) -> None:
        nonlocal points
        points += delta
        reasons.append(f"{delta:+d}  {why}")

    if sec.get("is_known_attacker"):
        add(35, "Flagged as a known attacker")
    if sec.get("is_bot") and sec.get("bot_type") in ATTACK_BOTS:
        add(25, f"Attack bot activity: {sec['bot_type']}")
    elif sec.get("is_bot") and not sec.get("is_known_good_bot"):
        add(8, f"Undeclared bot ({sec.get('bot_type') or 'unknown type'})")
    if sec.get("is_tor"):
        add(15, "Tor exit node")
    if sec.get("is_spam"):
        add(12, "Associated with spam activity")
    if sec.get("is_anonymous") and not sec.get("is_tor"):
        add(10, "Anonymised connection")  # not double-counted on top of Tor
    if sec.get("is_residential_proxy"):
        add(8, "Residential proxy network")

    failures = activity.get("auth_failures", 0)
    if failures >= 5:
        add(40, f"{failures} failed or denied auth attempts")
        if failures >= 20:
            add(10, "Sustained brute force")
    if activity.get("sensitive"):
        add(30, f"{activity['sensitive']} requests to sensitive paths")
        if activity["sensitive"] >= 10:
            add(10, "Sustained scanner activity")
    hits = activity.get("hits", 0)
    if hits >= 10 and activity.get("errors", 0) / hits >= 0.5:
        add(15, "Over half of requests returned 4xx or 5xx")
    if activity.get("not_found", 0) >= 25:
        add(10, f"{activity['not_found']} x 404, looks like path enumeration")

    # The subtraction. Order doesn't matter; the fact that it happens at all does.
    if sec.get("is_known_good_bot") and not sec.get("is_known_attacker"):
        add(-45, f"Verified {sec.get('bot_operator_name') or 'good bot'}, de-prioritised")
    if sec.get("is_corporate_gateway"):
        provider = sec.get("corporate_gateway_provider_name") or "Corporate"
        add(-10, f"{provider} gateway egress, shared by many users, do not block")

    return max(0, min(100, round(points))), reasons

Run that over the four addresses from the opening table and the order inverts. The Zscaler IP with 85 hits lands at 0. The ChatGPT crawler lands at 0. The residential proxy that also carries a known-attacker and spam flag lands at 100 on reputation alone, before its behaviour is counted. The brute_force bot clears 100 as soon as its failed logins are added.

Every weight above lives in one file in the repo, which is on purpose. You will want to change them. The auth-failure weight in particular is tuned for a box that gets hammered on SSH, and if yours doesn't, 40 points is too aggressive.

Two things the snippet skips that the repo does: request rate, which needs timestamps that my regex above throws away, and the --no-trust-good-bots escape hatch for when you genuinely do want to see crawlers ranked with everything else.

Turn findings into something that acts

A ranked list you read on Tuesday is a report. A ranked list that does something is a tool.

def nginx_blocklist(findings: dict, minimum: int = 60) -> str:
    """Emit deny rules for HIGH and above. Candidates, not a deploy artifact."""
    lines = ["# generated by log triage, review before applying"]
    for ip, result in sorted(findings.items(), key=lambda kv: -kv[1]["score"]):
        if result["score"] < minimum:
            continue
        if result["security"].get("is_corporate_gateway"):
            continue  # belt and braces: never emit a shared office egress address
        top_reason = result["reasons"][0] if result["reasons"] else "no reason recorded"
        lines.append(f"deny {ip};  # {result['score']}/100 {top_reason}")
    return "\n".join(lines)

That corporate gateway check is redundant, because the -10 credit plus a low threat score usually keeps those addresses well under 60 anyway. I left it in because "usually" is doing a lot of work in that sentence, and the failure mode is locking an enterprise customer out of your product.

Past that, the useful outputs are a non-zero exit code so cron or CI can page you when something crosses a threshold, and NDJSON so your SIEM can ingest findings without a custom parser. An hourly cron entry with --fail-on high covers most of what a small team needs.

If you already run fail2ban, this isn't a fail2ban alternative and I wouldn't pitch it as one. fail2ban reacts in seconds to a pattern it already recognises, in-process, with no network call. This runs on a schedule, costs money per address, and answers a different question: out of everything that hit you yesterday, which handful deserves a human looking at it. The two compose fine. fail2ban handles the obvious, this finds the quiet 16-hit address that never tripped a threshold.

What this will not do

Worth being straight about the limits, because IP-level scoring gets oversold.

Shared addresses are a real problem, and corporate gateways are only the visible half of it. Carrier-grade NAT puts thousands of mobile users behind one address: a university, a hotel, a coffee shop: same shape. A high score on a shared address means somebody behind it is a problem, not that everyone behind it is.

Scores expire. Residential proxy pools rotate. An address that was laundering traffic last week can be a normal home connection this week, and the reverse happens just as often. Cache for a day, not a quarter, and treat a blocklist as something you regenerate rather than something you accumulate.

IPv6 changes the unit. A single /64 is one customer's entire address space. Scoring individual v6 addresses will produce a very long list of singletons and tell you nothing. You want to aggregate at the prefix.

This is triage, not prevention. It reads logs after the requests already happened. It is not a WAF, it is not rate limiting, and it does not replace either. What it gives you is a short list of addresses worth a human decision, which is the thing you don't have when your only sort key is request count.

Run it against last week's log before you wire it into anything. The first run mostly tells you how boring your traffic is, which is useful calibration, and whether your thresholds are anywhere near right for your box. Set --fail-on high, let it page you for a month, and resist auto-applying the blocklist until you've read enough of them to trust it. iplogsec is on GitHub if you want the version with format detection, the SQLite cache and the HTML report already written.

How to Detect and Handle Proxy IPs in Web Applications

Abdul Mateen — Mon, 21 Sep 2026 09:18:43 +0000

When a web application receives a request, the IP address is often one of the first pieces of information available to the server.

It is tempting to treat that address as the identity of the client.

In real-world applications, things are rarely that simple.

A request may pass through a CDN, reverse proxy, VPN, corporate gateway, residential proxy, or another intermediary before reaching your application. The IP address visible to your server may therefore represent an intermediary rather than the original user.

This creates an important engineering problem.

How do you determine whether an IP belongs to a normal network, a VPN, a proxy, a residential proxy, a cloud provider, or another type of intermediary?

And more importantly, what should your application actually do with that information?

This article walks through the problem and looks at practical approaches for using IP intelligence in web applications.

What is a proxy IP?

A proxy server sits between a client and the destination server.

A direct connection looks roughly like this:

Client → Your Server

A proxied connection looks more like this:

Client → Proxy → Your Server

Your application sees the proxy's IP address.

That does not automatically make the request malicious.

Proxies have many legitimate uses. Companies may route traffic through centralized gateways. Developers may use proxies for testing. Privacy tools may hide the originating network. Security products may inspect traffic before forwarding it.

At the same time, proxy networks are also commonly used for automated traffic, scraping, account abuse, and other activities that a security team may want to investigate.

That is why detecting a proxy should usually be treated as an intelligence problem rather than a simple block-or-allow rule.

Proxy, VPN, CDN, and corporate gateway are different

One of the first mistakes when working with IP intelligence is putting every intermediary into the same category.

Consider these examples:

Network type	Typical purpose	What your application may see
Residential proxy	Route traffic through residential IP addresses	Residential-looking exit IP
Datacenter proxy	Route traffic through hosting infrastructure	Datacenter IP
VPN	Provide an encrypted or private connection	VPN server IP
CDN	Deliver content from distributed infrastructure	CDN edge IP
Corporate gateway	Centralize enterprise traffic	Shared corporate egress IP

These categories can overlap from the perspective of a basic IP lookup, but they are not interchangeable.

A corporate gateway, for example, may represent hundreds or thousands of legitimate employees.

Blocking every address associated with a gateway could therefore cause problems for an otherwise legitimate customer.

Why checking the ASN is not enough

An Autonomous System Number, or ASN, identifies a network on the internet.

ASN information can be extremely useful.

For example, if an IP belongs to a cloud or hosting organization, that can provide context about the type of connection.

But ASN ownership does not tell you exactly how an IP is being used.

A cloud provider can host:

A public website
An API
A monitoring service
A legitimate business application
A crawler
A proxy service

The same network can therefore contain very different types of traffic.

This is why ASN information works better as one signal in a larger IP intelligence system.

The IPGeolocation API documentation includes ASN and network information alongside geolocation and other IP intelligence data.

Residential proxies make detection harder

Residential proxies are particularly difficult to identify using basic network ownership checks.

A simplified setup looks like this:

Automated Client
       |
       v
Proxy Provider
       |
       v
Residential Exit IP
       |
       v
Your Website

Your application sees the residential exit address.

If your detection system only checks whether an IP belongs to a hosting provider, the request may look like ordinary residential traffic.

This is one reason proxy detection needs signals beyond ASN classification.

The current IP Security API can identify proxy and residential proxy signals and can return proxy confidence information and provider names when available.

Look at multiple signals

A better approach is to combine several pieces of information.

For example:

                    ┌── ASN information
                    │
                    ├── Proxy detection
                    │
Incoming IP ────────┼── VPN detection
                    │
                    ├── Bot information
                    │
                    ├── Abuse information
                    │
                    └── Network ownership

Each signal answers a different question.

ASN information can help identify the network that routes the address.

Proxy detection can indicate whether the address is associated with proxy infrastructure.

VPN detection can identify known VPN networks.

Bot signals can provide additional context about automated traffic.

Threat intelligence can indicate whether the address has been associated with suspicious activity.

The result is much more useful than a single boolean such as:

{
  "is_proxy": true
}

What about X-Forwarded-For?

There is another problem that developers encounter when implementing IP detection.

Your application may not directly receive the client's connection.

For example:

Internet
   |
   v
Load Balancer
   |
   v
Reverse Proxy
   |
   v
Application

The application server may see the reverse proxy's IP instead of the original client IP.

Infrastructure may therefore add forwarding information such as:

X-Forwarded-For: 203.0.113.42

This can be useful, but it should not be blindly trusted.

A client can potentially send its own X-Forwarded-For header.

For example:

X-Forwarded-For: 1.2.3.4

That does not prove that the request originated from 1.2.3.4.

The safer approach is to trust forwarded IP information only from infrastructure that you control or explicitly trust.

Trusted proxy configuration matters

Consider this architecture:

Internet
   |
   v
Trusted Load Balancer
   |
   v
Reverse Proxy
   |
   v
Application

Your application can be configured to recognize the load balancer and reverse proxy as trusted intermediaries.

Only then should forwarding headers be used to determine the client IP.

This is an infrastructure concern as much as it is an application concern.

If the trust boundary is configured incorrectly, an application may make security decisions based on an IP address supplied by the requester.

Do not make proxy detection a binary security rule

Suppose a login system has this rule:

if proxy:
    deny

It looks simple.

It is also likely to create legitimate problems.

A user might be connected through a corporate network.

Another user might use a privacy service.

A business customer might route all employees through a shared security gateway.

A proxy signal alone does not tell you why the proxy is being used.

A more flexible architecture looks like this:

IP Intelligence
      +
Account History
      +
Request Behavior
      +
Authentication Signals
      +
Rate Limiting
      ↓
Risk Assessment

The IP classification becomes one input rather than the entire decision.

Using a threat score

A threat score can make this approach easier to implement.

Instead of receiving only:

{
  "is_proxy": true
}

a security API can provide additional context.

The IPGeolocation IP Security API provides a threat score from 0 to 100 along with individual security signals such as VPN, proxy, residential proxy, Tor, bot, spam, known attacker, and cloud provider indicators.

A response can therefore be evaluated using multiple fields:

{
  "security": {
    "threat_score": 72,
    "is_proxy": true,
    "is_vpn": false,
    "is_tor": false,
    "is_known_attacker": false
  }
}

Your application can then define its own response to those signals.

For example, it might flag an account for additional verification instead of immediately blocking it.

The appropriate threshold depends on the application and the consequences of a false positive.

Rate limiting is another useful example

Consider an API that limits requests by IP address.

A basic implementation might maintain:

203.0.113.10 → 100 requests/minute

This works reasonably well when each client has its own public IP.

Now consider a corporate gateway:

User A ─┐
User B ─┤
User C ─┼── Corporate Gateway ──→ API
User D ─┤
User E ─┘

All five users may appear to originate from the same IP.

If you blindly apply a per-IP limit, one customer could consume the entire quota for everyone behind that gateway.

The opposite problem can occur with rotating proxies.

An automated client can potentially change its apparent IP address frequently, making a simple per-IP rate limit less effective.

IP classification can therefore help your application understand the network context before applying a rate-limiting strategy.

IP intelligence can improve observability

Proxy detection is not only useful for blocking traffic.

It can also make application logs more useful.

Imagine your analytics system suddenly reports a large increase in traffic from a particular country.

That does not necessarily mean there are suddenly more real users from that location.

The traffic could be coming from:

A crawler
A proxy network
A security scanner
A cloud workload
A monitoring service
A CDN

Adding network classification to your logs provides additional context.

For example:

timestamp
ip
country
asn
organization
network_type
proxy_status
vpn_status
bot_status
request_path
user_agent

When an unusual traffic pattern appears, those fields can help explain what happened.

Using an IP security API

If maintaining your own IP intelligence database is not practical, an API can provide the classification data as part of your application's request flow.

For example, the IP Security API documentation provides a dedicated /v3/security endpoint for security lookups. It supports individual IP lookups as well as bulk lookups.

A simplified architecture looks like this:

Incoming Request
       |
       v
Extract Client IP
       |
       v
IP Security Lookup
       |
       +---- Proxy
       |
       +---- VPN
       |
       +---- Tor
       |
       +---- Bot
       |
       +---- Threat Score
       |
       v
Application Rules

The API response should not automatically determine the final action.

Your application should decide what those signals mean in the context of the particular workflow.

Combine geolocation and security data when needed

Security information is often more useful when combined with location and network information.

For example, an application might need to know:

Where is this IP registered?
Who operates the network?
Is it a proxy?
Is it a VPN?
Is it a cloud provider?
Is it associated with suspicious activity?

The IP Geolocation API can provide location information for IPv4 and IPv6 addresses, while security information can be requested when the application needs additional risk signals.

This allows an application to keep the data it needs in a single IP intelligence workflow.

For example:

IP
 |
 +-- Location
 |     +-- Country
 |     +-- City
 |     +-- Coordinates
 |
 +-- Network
 |     +-- ASN
 |     +-- Organization
 |
 +-- Security
       +-- Proxy
       +-- VPN
       +-- Bot
       +-- Threat Score

Cache results where appropriate

There is another practical consideration when using an external API.

You may not need to perform a fresh lookup every time the same IP appears.

Imagine your application receives:

10,000 requests

from the same IP within a short period.

Making 10,000 identical intelligence requests may add unnecessary latency and API usage.

A cache can change the flow:

Incoming IP
     |
     v
Cache Lookup
     |
   Found
     |
     v
Use Cached Data

If the IP is not cached:

Incoming IP
     |
     v
Cache Lookup
     |
   Not Found
     |
     v
API Lookup
     |
     v
Store Result
     |
     v
Use Result

The appropriate cache duration depends on the application.

A security-sensitive workflow may require fresher information than an analytics dashboard.

Do not assume every classification is permanent

IP ownership and network behavior can change.

An address can move between providers.

A network can change how it is used.

A proxy service can add or remove addresses.

A previously ordinary address can later become part of infrastructure used for automated traffic.

For this reason, IP intelligence should be treated as time-sensitive information rather than permanent identity data.

Some security systems provide last-seen information for proxy and VPN signals. IPGeolocation's security response, for example, includes fields such as proxy_last_seen and vpn_last_seen when that information is available.

That context can be useful when investigating an IP that changes classification over time.

False positives are unavoidable

No IP classification system should be treated as perfect.

A legitimate user can be behind a VPN.

A corporate gateway can represent hundreds of employees.

A cloud provider can host completely legitimate applications.

A residential network can be involved in proxy infrastructure.

This is why a system that immediately blocks every IP matching one signal can create unnecessary friction.

A better design is to define actions around the confidence and context of the detection.

For example:

Low concern
    ↓
Allow

Some risk
    ↓
Monitor / rate limit

Higher risk
    ↓
Additional verification

Confirmed abuse
    ↓
Block / investigate

The exact rules should be based on the application's risk tolerance.

IP addresses are not user identities

This is perhaps the most important concept when building IP-based security systems.

An IP address can represent:

One device
Multiple devices
An entire office
A mobile network
A cloud server
A VPN endpoint
A proxy exit node
A CDN edge
A corporate gateway

Two users can share an IP.

One user can appear behind several IP addresses.

An IP address can also change over time.

Therefore, IP intelligence is most useful as a signal about a connection or network, not as a permanent identity for a person.

A practical architecture

For an application that needs IP intelligence, the architecture can remain relatively simple:

                     Incoming Request
                            |
                            v
                    Trusted Proxy Check
                            |
                            v
                     Extract Client IP
                            |
                            v
                      IP Intelligence
                            |
             ┌──────────────┼──────────────┐
             |              |              |
             v              v              v
         Location        Network        Security
             |              |              |
             └──────────────┼──────────────┘
                            |
                            v
                     Application Rules
                            |
                            v
                         Logging

The important design choice is keeping IP intelligence separate from application rules.

Your application can then change its policy without replacing the underlying IP intelligence system.

For example, the same data could initially be used for analytics and rate limiting. Later, it could become one signal in a fraud detection workflow.

When should you use a dedicated security lookup?

A dedicated security lookup makes sense when the application primarily needs threat intelligence.

For example:

Is this IP a proxy?
Is this IP a VPN?
Is this IP a Tor exit node?
Is this IP associated with a bot?
Is this IP a known attacker?
What is its threat score?

The dedicated IP Security API is designed around these types of questions.

If your application also needs location, ASN, company, timezone, or other IP information, the broader IP Geolocation API can provide those additional modules.

There is also a Real-Time Proxy and VPN Detection API designed for client-side detection at points such as signup, login, and checkout. Its response separates public IP information from the live VPN or proxy verdict and can include additional information about the visitor's actual location.

Final thoughts

Detecting proxy IPs is more complicated than checking whether an address belongs to a hosting provider.

Modern web traffic can pass through several layers before reaching an application.

CDNs, reverse proxies, VPNs, corporate gateways, cloud infrastructure, and residential proxy networks can all change what your server sees.

A practical implementation therefore starts with a few principles:

Understand your proxy and forwarding architecture.
Trust forwarding headers only from known infrastructure.
Use ASN ownership as a signal rather than a final conclusion.
Distinguish proxies, VPNs, corporate gateways, and cloud networks.
Combine IP intelligence with application-level signals.
Cache results when the use case allows it.
Consider confidence and freshness when making decisions.
Avoid treating an IP address as a user identity.

The goal is not to determine whether every IP is "good" or "bad."

The goal is to understand the network behind a request well enough to make a better application decision.

That distinction becomes increasingly important as more legitimate users and automated systems operate through intermediary networks.

Non-Geolocatable IP Ranges: Full Table and Fix Code

Abdul Mateen — Tue, 28 Jul 2026 09:08:32 +0000

Why Your IP Lookup Returns Nothing: A Range Reference

An IP geolocation lookup returns nothing for four different reasons, and most code only handles one of them.

Private ranges are the obvious case. Everyone remembers 192.168.0.0/16. The other three catch people out: address space no registry has handed out yet, space that was handed out but nobody is announcing, and addresses that resolve cleanly to a place that has nothing to do with your user.

That last one is the expensive one. It doesn't look like a failure. It looks like data.

TL;DR

Four distinct failure modes, and only one is private address space.
The IANA special-purpose registries are the authoritative list, and they publish a Globally Reachable column that answers "will this ever geolocate" directly.
Full IPv4 and IPv6 tables below, including 3fff::/20 (July 2024) and 5f00::/16 (April 2024), which most reference pages predate.
APIs signal this either through a status code or a response field. Check which one yours does before you write the branch.
Filtering locally costs nothing and skips the round trip. Tested Python and Node at the end.

A lookup that comes back empty is usually correct, not broken. The address genuinely has no location. What you do about it depends on which of the four cases you hit, and telling them apart takes about fifteen lines of code plus one table you can bookmark.

Four reasons a lookup comes back empty

These are not variations on a theme. They need different handling, and two of them are invisible in your logs unless you go looking.

Case	What happened	Will it ever resolve?	Your move
Special-purpose range	Private, loopback, CGNAT, documentation, reserved	No, by design	Filter before the call
Unallocated	No registry has assigned the block	Not today, maybe later	Cache the miss, retry rarely
Allocated, not routed	Assigned to an org, no BGP announcement	Possibly, if it gets announced	Same as unallocated
Resolves, but wrong	Shared or carrier address returns a real location	It already did, and misled you	Weight it lower, don't trust city

The first case is a lookup you should never have made. The middle two are honest gaps in global routing data. The fourth one is the one that quietly corrupts fraud rules and analytics, because the API did its job and the answer is still useless.

The ranges that can never be geolocated

Both tables come from the IANA IPv4 Special-Purpose Address Registry and its IPv6 counterpart. If you only remember one thing from this article, remember that those registries carry a Globally Reachable column. Every block below has it set to false, and that single boolean is a better predictor than any vendor's list.

IPv4 special-purpose ranges

The "why it reaches you" column matters more than the range itself. Knowing that 169.254.0.0/16 exists is trivia. Knowing that it shows up because a DHCP lease failed, or because something is hitting the cloud metadata endpoint, is actionable.

Range	Name (RFC)	Why it reaches your logs
`0.0.0.0/8`	This network (RFC 791)	Misconfigured client, DHCP before assignment
`10.0.0.0/8`	Private-Use (RFC 1918)	Internal traffic, or a missing `X-Forwarded-For`
`100.64.0.0/10`	Shared Address Space (RFC 6598)	Carrier-grade NAT, mobile and fixed ISP subscribers
`127.0.0.0/8`	Loopback (RFC 1122)	Local dev, health checks, same-host reverse proxy
`169.254.0.0/16`	Link Local (RFC 3927)	DHCP failure, cloud metadata at `169.254.169.254`
`172.16.0.0/12`	Private-Use (RFC 1918)	Docker bridge networks live here by default
`192.0.0.0/24`	IETF Protocol Assignments (RFC 6890)	NAT64 discovery, protocol machinery
`192.0.2.0/24`	Documentation, TEST-NET-1 (RFC 5737)	Someone copied an example from a tutorial
`192.168.0.0/16`	Private-Use (RFC 1918)	Home and small office LANs
`198.18.0.0/15`	Benchmarking (RFC 2544)	Load generators and network test rigs
`198.51.100.0/24`	Documentation, TEST-NET-2 (RFC 5737)	Same as TEST-NET-1
`203.0.113.0/24`	Documentation, TEST-NET-3 (RFC 5737)	Same as TEST-NET-1
`224.0.0.0/4`	Multicast (RFC 5771)	Malformed source, or something badly wrong
`240.0.0.0/4`	Reserved (RFC 1112)	Reserved since 1989 and still unused
`255.255.255.255/32`	Limited Broadcast (RFC 919, RFC 8190)	Broadcast leaking into an application log

Pitfall: the documentation ranges are worth flagging to your team. 203.0.113.45 in a bug report almost always means someone pasted an example instead of a real address, and every API on the market will reject it.

IPv6 special-purpose ranges

IPv6 is where reference pages go stale, because the registry keeps growing. Two blocks below were allocated in 2024 and are missing from most published bogon lists.

3fff::/20 is the one to know. RFC 9637 registered it as a documentation prefix in July 2024, expanding what 2001:db8::/32 used to cover alone. If you are validating IPv6 input against a list you copied from somewhere in 2023, 3fff::/20 is a hole in it.

Range	Name (RFC)
`::/128`	Unspecified Address (RFC 4291)
`::1/128`	Loopback (RFC 4291)
`::ffff:0:0/96`	IPv4-mapped Address (RFC 4291)
`100::/64`	Discard-Only Address Block (RFC 6666)
`100:0:0:1::/64`	Dummy IPv6 Prefix (RFC 9780, April 2025)
`2001:2::/48`	Benchmarking (RFC 5180)
`2001:20::/28`	ORCHIDv2 (RFC 7343)
`2001:db8::/32`	Documentation (RFC 3849)
`3fff::/20`	Documentation (RFC 9637, July 2024)
`5f00::/16`	Segment Routing SRv6 SIDs (RFC 9602, April 2024)
`fc00::/7`	Unique-Local (RFC 4193, RFC 8190)
`fe80::/10`	Link-Local Unicast (RFC 4291)

Two entries you may have in an older list should come out. 2001:10::/28 was ORCHID and was deprecated in March 2014, replaced by 2001:20::/28. And fec0::/10 site-local is gone entirely, not merely deprecated. It is no longer in the registry at all.

The 6to4 range people miss

2002::/16 (RFC 3056) embeds an IPv4 address inside an IPv6 one, so a 6to4 address wrapping a private IPv4 range is non-routable even though the outer prefix looks ordinary. 2002:a00::/24 is 10.0.0.0/8 in disguise. Rare in 2026, still worth a line in your filter if you handle tunnel traffic.

What the API sends back instead

Here is the part no reference page covers, and the reason I wrote this: the ranges are easy to find, but what your provider actually does when you send one is not documented anywhere consistently.

Status code or response field

There are two designs in the wild, and they need different code.

IPinfo returns HTTP 200 with a bogon field set to true, so you branch on the payload. IPGeolocation returns 423 Locked with a message body and no location object, so you branch on the status code. Both are reasonable. Neither is guessable, and getting it wrong means your handler never fires.

If you are on the status-code design, the body looks like this:

{
  "message": "'10.0.0.0' is a bogon IP address."
}

Being blunt about a limitation here, since I work on one of these: there is no is_bogon boolean in the successful response on our side. The signal is the 423. If you were hoping to check one field on a 200 and be done, that works with IPinfo's shape and not with ours.

For contrast, a successful lookup on the same endpoint returns this, on the free plan, with no include parameters:

{
  "ip": "91.128.103.196",
  "location": {
    "continent_code": "EU",
    "continent_name": "Europe",
    "country_code2": "SE",
    "country_code3": "SWE",
    "country_name": "Sweden",
    "country_name_official": "Kingdom of Sweden",
    "country_capital": "Stockholm",
    "state_prov": "Stockholms län",
    "state_code": "SE-AB",
    "district": "Stockholm",
    "city": "Stockholm",
    "zipcode": "164 40",
    "latitude": "59.40510",
    "longitude": "17.95510",
    "is_eu": true,
    "country_flag": "https://ipgeolocation.io/static/flags/se_64.png",
    "geoname_id": "9972319",
    "country_emoji": "<SE flag emoji>"
  },
  "country_metadata": {
    "calling_code": "+46",
    "tld": ".se",
    "languages": ["sv-SE", "se", "sma", "fi-SE"]
  },
  "currency": { "code": "SEK", "name": "Swedish Krona", "symbol": "kr" },
  "asn": {
    "as_number": "AS1257",
    "organization": "Tele2 Sverige AB",
    "country": "SE"
  },
  "time_zone": {
    "name": "Europe/Stockholm",
    "offset": 1,
    "offset_with_dst": 1,
    "current_time": "2026-03-07 10:37:38.987+0100",
    "current_time_unix": 1772876258.987,
    "current_tz_abbreviation": "CET",
    "current_tz_full_name": "Central European Standard Time",
    "standard_tz_abbreviation": "CET",
    "standard_tz_full_name": "Central European Standard Time",
    "is_dst": false,
    "dst_savings": 0,
    "dst_exists": true,
    "dst_tz_abbreviation": "CEST",
    "dst_tz_full_name": "Central European Summer Time",
    "dst_start": {
      "utc_time": "2026-03-29 TIME 01:00",
      "duration": "+1.00H",
      "gap": true,
      "date_time_after": "2026-03-29 TIME 03:00",
      "date_time_before": "2026-03-29 TIME 02:00",
      "overlap": false
    },
    "dst_end": {
      "utc_time": "2026-10-25 TIME 01:00",
      "duration": "-1.00H",
      "gap": false,
      "date_time_after": "2026-10-25 TIME 02:00",
      "date_time_before": "2026-10-25 TIME 03:00",
      "overlap": true
    }
  }
}

Two type traps in there that will bite you. latitude and longitude are strings, not numbers, so anything doing arithmetic needs a cast. And as_number carries the AS prefix as part of the string, so AS1257 rather than 1257.

What a rejected lookup costs you

Nothing, which is the useful part. Private, bogon, and malformed addresses are not counted as valid IPs, so they do not consume credits. That rule applies to both the single and bulk endpoints, per the documented status codes and credit rules.

Every response carries an X-Credits-Charged header, and that header is the billing source of truth rather than your own arithmetic. Base lookups cost 1 credit, adding security costs 2 more for a total of 3, and adding abuse contact data costs 1 more.

That makes the API safe to use as a validation layer if you want to. I still wouldn't. A network round trip to learn that 192.168.1.1 is private is a round trip you can skip with a local check, and the latency is the cost that matters, not the credit.

Bulk lookups return a mixed array

This one is a genuine footgun. Post three addresses where one is private, and the array you get back is not homogeneous:

[
  { "message": "'10.0.0.0' is a bogon IP address." },
  { "ip": "91.128.103.196", "location": { "country_code2": "SE" } },
  { "ip": "107.161.145.198", "location": { "country_code2": "US" } }
]

Index 0 has no ip key and no location object. Any code that maps over the response reaching for entry.location.country_code2 throws on the first element. There is also an X-Successful-Record header that appears only when the batch contained something invalid, telling you how many entries actually returned data.

Allocated, but nobody is announcing it

Two more classes of empty response have nothing to do with reserved ranges, and they are why you cannot solve this problem with a filter alone.

An address can sit in space that no regional registry has assigned yet. IPv4 has very little of this left after exhaustion, but IPv6 has enormous unallocated regions and will for decades.

More common: the block is allocated to a real organization, and no autonomous system is announcing a route to it. Geolocation providers lean on BGP data to place addresses, so an unannounced prefix has nothing to place. The address is real, owned, and invisible.

Both cases return a normal empty result rather than an error, because nothing is wrong with the request. Cache the miss for a day or two and move on. Retrying in a tight loop will not conjure a route, and if the prefix does get announced next month your cache expiry will pick it up on its own.

CGNAT is the one that actually costs you money

The other three cases fail loudly. This one succeeds and hands you a plausible answer, which is worse.

When a subscriber sits behind carrier-grade NAT, their device holds an address in 100.64.0.0/10, the shared space RFC 6598 set aside for exactly this. That address never reaches your server, so you will rarely see it in production logs. What reaches you is the carrier's shared public address, and that geolocates perfectly well: real country, real city, real coordinates. The country is usually right. The city is the carrier's aggregation point, which can be several hundred kilometres from the person.

Cloudflare's engineering team documented the scale of this in October 2025, noting that a single IPv4 address can now represent hundreds or thousands of users, and that security mechanisms treating an address as one accountable entity cause collateral damage as a result. Their detection approach relies on traceroute analysis spotting a 100.64.0.0/10 hop between the customer router and the public address, which tells you how much work it takes to identify from the outside.

The practical consequence: any rule that blocks, rate-limits, or scores an IP is aimed at a group, not a person. On mobile carriers that group can be a city.

My take, and this is where I'd push back on how most teams use this data: city-level geolocation deserves to be an input with a confidence weight, never a gate. Country level is dependable enough to act on. City level on mobile traffic is a hint. If your fraud rules escalate on a city mismatch, you are flagging commuters and mobile users, and you will not see it in your metrics because the false positives look exactly like caught fraud.

Filter before you call

Every block in those tables is knowable locally. Checking costs microseconds and saves a round trip.

Python

The standard library already knows most of this. Two gaps it does not.

import ipaddress
import os

import requests

# Blocks the stdlib does not classify yet. Both were allocated after
# Python 3.12's tables were written. Verified against 3.12.3.
_STDLIB_GAPS = [
    ipaddress.ip_network("3fff::/20"),  # Documentation, RFC 9637
    ipaddress.ip_network("5f00::/16"),  # SRv6 SIDs, RFC 9602
]


def is_lookupable(raw_ip):
    try:
        addr = ipaddress.ip_address(raw_ip)
    except ValueError:
        return False  # malformed input, not an address at all

    # is_global alone is not enough. Multicast reports is_global True,
    # and 100.64.0.0/10 reports False for both is_global and is_private,
    # so a filter written only on is_private lets CGNAT through.
    if not addr.is_global or addr.is_multicast or addr.is_reserved:
        return False

    return not any(addr in net for net in _STDLIB_GAPS)


def geolocate(raw_ip):
    if not is_lookupable(raw_ip):
        return None

    api_key = os.environ.get("IPGEO_API_KEY")
    if not api_key:
        raise RuntimeError("IPGEO_API_KEY is not set")

    try:
        response = requests.get(
            "https://api.ipgeolocation.io/v3/ipgeo",
            params={"apiKey": api_key, "ip": raw_ip, "fields": "location"},
            timeout=(1.0, 1.5),
        )
    except requests.RequestException as exc:
        # Fail open. A geolocation miss must never block the request.
        print(f"geolocation lookup failed for {raw_ip}: {exc}")
        return None

    if response.status_code == 423:
        return None  # bogon or private, and it cost no credits
    if response.status_code != 200:
        print(f"unexpected geolocation status {response.status_code}")
        return None

    location = response.json().get("location") or {}
    latitude = location.get("latitude")
    return {
        "country": location.get("country_code2"),
        # Coordinates arrive as strings, so cast before any arithmetic.
        "latitude": float(latitude) if latitude else None,
    }

That filter passes all 26 addresses I tested it against, including boundary cases either side of each block. The is_global and is_private asymmetry around 100.64.0.0/10 is the part I'd flag to anyone reviewing this kind of code, because it reads correct and isn't.

Node

No standard library equivalent exists, so IPv4 needs bit math. One line in it is load-bearing and easy to get wrong.

import net from 'node:net';

const toInt = (ip) =>
  ip.split('.').reduce((acc, octet) => ((acc << 8) >>> 0) + Number(octet), 0) >>> 0;

const BLOCKED_V4 = [
  '0.0.0.0/8', '10.0.0.0/8', '100.64.0.0/10', '127.0.0.0/8',
  '169.254.0.0/16', '172.16.0.0/12', '192.0.0.0/24', '192.0.2.0/24',
  '192.168.0.0/16', '198.18.0.0/15', '198.51.100.0/24', '203.0.113.0/24',
  '224.0.0.0/4', '240.0.0.0/4', '255.255.255.255/32',
].map((cidr) => {
  const [base, bits] = cidr.split('/');
  const prefix = Number(bits);
  const mask = (0xffffffff << (32 - prefix)) >>> 0;
  // The >>> 0 here is not decoration. JS bitwise ops work on signed int32,
  // so every network above 127.255.255.255 comes back negative and silently
  // never matches. Dropping it breaks 11 of the 15 blocks above.
  return { network: (toInt(base) & mask) >>> 0, mask };
});

export function isLookupable(raw) {
  const version = net.isIP(raw);
  if (version === 0) return false;
  // Hand-rolled IPv6 prefix matching is a bug factory. Reach for ipaddr.js
  // if your traffic is v6-heavy; this path deliberately declines to guess.
  if (version === 6) return false;

  const value = toInt(raw);
  return !BLOCKED_V4.some(({ network, mask }) => ((value & mask) >>> 0) === network);
}

export async function geolocate(raw) {
  if (!isLookupable(raw)) return null;

  const apiKey = process.env.IPGEO_API_KEY;
  if (!apiKey) throw new Error('IPGEO_API_KEY is not set');

  const url = new URL('https://api.ipgeolocation.io/v3/ipgeo');
  url.searchParams.set('apiKey', apiKey);
  url.searchParams.set('ip', raw);
  url.searchParams.set('fields', 'location');

  try {
    // 1.5s ceiling. Enrichment should never hold a request open longer.
    const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
    if (res.status === 423) return null;   // bogon or private, no credit spent
    if (!res.ok) {
      console.warn(`unexpected geolocation status ${res.status}`);
      return null;
    }
    const body = await res.json();
    const lat = body?.location?.latitude;
    return {
      country: body?.location?.country_code2 ?? null,
      latitude: lat ? Number.parseFloat(lat) : null,
    };
  } catch (err) {
    // Fail open, including on the timeout abort.
    console.warn(`geolocation lookup failed for ${raw}: ${err.message}`);
    return null;
  }
}

I shipped that comment because I wrote the bug first. The missing >>> 0 made every block above 127.255.255.255 fail to match, which meant 192.168.1.1 sailed through as lookupable and the tests were the only thing that caught it.

A curl sanity check

# Expect 423. Anything else means the range handling changed.
curl -s -o /dev/null -w '%{http_code}\n' \
  "https://api.ipgeolocation.io/v3/ipgeo?apiKey=${IPGEO_API_KEY}&ip=10.0.0.1"

Put that in a smoke test if you depend on the status-code branch.

Fail open, not closed

When a lookup returns nothing, the request still has to be served.

Fail open by default: treat the location as unknown and let the user through. Geolocation is enrichment, and enrichment failing should never take down a signup flow. The exception is a rule that legally requires a known jurisdiction, such as gambling or regulated financial access, where unknown has to mean blocked. Decide that explicitly rather than inheriting it from a timeout.

Log the reason, not just the miss. "No location for 10.0.0.1" and "no location for 45.83.122.7" look identical in a dashboard and mean completely different things: one is a proxy configuration bug, the other is a routing gap. Store which of the four cases you hit and the difference becomes visible.

A few extra notes

If your X-Forwarded-For handling is producing private addresses, the filter is treating a symptom. Check your trust-proxy configuration first, because seeing 10.x.x.x at the application layer usually means you are reading the wrong hop rather than that your users are internal.

The IPv4 special-purpose list is effectively frozen now that allocation has run out, so a hardcoded IPv4 table will stay accurate. IPv6 is the opposite. Two blocks landed in 2024 and another in 2025, so pin your source to the IANA registry and re-check it once or twice a year rather than trusting a list you copied.

For logs, store the raw address alongside the enriched result. Re-running enrichment later is cheap when the input survived, and prefixes that were unrouted last quarter are sometimes announced this quarter.

Start by filtering the fifteen IPv4 blocks locally, since that removes the majority of pointless calls for a few microseconds of work. Then decide what unknown means in your specific flow, and write that decision down somewhere your future self will find it. If you are picking a provider, the question to ask is not which ranges they reject but how they tell you: a status code and a response field lead to genuinely different error handling, and finding out after you have written the handler is annoying.

VPN & Proxy Detection for Online Games (Node.js Guide)

Abdul Mateen — Wed, 15 Jul 2026 12:15:03 +0000

Detecting VPN and proxy players in an online game comes down to one uncomfortable fact: your server only ever sees an IP address. Not an account's real country, not the payment card's region, not whether the person behind it is sitting where they claim. Just an IP, and whatever you can infer from it.

That gap is worth money. Global games revenue crossed $200 billion in 2025 (Newzoo, up 9.1% year over year), and a real slice of that turns on regional pricing, staggered launches, and licensing that VPNs quietly route around. Add ranked lobbies degraded by region-hoppers and banned accounts coming back on a fresh IP, and detection stops being optional.

TL;DR

The server only sees an IP. IP intelligence turns that into VPN, proxy, Tor, and relay flags plus a 0 to 100 threat score.

It catches commercial VPNs and datacenter traffic well, catches residential proxies partially, and cannot see account or store region at all.

Check at login, matchmaking, and purchase. Not per frame. Cache the result briefly.

Do not treat iCloud Private Relay as a VPN. That punishes legitimate Apple and mobile players.

Fail open for gameplay so an API blip never locks out paying players. Fail closed only for purchases.

IP-based detection is one strong layer, not the whole answer. This walks through the Node.js you would actually ship for it, and it is honest about the cases where the IP tells you nothing useful.

What region-hoppers actually bypass

There are three separate things players evade, and they need different defenses.

The first is the storefront region: buying a game or edition cheaper by switching a Steam, PSN, or Xbox marketplace country, often with a matching billing address. The second is the game region or matchmaking pool: connecting to EU servers from another continent to squad up with friends, which quietly wrecks ping for everyone else in the match. The third is ban evasion: a banned account returning on a new IP.

IP data touches the second and third directly. It touches the first barely, because store region is usually tied to account and payment, not the IP at checkout. Knowing which problem you are solving keeps you from expecting the IP to fix something it never could.

What IP data catches, and what it can't

Be clear-eyed about this before you write a line of code, because overselling it is how you end up hard-blocking innocent players.

IP intelligence is strong on commercial VPNs and datacenter traffic. Those exit nodes live on known hosting ranges, get enumerated continuously, and often come with a provider name attached. If someone routes through a popular VPN, you will usually know, and you will frequently know which one.

It is partial on residential and mobile proxies. Those route through real consumer ISP connections, so the underlying IP looks like a normal home or carrier address. Good providers flag a meaningful share of them through behavioral signals and honeypot data, but nobody catches all of it, and the gap widens as proxy networks get better. Treat a clean residential result as "probably fine," not "definitely a real local player."

And it is blind to a whole category. The IP cannot tell you the account's store region, the billing country, or that a player borrowed a friend's home connection in the target country. If the enforcement problem lives at the account or payment layer, IP data is the wrong tool and no amount of code changes that.

So the honest framing: use IP signals to raise or lower confidence and add friction, and pair them with account age, payment region, and device signals for anything that actually costs the player something.

Reading the VPN and proxy signals in Node.js

The mechanics are simple. Send the player's IP to an IP intelligence endpoint, read the flags, decide what to do. The parts that separate a shipped feature from a snippet are the timeout, the fallback, the header handling, and knowing which flag means what.

I'll use ipgeolocation.io's IP Security API for the examples because a single call returns location and the full security object together, which is exactly what a region-plus-VPN check needs. Sign up for a key, or swap in whatever you already run. IPGeolocation, IPQualityScore, proxycheck, vpnapi, and MaxMind all return roughly the same shape; pick on residential-proxy coverage, whether you get provider names, and pricing model. Set the key as an environment variable, never inline.

The call, and the full response

Here is the raw request. Security data rides the unified endpoint with include=security, so one call gets you both region and risk. Note the API key travels in the query string, so keep full request URLs out of your logs.

curl -G 'https://api.ipgeolocation.io/v3/ipgeo' \
  --data-urlencode "apiKey=$IPGEO_API_KEY" \
  --data-urlencode 'ip=2.56.188.34' \
  --data-urlencode 'include=security'

The response nests everything under typed objects. location gives you country and region, asn tells you who owns the network, and security carries the anonymizer signals. This is the complete security object, not a trimmed version, because the provider names, confidence scores, and last-seen dates are the parts that make a real enforcement decision possible.

{
  "ip": "2.56.188.34",
  "location": {
    "country_code2": "NL",
    "country_name": "Netherlands",
    "state_prov": "North Holland",
    "city": "Amsterdam",
    "latitude": "52.37403",
    "longitude": "4.88969",
    "is_eu": true
  },
  "asn": {
    "as_number": "AS9009",
    "organization": "M247 Europe SRL",
    "type": "HOSTING"
  },
  "security": {
    "threat_score": 78,
    "is_vpn": true,
    "vpn_provider_names": ["NordVPN"],
    "vpn_confidence_score": 90,
    "vpn_last_seen": "2026-07-13",
    "is_proxy": false,
    "proxy_provider_names": [],
    "proxy_confidence_score": 0,
    "proxy_last_seen": null,
    "is_tor": false,
    "is_anonymous": true,
    "is_residential_proxy": false,
    "is_known_attacker": false,
    "is_bot": false,
    "is_spam": false,
    "is_relay": false,
    "relay_provider_name": null,
    "is_cloud_provider": true,
    "cloud_provider_name": "M247"
  }
}

Two fields do most of the work for games. asn.type returning HOSTING is a strong tell on its own, because home players do not connect from datacenter ranges. And is_relay, which you will meet again below, is the one flag people misread most often.

A lookup with a timeout and a fallback

Wrap the call so a slow or failed API never blocks a login. Node 18+ ships a global fetch, so there are no dependencies here beyond the runtime.

// ip-intel.js
// One lookup, hard timeout, and a safe shape on failure.

const IPGEO_URL = "https://api.ipgeolocation.io/v3/ipgeo";

export async function lookupIp(ip) {
  const key = process.env.IPGEO_API_KEY;
  if (!key || !ip) return null; // No key or no IP: caller decides what to do.

  const params = new URLSearchParams({ apiKey: key, ip, include: "security" });

  try {
    const res = await fetch(`${IPGEO_URL}?${params}`, {
      // 1.5s ceiling. A login flow cannot wait on a slow network call.
      signal: AbortSignal.timeout(1500),
    });

    if (!res.ok) {
      // 401 usually means the security module is not on your plan.
      console.error(`ip lookup failed: HTTP ${res.status}`);
      return null;
    }

    const data = await res.json();
    const sec = data.security ?? {};

    return {
      country: data.location?.country_code2 ?? null,
      asnType: data.asn?.type ?? null,
      // threat_score can serialize as a number or a numeric string. Coerce once.
      threatScore: Number(sec.threat_score ?? 0),
      isVpn: sec.is_vpn === true,
      isProxy: sec.is_proxy === true,
      isResidentialProxy: sec.is_residential_proxy === true,
      isTor: sec.is_tor === true,
      isRelay: sec.is_relay === true,
      vpnProvider: sec.vpn_provider_names?.[0] ?? null,
    };
  } catch (err) {
    // Timeout or network error. Return null and let the caller fail open.
    console.error(`ip lookup error: ${err.name}`);
    return null;
  }
}

The null return is deliberate. The lookup does not decide policy; it reports what it found or admits it found nothing, and the caller chooses how to react. That separation is what lets you fail open in one place and fail closed in another.

Login and matchmaking middleware

Now the part Greip-style guides describe but rarely show: a real Express middleware. The trap here is the client IP. Behind a load balancer or CDN, req.socket.remoteAddress is the proxy, not the player, and reading x-forwarded-for blindly lets a client spoof whatever IP it wants. Configure trust proxy for your actual hop count or trusted subnet, then read req.ip.

// server.js
import express from "express";
import { lookupIp } from "./ip-intel.js";

const app = express();

// Set this to your real infrastructure: the number of proxies in front of
// the app, or the trusted subnet. Blindly trusting all forwarded headers is
// how attackers feed you a fake IP.
app.set("trust proxy", 1);

async function checkConnection(req, res, next) {
  const intel = await lookupIp(req.ip);

  // Fail OPEN for gameplay. An API blip must not lock out paying players.
  // Log it so a sustained outage is visible, then let them through.
  if (!intel) {
    console.warn(`ip intel unavailable for ${req.ip}; allowing`);
    req.playerRisk = { level: "unknown", reason: "lookup_failed" };
    return next();
  }

  // Datacenter or a flagged VPN/proxy is the high-signal case for games.
  const anonymized =
    intel.isVpn || intel.isProxy || intel.isResidentialProxy ||
    intel.isTor || intel.asnType === "HOSTING";

  req.playerRisk = {
    level: intel.threatScore >= 45 || anonymized ? "elevated" : "normal",
    score: intel.threatScore,
    country: intel.country,
    vpnProvider: intel.vpnProvider,
    isRelay: intel.isRelay,
  };

  next();
}

// Attach to the routes where a check is worth the latency: login,
// matchmaking, store. Never on a per-frame or per-tick path.
app.post("/login", checkConnection, (req, res) => {
  // Read req.playerRisk downstream to route the session. See enforcement below.
  res.json({ ok: true, risk: req.playerRisk.level });
});

app.listen(3000);

Two calls, one middleware, and the risk verdict rides along on the request for the route handler to act on. Notice there is no hard block in here. That decision belongs in enforcement, where it can differ by action.

Why iCloud Private Relay is not a VPN

This is the mistake worth catching before it ships. iCloud Private Relay and similar privacy relays route a real person's traffic through Apple's infrastructure, so the exit IP is not the player's own. An API that lumps relays in with VPNs will flag a large, growing slice of ordinary iPhone and Mac players as evaders.

That is why the response separates is_relay from is_vpn. A relay hit is not a region-hopper signal; it is a privacy-feature signal from a legitimate device. In the middleware above, is_relay is carried through but deliberately left out of the anonymized check, so a relay user is not swept into the elevated bucket. If you want to be stricter, treat a relay as "verify by other means," not "block." Blocking Apple's relay is a support-ticket generator, not a fair-play win.

From detection to enforcement

Binary "block all VPNs" is the blunt instrument that gets you false-positive complaints from corporate, university, and carrier-CGNAT players who share flagged ranges. Score the connection instead and match the response to the stakes. The threat_score gives you a 0 to 100 dial; here is a starting map for games.

threat_score	What it usually means	Gaming action
0 to 19	Clean residential or mobile IP	Allow everything, including ranked
20 to 44	Some signal, needs context	Allow, log, watch for other flags
45 to 79	Flagged VPN, proxy, or datacenter	Allow casual, restrict ranked and store
80 to 100	Tor, known attacker, high-confidence proxy	Block or send to manual review

The bands are a default, not gospel. Tune them against your own traffic, and remember that a threat score is a starting point, not a verdict; read the individual flags to see why an IP scored the way it did before you act on it. A datacenter VPN and a residential proxy at the same score deserve different treatment, and the flags are what tell them apart.

Where you enforce also matters more than the number. At login, restrict ranked for elevated risk but let casual through. At matchmaking, use the resolved country to keep a VPN player in their true regional pool instead of the one they are pretending to be in. At purchase, this is the one place fail-closed makes sense: if the flags say VPN and the store region does not match, hold the transaction and ask the player to buy from their real region.

Where this breaks, honestly

A few things this approach does not solve, so you plan around them instead of trusting the check too far.

Residential proxies are the hard problem. A player routing through a residential-proxy service looks like a real home connection, and is_residential_proxy will catch some but not all of them. Pair it with account age and behavior for anything high-stakes; do not rely on the IP alone.

A borrowed IP defeats you cleanly. Someone playing through a friend's home connection in the target country produces a genuinely local, genuinely clean result. There is no IP signal that flags this, because there is nothing anomalous about the IP. This is an account-layer problem.

Store-region abuse mostly lives outside the IP. Because storefront region is tied to account and payment method, an IP check at checkout is a weak backstop at best. The real controls are billing-country verification and account region history.

And false positives are real. Corporate networks, university campuses, and mobile carriers using CGNAT can share IP ranges that carry VPN or proxy signals. That is exactly why the enforcement above leans on soft friction and fail-open defaults rather than hard blocks: the cost of wrongly locking out a paying player is higher than the cost of letting one region-hopper into a casual match.

Wire the check into login, matchmaking, and purchase, cache each IP's result for five to ten minutes so you are not paying for a lookup on every request, and read the individual flags before you act rather than trusting the score alone. If I were building this from scratch, I would fail open everywhere except the payment path from day one, and treat every flag as a reason to add friction, not a reason to slam the door.

How to Detect Residential Proxies in Your Application

Abdul Mateen — Fri, 08 May 2026 01:41:39 +0000

Residential proxy detection is one of the most challenging problems in IP-based threat intelligence. VPNs run on known datacenter IP ranges; you can blocklist them. Tor exit nodes publish their addresses. Datacenter proxies sit on hosting ASNs that reputation databases flag in hours. Residential proxies do none of that. They route traffic through real consumer ISP connections (Comcast, Vodafone, Jio, Deutsche Telekom), making every request look like it comes from someone's living room.

The FBI published a PSA in March 2026 warning that residential proxies have become a standard tool for credential stuffing, account takeovers, and purchase fraud. Google's Threat Intelligence team disrupted what they called the largest residential proxy network a month earlier. The threat is not emerging. It's operational.

This tutorial walks through detecting residential proxy traffic using an IP security API, with production code in cURL, Python, and Node.js.

TL;DR

Residential proxies use real ISP-assigned IPs, so VPN blocklists and datacenter ASN checks miss them.
API-based detection matches IPs against known residential proxy networks and returns provider attribution, confidence scores, and a composite threat score.
The examples below use a dedicated security endpoint that returns 17 fields per IP, including is_residential_proxy with provider names.
Use confidence scores and threat scores to add friction rather than hard-blocking. The same IP may serve both proxy traffic and legitimate users.

Why residential proxies bypass traditional detection

VPN detection is a solved problem (mostly). Commercial VPN providers run dedicated server infrastructure on hosting ASNs. NordVPN, ExpressVPN, Mullvad all operate on IP ranges that every major reputation database can flag within days.

Residential proxies work differently. They source IPs through three channels:

Embedded SDKs. Proxy providers pay mobile app developers to bundle their SDK. When someone installs the app, their device becomes a proxy exit node. The FBI PSA specifically calls this out as the most common sourcing method.

Peer-to-peer bandwidth sharing. "Earn money from your internet connection" apps funnel traffic through consumer devices. Users opt in without understanding their connection will be used for credential stuffing or ad fraud.

Compromised devices. Malware turns IoT devices, routers, and set-top boxes into proxy nodes. Trend Micro documented residential proxy providers in eastern Asia shipping pre-infected Android devices with proxy SDKs installed at the factory.

The result: proxy traffic originates from IPs assigned to Comcast, Jio, Telekom, and other consumer ISPs. To a traditional IP reputation system, it looks like a legitimate user.

How bad is the false negative problem? In 2024, Peakhour tested five major IP intelligence services against 25 IPs that had been actively used as residential proxies within the previous five minutes. MaxMind detected 0 out of 25. IPQualityScore detected 6 out of 25. proxycheck.io detected 0 out of 25. Cloudflare's research found that 4 out of 5 requests from residential proxy IPs are legitimate traffic from the device's real owner. That ratio is why hard-blocking creates unacceptable collateral damage.

What to look for in a detection API

Several IP intelligence APIs offer proxy detection: Spur, IPQualityScore, IPGeolocation, IPinfo, proxycheck.io, IP2Proxy, and others. Before picking one, check for:

A dedicated residential proxy flag separate from the generic is_proxy field. vpnapi.io, IPstack, and AbstractAPI return boolean proxy flags but don't distinguish residential proxies from datacenter proxies.

Provider attribution. Knowing an IP is "a proxy" is less useful than knowing it's Oxylabs, 922 Proxy, or Bright Data. Provider names let you build granular rules.

Confidence scores, not just boolean flags. A binary yes/no produces false positives on mobile carriers and large ISPs sharing IPs across thousands of users via CGNAT.

A composite threat score. An IP might simultaneously be a residential proxy, a known attacker, and a spam source. A composite score saves you from writing the aggregation logic.

Update frequency. Residential proxy IPs churn faster than VPN server IPs. A database that refreshes weekly will miss the majority of active endpoints.

I'll use ipgeolocation.io for the examples because the Security API returns a dedicated is_residential_proxy flag with provider names and confidence scores on all paid plans starting at $19/month. The same approach works with any API that provides equivalent signals.

Making the API call

The dedicated security endpoint:

curl -s "https://api.ipgeolocation.io/v3/security?apiKey=$IPGEO_API_KEY&ip=85.117.56.115" | python3 -m json.tool

{
    "ip": "85.117.56.115",
    "security": {
        "threat_score": 75,
        "is_tor": false,
        "is_proxy": true,
        "proxy_provider_names": [
            "Evomi Proxy",
            "DataImpulse",
            "NetNut",
            "Proxy Scrape"
        ],
        "proxy_confidence_score": 90,
        "proxy_last_seen": "2026-04-22",
        "is_residential_proxy": true,
        "is_vpn": true,
        "vpn_provider_names": [
            "Bestproxyswitcher VPN"
        ],
        "vpn_confidence_score": 90,
        "vpn_last_seen": "2026-03-19",
        "is_relay": false,
        "relay_provider_name": "",
        "is_anonymous": true,
        "is_known_attacker": true,
        "is_bot": false,
        "is_spam": false,
        "is_cloud_provider": false,
        "cloud_provider_name": ""
    }
}

A few things to notice here. The is_proxy flag is true and is_residential_proxy is also true, so this IP is being used by a residential proxy network. The proxy_provider_names array identifies the specific provider (Evomi Proxy, a commercial residential proxy service). The proxy_confidence_score of 85 means the API has high confidence in this classification. And threat_score of 75 places this IP in the "high risk" range, where you'd typically add friction.

Compare that to what a VPN-only API would return: a generic boolean flag with no provider name, no confidence score, and often no residential proxy flag at all. The difference between "this IP is suspicious" and "this IP is on the Evomy Proxy residential network with 85% confidence" is the difference between a useful detection system and a noisy one.

For the full API documentation, including field-level reference tables and error codes, see the docs.

Python implementation

import os
import requests

def check_residential_proxy(ip_address):
    """Check if an IP is a residential proxy. Returns a dict with detection results."""
    api_key = os.environ.get("IPGEO_API_KEY")
    if not api_key:
        raise EnvironmentError("IPGEO_API_KEY environment variable not set")

    try:
        response = requests.get(
            "https://api.ipgeolocation.io/v3/security",
            params={"apiKey": api_key, "ip": ip_address},
            timeout=(1.0, 1.5),  # connect timeout, read timeout
        )
        response.raise_for_status()
    except requests.exceptions.Timeout:
        # Fail open: if the API is unreachable, allow the request through
        return {"detected": False, "reason": "api_timeout", "action": "allow"}
    except requests.exceptions.RequestException as e:
        return {"detected": False, "reason": f"api_error: {e}", "action": "allow"}

    data = response.json()
    security = data.get("security", {})

    is_residential = security.get("is_residential_proxy", False)
    confidence = security.get("proxy_confidence_score", 0)
    threat_score = security.get("threat_score", 0)
    providers = security.get("proxy_provider_names", [])

    # Decision logic based on threat_score ranges
    if is_residential and confidence >= 70:
        if threat_score >= 80:
            action = "block"
        elif threat_score >= 45:
            action = "challenge"  # CAPTCHA, step-up auth, or rate limit
        else:
            action = "monitor"  # log but allow
    else:
        action = "allow"

    return {
        "detected": is_residential,
        "confidence": confidence,
        "threat_score": threat_score,
        "providers": providers,
        "action": action,
    }


result = check_residential_proxy("85.117.56.115")
print(f"Residential proxy: {result['detected']}")
print(f"Action: {result['action']}")
if result.get("providers"):
    print(f"Provider: {', '.join(result['providers'])}")

Pitfall: The timeout=(1.0, 1.5) matters. For an inline check on a login flow, anything slower degrades UX enough to hurt conversion. And the function fails open on API errors: if the API is unreachable, the request passes through. Failing closed means your login page breaks on every API hiccup. Fail open on detection; fail closed only on payment fraud flows where the cost of a miss exceeds the cost of a false block.

Node.js implementation

async function checkResidentialProxy(ipAddress) {
  const apiKey = process.env.IPGEO_API_KEY;
  if (!apiKey) {
    throw new Error("IPGEO_API_KEY environment variable not set");
  }

  const url = `https://api.ipgeolocation.io/v3/security?apiKey=${apiKey}&ip=${ipAddress}`;

  try {
    const response = await fetch(url, {
      signal: AbortSignal.timeout(1500), // 1.5s total timeout
    });

    if (!response.ok) {
      console.error(`Security API returned ${response.status}`);
      return { detected: false, action: "allow", reason: "api_error" };
    }

    const data = await response.json();
    const security = data?.security ?? {};

    const isResidential = security.is_residential_proxy ?? false;
    const confidence = security.proxy_confidence_score ?? 0;
    const threatScore = security.threat_score ?? 0;
    const providers = security.proxy_provider_names ?? [];

    let action = "allow";
    if (isResidential && confidence >= 70) {
      if (threatScore >= 80) action = "block";
      else if (threatScore >= 45) action = "challenge";
      else action = "monitor";
    }

    return { detected: isResidential, confidence, threatScore, providers, action };
  } catch (err) {
    // Fail open on network errors and timeouts
    console.error("Security API check failed:", err.message);
    return { detected: false, action: "allow", reason: "timeout_or_network" };
  }
}

AbortSignal.timeout(1500) kills the request after 1.5 seconds regardless of connection state. Optional chaining on data?.security handles partial or unexpected responses.

Building decision logic

The code uses a three-tier matrix based on threat_score:

1 to 19 (low risk): Allow the request. Even if is_residential_proxy is true, a low threat score with low confidence usually means a brief or historical proxy association. Log it.

45 to 79 (elevated risk): This is where most active residential proxy traffic lands. Add friction: CAPTCHA, email verification, step-up auth. Don't hard-block; the IP might serve legitimate users behind CGNAT.

80 to 100 (high risk): Multiple strong signals stacked together. Block or require manual review.

Pitfall: Indian mobile carriers (Jio, Airtel) route millions of users through a handful of public IPs via CGNAT. A residential proxy flag on a Jio IP with confidence 30 is likely noise. The same flag on a European broadband IP with confidence 90 is almost certainly a detection. Your decision function should treat confidence below 50 differently from confidence above 70.

Caching and rate considerations

Residential proxy IPs rotate fast. A scraper using Oxylabs or Bright Data might cycle exit nodes every request. That's why detection APIs exist, but it also means aggressive caching defeats the purpose.

For auth and fraud workflows, cache detection results for 5 to 15 minutes. For content personalization, 1 to 4 hours is fine. If you're processing logs after the fact, the bulk endpoint accepts up to 50,000 IPs per POST request.

What detection APIs can and cannot do

API-based detection catches known proxy networks. Oxylabs, Bright Data, 922 Proxy, SOAX, IPRoyal, and Smartproxy all operate at scale, and their IP pools are large enough to fingerprint.

What it won't catch: zero-day proxy infrastructure, small botnet-based networks, and proxies that load as separate software modules on compromised devices (a pattern Trend Micro flags as an emerging evasion technique).

Connection-level signals fill part of the gap. JA4+ TCP/TLS fingerprinting can detect proxied traffic based on packet characteristics that differ between direct and proxied connections. But JA4+ requires CDN or WAF-level access and is not something you add with an API call.

The practical recommendation: layer an IP intelligence API with behavioral analysis on your application side. An IP flagged as a residential proxy that also shows high login failure rates and automated navigation patterns is a much stronger signal than any single method alone.

A few extra notes

When traffic outgrows the free tier. The Security API costs 2 credits per lookup. At 150,000 credits/month on the Starter plan, that's plenty for login and checkout checks on a mid-traffic app. If you need per-request lookups on every page load, consider the downloadable residential proxy database instead.

Redis caching pattern. Store the threat_score and is_residential_proxy result with a 10-minute TTL keyed on the IP. Check Redis before the API call. This cuts redundant lookups by 70-80% on session-based traffic without serving dangerously stale results.

Fail-open vs fail-closed, stated explicitly. Every detection integration should document which mode it runs in. If your team can't answer "what happens when the security API is down?" without checking code, that's a gap worth closing before your next incident.

Use ASN Lookups to Spot Fraud Before It Hits Your App

Abdul Mateen — Mon, 04 May 2026 15:56:37 +0000

Most IP-based fraud checks stop at geolocation and VPN flags. That misses a layer of context sitting right there in the data: the autonomous system number.

A single ASN lookup tells you which organization controls the IP block your visitor is connecting from. It tells you whether that IP belongs to a residential ISP like Comcast (AS7922), a cloud provider like Hetzner (AS24940), or a VPN operator. That distinction matters. A login attempt from a Comcast residential IP and one from a Hetzner datacenter IP carry very different risk profiles, even if both geolocate to the same city.

This tutorial builds a risk-scoring function that combines ASN type classification with IP security signals (VPN detection, proxy detection, threat scoring) in a single API call. You will walk away with Express middleware you can drop into a Node.js app, plus equivalent Python code.

TL;DR

Every IP address belongs to exactly one ASN, which identifies the organization controlling that IP block
The ASN's type field (ISP, HOSTING, BUSINESS, EDUCATION) is a strong fraud signal because most automated attacks originate from HOSTING-type networks
Combining ASN type with VPN/proxy detection and threat scoring in one API call gives you a composite risk score without multiple vendor roundtrips
The tutorial builds a calculateRiskScore() function and Express middleware with caching, fail-open logic, and proper error handling

ASN data adds network-level context that geolocation and VPN flags alone cannot provide. Knowing that an IP belongs to a datacenter hosting provider changes a fraud decision differently than knowing it geolocates to Dallas. This tutorial shows how to make that distinction programmatically and act on it.

What an ASN tells you that geolocation doesn't

An autonomous system (AS) is a network, or collection of networks, operated by a single organization under a single routing policy. Each AS gets a unique number from a regional internet registry (ARIN, RIPE, APNIC, LACNIC, AFRINIC). There are roughly 115,000 active ASNs as of 2026.

The practical value for fraud detection is the ASN metadata, not the number itself. When you look up an IP's ASN, you get the organization name, its type classification, the country of registration, and the RIR that issued it. The type field is where the fraud signal lives.

Here is what a lookup returns for a Hetzner datacenter IP (49.12.0.0):

{
  "asn": {
    "as_number": "AS24940",
    "organization": "Hetzner Online GmbH",
    "type": "HOSTING",
    "country": "DE",
    "domain": "hetzner.com",
    "rir": "RIPE"
  }
}

And here is the same lookup for a Google corporate IP (8.8.8.8):

{
  "asn": {
    "as_number": "AS15169",
    "organization": "Google LLC",
    "type": "BUSINESS",
    "country": "US",
    "domain": "google.com",
    "rir": "ARIN"
  }
}

The type field classifies the ASN into categories like ISP (consumer broadband), HOSTING (cloud/datacenter), BUSINESS (corporate networks), and EDUCATION (university networks). This classification comes from analyzing the ASN's routing behavior, registered purpose, and allocation history.

Why does this matter for fraud? The Cybercrime Information Center's Q1 2025 data tracked malware activity by ASN and found DigitalOcean (AS14061) ranked #5 globally with 29,089 unique malware-hosting IPs from only 3 million routed addresses. Amazon's AS16509 had 13,459 malware addresses but spread across 210 million routed IPs. Hosting-type ASNs are disproportionately represented in malicious activity relative to their size.

A related ARIN-funded study by the DNS Research Federation (published January 2026) found that roughly 70% of reported malware URLs rely solely on IP addresses rather than domain names. That means DNS-based detection misses them entirely, and IP-level enrichment (including ASN data) is one of the few signals that catches them.

ASN type as a fraud signal

Here is how to interpret each type in a fraud context:

ISP is the expected type for real human users. Comcast (AS7922), Verizon (AS701), Deutsche Telekom (AS3320). Residential broadband. The vast majority of legitimate traffic comes from ISP-type ASNs. Low risk by itself, though compromised home machines and residential proxies use ISP ASNs too.

HOSTING is the high-attention category. AWS, Hetzner, DigitalOcean, OVH, Linode. Cloud VMs and dedicated servers. Legitimate users don't typically browse your app from a Hetzner VPS. When a login or signup comes from a HOSTING-type ASN, it is worth adding friction: a CAPTCHA, rate limiting, or manual review depending on your risk tolerance.

BUSINESS covers corporate networks. A login from a BUSINESS-type ASN is usually a company employee on a corporate VPN or office network. Medium context. Could be fine. Could be a compromised machine on a corporate network. Treat as neutral unless other signals (threat score, proxy flag) elevate it.

EDUCATION means university or research networks. Often legitimate. Also a common source of scanning and experimentation from campus WiFi. Low-to-medium risk.

Pitfall: ASN type is a prior, not a verdict. Blocking all HOSTING-type traffic would lock out developers who test from cloud VMs, monitoring services that health-check your endpoints, and legitimate webhook callbacks from SaaS platforms. Use ASN type to adjust a risk score, not as a binary block rule.

Fetch ASN and security data for an IP

Several providers return ASN data in their IP intelligence APIs: ipinfo, MaxMind GeoIP2, Team Cymru, IPLocate, and IPGeolocation.io all support ASN lookups. I will use IPGeolocation.io for the examples because a single call to the /v3/ipgeo endpoint returns ASN classification and security signals (VPN, proxy, threat score) together, which saves you a second API round-trip.

Note: ASN data is on the free tier (1,000 requests/day). The security signals (include=security) require a paid plan starting at $19/month for 150K requests. The combined call is what makes the fraud pipeline work, so the examples use the paid path.

curl

curl -s "https://api.ipgeolocation.io/v3/ipgeo?\
apiKey=${IPGEO_API_KEY}&\
ip=49.12.0.1&\
include=security"

{
  "ip": "49.12.0.1",
  "asn": {
    "as_number": "AS24940",
    "organization": "Hetzner Online GmbH",
    "type": "HOSTING",
    "country": "DE",
    "domain": "hetzner.com",
    "rir": "RIPE"
  },
  "security": {
    "threat_score": 80,
    "is_tor": false,
    "is_proxy": false,
    "proxy_provider_names": [],
    "proxy_confidence_score": 0,
    "proxy_last_seen": "",
    "is_residential_proxy": false,
    "is_vpn": false,
    "vpn_provider_names": [],
    "vpn_confidence_score": 0,
    "vpn_last_seen": "",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": false,
    "is_known_attacker": false,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Hetzner Online GmbH"
  }
}

That is a lot more than Boolean flags. The security response includes provider names for VPNs and proxies when detected, confidence scores (0 to 100) indicating detection certainty, last-seen timestamps, and separate classifications for relays, bots, spam sources, known attackers, and cloud providers. For this Hetzner datacenter IP, the is_cloud_provider flag fires with the provider name, the threat score sits at 80, and the ASN type confirms HOSTING. Three independent signals pointing in the same direction.

Node.js

// fetchIpIntel.js
// Returns ASN + security data for a given IP address

const API_KEY = process.env.IPGEO_API_KEY;
const BASE_URL = 'https://api.ipgeolocation.io/v3/ipgeo';

async function fetchIpIntel(ip) {
  const params = new URLSearchParams({
    apiKey: API_KEY,
    ip,
    include: 'security',
  });

  try {
    const res = await fetch(`${BASE_URL}?${params}`, {
      signal: AbortSignal.timeout(1500), // Fail fast; don't hold the request
    });

    if (!res.ok) {
      throw new Error(`API returned ${res.status}: ${res.statusText}`);
    }

    return await res.json();
  } catch (err) {
    // Network timeout, DNS failure, or API error
    console.error(`IP intel lookup failed for ${ip}:`, err.message);
    return null;
  }
}

export { fetchIpIntel };

Python

# fetch_ip_intel.py
# Returns ASN + security data for a given IP address

import os
import requests

API_KEY = os.environ.get("IPGEO_API_KEY")
BASE_URL = "https://api.ipgeolocation.io/v3/ipgeo"


def fetch_ip_intel(ip: str) -> dict | None:
    try:
        resp = requests.get(
            BASE_URL,
            params={
                "apiKey": API_KEY,
                "ip": ip,
                "include": "security",
            },
            timeout=(1.0, 1.5),  # (connect, read) timeouts in seconds
        )
        resp.raise_for_status()
        return resp.json()
    except requests.RequestException as exc:
        print(f"IP intel lookup failed for {ip}: {exc}")
        return None

Both implementations include timeouts, error handling, and environment variable API keys. If the API is unreachable, they return null/None instead of raising. This matters for the next step.

Build a risk-scoring function

The risk function takes the combined ASN + security response and returns a numeric score with a decision. The thresholds below are a starting point. Tune them to your traffic.

Node.js

// riskScore.js
// Composite risk scoring from ASN type + security signals

const ASN_TYPE_RISK = {
  HOSTING: 30,    // Datacenter/cloud: high attention
  BUSINESS: 10,   // Corporate network: some attention
  EDUCATION: 5,   // University: low attention
  ISP: 0,         // Residential broadband: expected
};

function calculateRiskScore(data) {
  if (!data?.asn || !data?.security) {
    // Missing data = unknown risk. Return a middle score, not zero.
    return { score: 50, decision: 'CHALLENGE', reason: 'incomplete data' };
  }

  let score = 0;
  const factors = [];

  // ASN type classification
  const asnType = data.asn.type ?? 'UNKNOWN';
  const asnRisk = ASN_TYPE_RISK[asnType] ?? 15;
  score += asnRisk;
  if (asnRisk > 0) factors.push(`asn_type:${asnType}`);

  // VPN detection
  if (data.security.is_vpn) {
    score += 20;
    factors.push('vpn');
  }

  // Proxy detection (non-VPN proxies)
  if (data.security.is_proxy) {
    score += 25;
    factors.push('proxy');
  }

  // Residential proxy: hardest to detect, highest risk when present
  if (data.security.is_residential_proxy) {
    score += 30;
    factors.push('residential_proxy');
  }

  // Tor exit node
  if (data.security.is_tor) {
    score += 25;
    factors.push('tor');
  }

  // Known attacker: IP flagged in threat intelligence feeds
  if (data.security.is_known_attacker) {
    score += 35;
    factors.push('known_attacker');
  }

  // Bot traffic
  if (data.security.is_bot) {
    score += 20;
    factors.push('bot');
  }

  // Spam source
  if (data.security.is_spam) {
    score += 15;
    factors.push('spam');
  }

  // Cloud provider (corroborates HOSTING ASN type)
  if (data.security.is_cloud_provider) {
    score += 10;
    factors.push(`cloud:${data.security.cloud_provider_name || 'unknown'}`);
  }

  // API threat score (0-100), scaled to contribute up to 30 points
  const threatScore = data.security.threat_score ?? 0;
  const threatContribution = Math.round((threatScore / 100) * 30);
  score += threatContribution;
  if (threatContribution > 10) factors.push(`threat:${threatScore}`);

  // Cap at 100
  score = Math.min(score, 100);

  // Decision thresholds
  let decision;
  if (score < 20) decision = 'ALLOW';
  else if (score < 50) decision = 'CHALLENGE';
  else decision = 'BLOCK';

  return { score, decision, factors };
}

export { calculateRiskScore };

A few design choices worth calling out:

The ASN type contributes 0 to 30 base points. That is enough to push a borderline IP into CHALLENGE territory, but not enough to trigger BLOCK on its own. A Hetzner IP with no VPN flags and a low threat score scores 30 (CHALLENGE). Add a VPN flag and it jumps to 50 (BLOCK). That graduated response is the point.

is_known_attacker gets the highest individual weight (35 points) because it means the IP appears in threat intelligence feeds as a confirmed attacker. Residential proxies get 30 because they are the hardest signal to detect and almost always indicate fraud or scraping when present. The is_cloud_provider flag adds a modest 10 points on its own since it corroborates the ASN type rather than standing alone as evidence.

Missing data defaults to score 50 and CHALLENGE. This is a judgment call. If you can't determine the risk, adding friction (CAPTCHA, email verification) is safer than either allowing blindly or blocking based on no evidence.

Python

# risk_score.py
# Composite risk scoring from ASN type + security signals

ASN_TYPE_RISK = {
    "HOSTING": 30,
    "BUSINESS": 10,
    "EDUCATION": 5,
    "ISP": 0,
}


def calculate_risk_score(data: dict | None) -> dict:
    if not data or "asn" not in data or "security" not in data:
        return {"score": 50, "decision": "CHALLENGE", "reason": "incomplete data"}

    score = 0
    factors = []

    # ASN type
    asn_type = data["asn"].get("type", "UNKNOWN")
    asn_risk = ASN_TYPE_RISK.get(asn_type, 15)
    score += asn_risk
    if asn_risk > 0:
        factors.append(f"asn_type:{asn_type}")

    # Security flags
    sec = data["security"]
    if sec.get("is_vpn"):
        score += 20
        factors.append("vpn")
    if sec.get("is_proxy"):
        score += 25
        factors.append("proxy")
    if sec.get("is_residential_proxy"):
        score += 30
        factors.append("residential_proxy")
    if sec.get("is_tor"):
        score += 25
        factors.append("tor")
    if sec.get("is_known_attacker"):
        score += 35
        factors.append("known_attacker")
    if sec.get("is_bot"):
        score += 20
        factors.append("bot")
    if sec.get("is_spam"):
        score += 15
        factors.append("spam")
    if sec.get("is_cloud_provider"):
        score += 10
        factors.append(f"cloud:{sec.get('cloud_provider_name', 'unknown')}")

    # Threat score contribution (up to 30 points)
    threat = sec.get("threat_score", 0)
    threat_contrib = round((threat / 100) * 30)
    score += threat_contrib
    if threat_contrib > 10:
        factors.append(f"threat:{threat}")

    score = min(score, 100)

    if score < 20:
        decision = "ALLOW"
    elif score < 50:
        decision = "CHALLENGE"
    else:
        decision = "BLOCK"

    return {"score": score, "decision": decision, "factors": factors}

Wire it into Express middleware

Here is how the pieces fit together in a Node.js backend. The middleware runs on every request (or on sensitive routes like /login and /signup), caches results per IP, and attaches the risk assessment to req for downstream handlers.

// ipRiskMiddleware.js
import { fetchIpIntel } from './fetchIpIntel.js';
import { calculateRiskScore } from './riskScore.js';
import { createClient } from 'redis';

const redis = createClient({ url: process.env.REDIS_URL });
redis.on('error', (err) => console.error('Redis error:', err));
await redis.connect();

const CACHE_TTL = 900; // 15 minutes for security data

async function ipRiskMiddleware(req, res, next) {
  // Trust proxy must be configured in Express for this to work behind a load balancer.
  // Without it, req.ip returns the load balancer's IP, not the client's.
  const clientIp = req.ip;

  if (!clientIp) {
    req.riskScore = { score: 0, decision: 'ALLOW', factors: ['no_ip'] };
    return next();
  }

  try {
    // Check cache first
    const cached = await redis.get(`ip-risk:${clientIp}`);
    if (cached) {
      req.riskScore = JSON.parse(cached);
      return next();
    }

    const intel = await fetchIpIntel(clientIp);
    const risk = calculateRiskScore(intel);

    // Cache the result
    await redis.setEx(`ip-risk:${clientIp}`, CACHE_TTL, JSON.stringify(risk));

    req.riskScore = risk;
  } catch (err) {
    // Fail open: if anything breaks, let the request through.
    // For payment endpoints, you might want fail-closed instead.
    console.error('Risk middleware error:', err.message);
    req.riskScore = { score: 0, decision: 'ALLOW', factors: ['error_failopen'] };
  }

  next();
}

export { ipRiskMiddleware };

Usage in your Express app:

import express from 'express';
import { ipRiskMiddleware } from './ipRiskMiddleware.js';

const app = express();

// Enable trust proxy if behind nginx, Cloudflare, AWS ALB, etc.
// Without this, req.ip is wrong and everything downstream breaks.
app.set('trust proxy', true);

// Apply to sensitive routes
app.use('/login', ipRiskMiddleware);
app.use('/signup', ipRiskMiddleware);

app.post('/login', (req, res) => {
  const { score, decision, factors } = req.riskScore;

  if (decision === 'BLOCK') {
    // Log the attempt; don't tell the user why
    console.warn(`Blocked login: ip=${req.ip} score=${score} factors=${factors}`);
    return res.status(403).json({ error: 'Request blocked' });
  }

  if (decision === 'CHALLENGE') {
    // Require additional verification (CAPTCHA, email OTP, etc.)
    return res.status(200).json({ requiresChallenge: true, challengeType: 'captcha' });
  }

  // Proceed with normal login flow
  // ... your auth logic here
});

Tip: The middleware defaults to fail-open: if Redis is down, the API is unreachable, or anything else breaks, the request goes through with decision: 'ALLOW'. This is the right default for most web apps where availability matters more than blocking every threat. For payment processing, checkout flows, or high-value account actions, switch to fail-closed (return CHALLENGE or BLOCK on error) so an API outage does not leave a security gap.

What this catches (and what it doesn't)

Worth being honest about limits. ASN-based risk scoring is strongest against:

Datacenter-originating attacks. Credential stuffing bots running on AWS, Hetzner, or DigitalOcean VMs get flagged immediately because their ASN type is HOSTING. Combined with the threat score, these typically score 50+ and land in BLOCK territory. This is the highest-volume category of automated abuse, and ASN type catches it without maintaining IP blocklists.

VPN and proxy traffic. The security flags add 20 to 25 points on top of whatever the ASN type contributes. A consumer VPN like NordVPN on an ISP-type ASN still gets flagged through the VPN detection layer, and the combined score pushes it into CHALLENGE range.

Bot and scanner traffic. The API's threat_score aggregates signals from threat feeds, behavioral profiling, and known attacker databases. Bots hitting your endpoints from cloud infrastructure combine a high threat score with a HOSTING ASN type, which stacks into the BLOCK range.

The approach is weakest against:

Residential proxies. These are the hardest threat to catch because they route traffic through real ISP connections. The ASN type shows ISP (expected for legitimate users), and the IP itself may belong to an unsuspecting home user whose device is part of a proxy network. The is_residential_proxy flag helps, but detection rates for residential proxies are lower across the industry than for VPNs or datacenter proxies.

Compromised home machines. A botnet node on a residential Comcast connection has a clean ASN type (ISP) and may not trigger threat scoring until it is reported. IP-level signals alone are insufficient here; you need behavioral analytics at the application layer (login velocity, credential patterns, session anomalies).

Legitimate cloud traffic. Webhook callbacks from Stripe, monitoring probes from Datadog, or API calls from a customer's cloud deployment all come from HOSTING-type ASNs. The scoring function correctly flags them. You will need allowlists for known service IPs or a separate path for server-to-server calls that skips the risk middleware.

Go deeper: the dedicated ASN API

The fraud pipeline above uses the unified /v3/ipgeo endpoint, which returns ASN basics alongside security signals in one call. That is the right choice for per-request middleware where you want combined data with minimal latency.

But ipgeolocation.io also has a dedicated ASN endpoint (/v3/asn) that returns richer network topology data. This is useful for incident response, threat hunting, and understanding the network infrastructure behind suspicious traffic.

curl -s "https://api.ipgeolocation.io/v3/asn?\
apiKey=${IPGEO_API_KEY}&\
asn=24940&\
include=peers,upstreams,downstreams"

{
  "asn": {
    "as_number": "AS24940",
    "organization": "Hetzner Online GmbH",
    "country": "DE",
    "type": "HOSTING",
    "domain": "http://hetzner.com/",
    "date_allocated": "2002-06-03",
    "asn_name": "HETZNER-AS",
    "allocation_status": "ASSIGNED",
    "num_of_ipv4_routes": "86",
    "num_of_ipv6_routes": "6",
    "rir": "RIPE",
    "routes": [
      "78.46.0.0/15",
      "138.199.128.0/17",
      "185.189.230.0/24",
      "85.10.192.0/18",
      "185.228.8.0/23",
      "185.157.178.0/23",
      "65.21.0.0/16",
      ...
  ]
    "downstreams": [
      {
        "as_number": "AS202851",
        "description": "rackSPEED GmbH",
        "country": "DE"
      },...
    ],
    "peers": [
      {
        "as_number": "AS61851",
        "description": "Garra Telecom Ltda",
        "country": "BR"
      },...
    ],
    "upstreams": [
      {
        "as_number": "AS12552",
        "description": "GlobalConnect AB",
        "country": "SE"
      },...
    ]
  }
}

The dedicated endpoint adds fields that the unified endpoint does not return: asn_name (the short registry name like "HETZNER-AS"), allocation_status, route counts (num_of_ipv4_routes, num_of_ipv6_routes), and the optional network relationship data.

Where this data earns its keep:

Upstream analysis. If a suspicious ASN routes traffic through known bulletproof hosting upstreams, that is a stronger signal than ASN type alone. Some fraud operations use small ASNs with clean type classifications but route through upstream providers with poor abuse handling.

Peer clustering. An ASN that peers heavily with other known-bad ASNs may share infrastructure with them. During incident response, pulling the peer list helps you identify related networks to investigate.

Route counts. An ASN with 2 IPv4 routes is a small operation. One with 500+ is a large provider. The scale tells you whether a few bad IPs are coincidental or systemic.

IP prefix enumeration. Add include=routes to get every IP prefix announced by the ASN. Useful for building targeted blocklists during an active attack, or for retrospective analysis of log data against a suspect network.

This is not data you need in real-time middleware. It is data you query during investigation, threat hunting, or when building batch-processing pipelines that assess risk at the ASN level rather than per-IP.

A few extra notes

Cache aggressively. ASN data changes rarely. An IP's autonomous system stays the same for months or years. Security signals change faster but are still valid for 5 to 15 minutes. The middleware above caches combined results for 15 minutes, which keeps API usage well within plan limits even at high traffic volumes.

IPv6 works the same way. The API accepts both IPv4 and IPv6 addresses. The ASN lookup returns the same fields. No code changes needed, but make sure your IP extraction handles both formats (Express does this by default when trust proxy is configured).

Log the decision, not the raw IP. IP addresses are personal data under GDPR. If you operate in the EU or serve EU users, log the risk score, decision, and contributing factors rather than storing the raw IP alongside user records. The risk assessment is what you need for audit trails; the IP itself is not necessary after the decision is made.

Bulk lookups for historical analysis. If you are processing logs or running batch fraud analysis, the API supports up to 50,000 IPs per POST request on the bulk endpoint. That is useful for retroactive analysis: pull your last 30 days of login IPs, run them through the bulk endpoint, and see what your current scoring function would have caught.

Next steps

Start with logging-only mode. Apply the middleware to your login and signup routes, but only log the risk scores for a week before you enforce any blocking. Compare the scores against your existing fraud data to tune the thresholds. The defaults in the code above (ALLOW < 20, CHALLENGE < 50, BLOCK >= 50) are conservative. Your traffic will tell you whether to tighten or loosen them.

If you need the risk data without the API call on every request, the downloadable IP-to-ASN and IP Security databases let you run lookups locally. Latency drops to microseconds, but you take on the update cycle yourself.

Turn Any IP Address into Actionable Security Signals in JavaScript

Abdul Mateen — Thu, 23 Apr 2026 13:01:49 +0000

IP data is not just about location. It can also help you understand risk, detect suspicious traffic, and make smarter decisions in real time. In this guide, you will learn how to use IP intelligence to flag risky requests, enrich logs, and build simple security checks into your app using a single API.

Why IP intelligence matters for developers?

Every request hitting your app carries an IP address. Most apps ignore it beyond logging, but that IP can reveal useful signals such as:

Whether the request is coming from a VPN or proxy
If the IP is associated with known malicious activity
The ASN and ISP behind the request
Risk indicators you can use for rate limiting or blocking

Adding this layer helps you:

Reduce fraud and abuse
Improve login security
Filter bot traffic
Add context to analytics and logs

What you will build

By the end of this tutorial, you will have:

A JavaScript function that checks an IP for risk signals
A simple threat scoring logic for your app
A middleware style pattern for Node.js
A frontend example to display risk status

The API endpoint

We will use the following base endpoint:

https://api.ipgeolocation.io/v3/ipgeo

we will request security-related fields.

Step 1: Fetch IP security data

To access security details, a paid API key is required. You can view the pricing options here: IPGeolocation.io Pricing.

The Starter plan is a great option as it costs just $19/month and includes 150,000 credits, which should be enough for most basic use cases.

Here is a minimal JavaScript example:

async function checkIPSecurity(ip) {
  const API_KEY = 'YOUR_API_KEY';

  const res = await fetch(
    `https://api.ipgeolocation.io/v3/ipgeo?apiKey=${API_KEY}&ip=${ip}&include=security&fields=security`
  );

  const data = await res.json();
  return data.security;
}

// Example usage
checkIPSecurity('8.8.8.8').then(sec => {
  console.log('Is VPN:', sec.is_vpn);
  console.log('Is proxy:', sec.is_proxy);
  console.log('Is Tor:', sec.is_tor);
  console.log('Threat level:', sec.threat_score);
});

Example Response

{
  "security": {
    "is_vpn": false,
    "is_proxy": false,
    "is_tor": false,
    "threat_score": 12
  }
}

These fields give you quick signals without needing complex infrastructure.

Step 2: Create a simple threat scoring system

function evaluateRisk(security) {
  let risk = 'low';

  if (security.is_tor) return 'high';
  if (security.is_proxy || security.is_vpn) risk = 'medium';
  if (security.threat_score > 70) risk = 'high';

  return risk;
}

checkIPSecurity('8.8.8.8').then(sec => {
  const risk = evaluateRisk(sec);
  console.log('Risk level:', risk);
});

Step 3: Use it in a Node.js middleware

export async function securityMiddleware(req, res, next) {
  const ip =
    req.headers['x-forwarded-for']?.split(',')[0].trim() ||
    req.socket.remoteAddress;

  try {
    const response = await fetch(
      `https://api.ipgeolocation.io/v3/ipgeo?apiKey=${process.env.API_KEY}&ip=${ip}&include=security&fields=security`
    );

    const data = await response.json();
    const risk = evaluateRisk(data.security);

    if (risk === 'high') {
      return res.status(403).json({ error: 'Request blocked due to risk' });
    }

    req.riskLevel = risk;
    next();
  } catch (err) {
    next();
  }
}

Step 4: Add context to logs

console.log({
  ip,
  risk: req.riskLevel,
  route: req.originalUrl,
  timestamp: new Date().toISOString()
});

Step 5: Frontend risk indicator

function RiskBadge({ risk }) {
  const color =
    risk === 'high' ? 'red' :
    risk === 'medium' ? 'orange' : 'green';

  return (
    <span style={{ color }}>
      {risk.toUpperCase()}
    </span>
  );
}

Real-world use cases

Login protection

Flag suspicious logins and trigger additional verification

Rate limiting

Apply stricter limits for medium or high-risk IPs

Fraud detection

Block or review transactions from risky networks

Content protection

Restrict access to sensitive endpoints

Handling edge cases

VPN users

Not all VPN users are malicious. Treat them as medium risk instead of
blocking outright.

False positives

Always allow fallback paths, such as manual verification or email
confirmation.

API failure

Wrap calls in try-catch and default to safe behavior.

How to Detect a User's Country and Currency from the IP in JavaScript

Abdul Mateen — Thu, 23 Apr 2026 11:43:23 +0000

TL;DR: Use the IPGeolocation.io API to detect any visitor's country, currency code, currency symbol, and dial code from their IP address — no GPS prompt, no sign-in required. One API call returns everything. Free tier included.

What you'll build

By the end of this tutorial, you'll have a working JavaScript snippet that:

Detects the visitor's country and country flag from their IP address
Returns the local currency code, name, and symbol (e.g. EUR, Euro, €)
Pre-fills a checkout/signup form with country, dial code, and currency — automatically, on page load
Works in Vanilla JS, React, and Node.js

No browser permissions. No annoying "Allow location access" popups. Just a clean API call.

Why detect country and currency from IP?

When a user lands on your site, you already know roughly where they are — through their IP address. Most developers ignore this and make users manually select their country and currency, which:

Creates unnecessary friction at checkout
Increases form abandonment
Makes your site feel generic to international visitors

According to IPGeolocation.io's own data, displaying prices in a visitor's local currency alone can increase conversion rates by up to 40%. Personalizing content by location can improve engagement by up to 70%.

IP-based geolocation is non-intrusive — you're not asking for GPS coordinates or requiring any user interaction. It works silently in the background and simply makes the experience feel tailored.

The API: IPGeolocation.io

IPGeolocation.io is a developer-focused IP intelligence API that returns geolocation, currency, timezone, ASN, and security data for any IPv4 or IPv6 address. It's one of the few providers that includes:

Currency data (code, name, symbol) on the free plan
Country metadata (dial/calling code, TLD, spoken languages)
Country flag URLs and country emoji — ready to drop into UI
A JavaScript SDK available via npm and CDN

Free tier: 30,000 requests/month. No credit card required.

The endpoint we'll use: https://api.ipgeolocation.io/v3/ipgeo

Step 1: Get your free API key

Go to ipgeolocation.io and sign up
Copy your API key from the dashboard at https://app.ipgeolocation.io/dashboard

That's it. No waitlist, no credit card.

Step 2: Make your first API call (Vanilla JS)

The simplest possible call — detect the current visitor's IP automatically:

// Detects the visitor's own IP automatically when no `ip` param is passed
async function getUserGeoData() {
  const API_KEY = 'YOUR_API_KEY_HERE';

  const response = await fetch(
    `https://api.ipgeolocation.io/v3/ipgeo?apiKey=${API_KEY}&fields=location,currency,country_metadata`
  );

  const data = await response.json();
  return data;
}

getUserGeoData().then(data => {
  console.log('Country:', data.location.country_name);
  console.log('Currency code:', data.currency.code);     // e.g. "EUR"
  console.log('Currency symbol:', data.currency.symbol); // e.g. "€"
  console.log('Dial code:', data.country_metadata.calling_code); // e.g. "+49"
  console.log('Flag URL:', data.location.country_flag);
});

Sample API response

Here's what a real response looks like for a visitor from Germany:

{
  "ip": "85.212.44.10",
  "location": {
    "country_name": "Germany",
    "country_code2": "DE",
    "city": "Berlin",
    "state_prov": "Berlin",
    "country_flag": "https://ipgeolocation.io/static/flags/de_64.png",
    "country_emoji": "🇩🇪",
    "is_eu": true
  },
  "country_metadata": {
    "calling_code": "+49",
    "tld": ".de",
    "languages": ["de"]
  },
  "currency": {
    "code": "EUR",
    "name": "Euro",
    "symbol": "€"
  }
}

Notice how much you get in a single request: country, city, EU membership status, dial code, language, and full currency details.

Step 3: Auto-fill a checkout form

Now let's wire this into a real form. This pattern works for signup, checkout, lead gen — anything where you want to reduce friction for international users.

HTML

<form id="checkout-form">
  <label>Country
    <div style="display: flex; align-items: center; gap: 8px;">
      <img id="flag-img" src="" alt="" width="24" style="display:none;" />
      <input type="text" id="country-input" placeholder="Detecting..." />
    </div>
  </label>

  <label>Phone number
    <div style="display: flex; gap: 6px;">
      <input type="text" id="dial-code" style="width: 80px;" placeholder="+1" />
      <input type="tel" id="phone" placeholder="Your phone number" style="flex:1;" />
    </div>
  </label>

  <label>Preferred currency
    <input type="text" id="currency-input" placeholder="USD" />
  </label>
</form>

JavaScript — auto-fill on page load

async function prefillFormFromIP() {
  const API_KEY = 'YOUR_API_KEY_HERE';

  try {
    const res = await fetch(
      `https://api.ipgeolocation.io/v3/ipgeo?apiKey=${API_KEY}&fields=location,currency,country_metadata`
    );
    const data = await res.json();

    // Fill country field
    document.getElementById('country-input').value = data.location.country_name;

    // Show country flag
    const flagImg = document.getElementById('flag-img');
    flagImg.src = data.location.country_flag;
    flagImg.alt = data.location.country_emoji;
    flagImg.style.display = 'inline';

    // Fill dial code
    document.getElementById('dial-code').value = data.country_metadata.calling_code;

    // Fill currency
    const currencyDisplay = `${data.currency.code} (${data.currency.symbol})`;
    document.getElementById('currency-input').value = currencyDisplay;

  } catch (err) {
    console.error('Geolocation lookup failed:', err);
    // Gracefully fall back — leave fields blank for manual entry
  }
}

document.addEventListener('DOMContentLoaded', prefillFormFromIP);

UX tip: Always let the user override the pre-filled values. The goal is to reduce friction, not lock them in.

Step 4: Use the JavaScript SDK (optional but cleaner)

If you're working in a Node.js or bundled project, IPGeolocation.io has an official npm SDK that removes the need to hand-roll fetch calls.

Install

npm install ip-geolocation-api-javascript-sdk

Usage

import { IpGeolocationClient } from "ip-geolocation-api-javascript-sdk";

async function main() {
  const client = new IpGeolocationClient({
    apiKey: "YOUR_API_KEY",
  });

  try {
    const response = await client.lookupIpGeolocation({
      ip: "8.8.8.8",
    });

    console.log("Country:", response.data.location?.countryName); // "United States"
    console.log("City:", response.data.location?.city);
    console.log("Currency", response.data.currency?.code); // "USD"
  } finally {
    await client.close();
  }
}

main().catch((error) => {
  console.error(error);
});

The SDK handles authentication, error retries, and response parsing for you.

Step 5: Use it in React

Here's a clean React hook you can drop into any component:

import { useState, useEffect } from 'react';

function useIPGeo(apiKey) {
  const [geoData, setGeoData] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchGeo = async () => {
      try {
        const res = await fetch(
          `https://api.ipgeolocation.io/v3/ipgeo?apiKey=${apiKey}&fields=location,currency,country_metadata`
        );
        const data = await res.json();
        setGeoData(data);
      } catch (err) {
        setError(err);
      } finally {
        setLoading(false);
      }
    };

    fetchGeo();
  }, [apiKey]);

  return { geoData, loading, error };
}

// Usage in a component
export default function CurrencyBanner({ apiKey }) {
  const { geoData, loading } = useIPGeo(apiKey);

  if (loading) return <p>Detecting your location...</p>;
  if (!geoData) return null;

  const { currency, location, country_metadata } = geoData;

  return (
    <div className="geo-banner">
      <img
        src={location.country_flag}
        alt={location.country_name}
        width={20}
      />
      <span>
        Showing prices in <strong>{currency.name}</strong> ({currency.symbol})
        for {location.country_name}
      </span>
    </div>
  );
}

What fields does the API return?

Here's a quick reference for the fields most useful in localization and checkout flows:

Field path	Example value	Use case
`location.country_name`	`"Germany"`	Display name, form pre-fill
`location.country_code2`	`"DE"`	Passing to payment providers
`location.country_flag`	URL to PNG	Flag icon in UI
`location.country_emoji`	`"🇩🇪"`	Inline emoji flag
`location.is_eu`	`true`	Trigger GDPR consent banner
`currency.code`	`"EUR"`	ISO 4217 currency for Stripe/payment APIs
`currency.name`	`"Euro"`	Display label
`currency.symbol`	`"€"`	Price display
`country_metadata.calling_code`	`"+49"`	Phone number dial code
`country_metadata.languages`	`["de"]`	Auto-select UI language

Handling edge cases

What if the user is on a VPN?

If a user is tunneling through a VPN, the API will return the VPN server's country, not the user's real country. For checkout forms, this is usually fine — the user chose to appear in that country. If it matters for your use case (e.g., tax calculation), you can enable IPGeolocation.io's Security module alongside this call to detect VPN/proxy usage and prompt the user to confirm their location.

What about server-side rendering (Next.js)?

On the server, you have access to the real IP via request headers (x-forwarded-for or req.socket.remoteAddress). Pass that IP explicitly to the API:

// pages/api/geo.js (Next.js API route)
export default async function handler(req, res) {
  const ip =
    req.headers['x-forwarded-for']?.split(',')[0].trim() ||
    req.socket.remoteAddress;

  const API_KEY = process.env.IPGEO_API_KEY;
  const response = await fetch(
    `https://api.ipgeolocation.io/v3/ipgeo?apiKey=${API_KEY}&ip=${ip}&fields=location,currency,country_metadata`
  );

  const data = await response.json();
  res.status(200).json(data);
}

Security note: Keep your API key in environment variables (process.env.IPGEO_API_KEY). Never expose it in client-side JavaScript if you're on a paid plan.

Free tier limits and when to upgrade

Plan	Requests/month	Currency data	Security data
Free	30,000	✅	❌
Paid	150,000+	✅	❌

For most personal projects and small SaaS apps, the free tier is more than enough. Once you need VPN/proxy detection, threat scoring, or higher volume, upgrade to the Paid plan.

Frequently asked questions

Does IP geolocation work for IPv6?
Yes. IPGeolocation.io supports both IPv4 and IPv6 lookups natively. The API endpoint and response format are identical.

How accurate is IP-based country detection?
Country-level accuracy is typically above 99% for most IP ranges. City-level accuracy varies more. For currency and country pre-filling, country-level is all you need.

Can I use this on the frontend without an API key?
Yes — IPGeolocation.io supports keyless authentication via request origin (CORS allowlisting). You add your domain to the dashboard and the API authenticates requests from that domain automatically. This is ideal for frontend-only projects.

Does using IP geolocation require GDPR consent?
Detecting a country from an IP address for UX purposes (form pre-fill, currency display) is generally considered legitimate interest under GDPR — it doesn't involve storing or tracking personal data. Always consult your legal team for your specific use case.

What happens if the API is down or slow?
Always wrap the API call in a try/catch and provide a graceful fallback (leave fields empty, default to USD, etc.). IPGeolocation.io runs on Cloudflare's global network with a 99.99% uptime SLA on paid plans.

Summary

Here's what we covered:

Why detecting country and currency from IP improves conversion and UX
How to use the IPGeolocation.io /v3/ipgeo endpoint to retrieve country, currency, flag, and dial code in one call
A Vanilla JS snippet to auto-fill a checkout form on page load
The npm SDK for Node.js and bundled projects
A React hook (useIPGeo) ready to drop into any component
A Next.js API route pattern for server-side IP resolution
Edge cases: VPN detection, SSR, GDPR, and API key security

The full API response gives you everything you need for a localized, frictionless experience — with zero popups, zero GPS requests, and zero user interaction required.

What's next?

Localize your full UI: Use location.is_eu to trigger GDPR banners, country_metadata.languages to switch UI language automatically
Go offline: For high-traffic apps, IPGeolocation.io offers downloadable IP Geolocation Databases (MMDB, CSV, JSON) for sub-millisecond local lookups