DEV Community: ABDULLAH AFZAL

A Self-Correcting Solar System Baseline From Sunrise/Sunset Data

ABDULLAH AFZAL — Thu, 27 Aug 2026 09:36:23 +0000

A fixed-schedule solar baseline drifts out of sync with the sun throughout the year. In Phoenix the sun is up for 13 hours 10 minutes in late August and 10 hours 2 minutes at the December solstice. A flat daily kWh target flags that entire winter as a fault, then stays quiet on the July afternoon when one string dies at 2pm under full sun. The fix is to anchor the baseline to the actual sun instead of the clock, and most of what you need for that does not require an irradiance forecast.

One thing before any code: sun geometry tells you when a system should be producing and when it should peak. It does not tell you how much light actually reached the panels. That is irradiance, and cloud cover swamps it. If you want modeled output in kWh, reach for Forecast.Solar or Solcast, which fold in weather and your array's tilt and azimuth. What follows is the free, dependency-light layer underneath that: the daylight window, the solar-noon peak, and the day-length trend.

TL;DR

Sun geometry (sunrise, sunset, solar noon, day length) catches a specific class of solar underperformance with no irradiance data.

Gate alerts to the real daylight window so your monitor stops crying "underperformance" before sunrise.

Track the daily production peak relative to solar noon. A persistent shift across comparable days can reveal shading, orientation, or system changes that a total-kWh check misses.

Normalize a flat kWh target by day length so winter stops tripping false alarms. First-order fix, not a physics model.

One call to an astronomy endpoint returns all of it. Code below in curl, Python, and Node.

For real production forecasting, use an irradiance API. Sun times are the sanity layer, not the forecaster.

Sun times will not predict your kWh, but they eliminate common timing-based false alarms and can surface useful production-shape anomalies early. Pull sunrise, sunset, solar noon, and day length once a day, gate your alerts to daylight, watch the peak, and scale the target for season.

What sun times can and cannot tell you

Sun geometry gives you three usable things: the window a system can physically produce in, the moment it should peak, and how that window changes through the year. All three come from a plain lat/long lookup and none of them costs you a weather subscription.

What they leave out is the part that actually varies day to day. A clear July noon and an overcast one have the same solar noon and nearly the same day length, but wildly different output. So sun times are a denominator, not a measurement. Treat a gap between expected window and actual production as a question, not a verdict, and reserve the confident "this panel is broken" call for the cases geometry can isolate on its own.

Plenty of tools return sun times: Sunrise-Sunset.org is free with no signup, SunCalc computes positions in the browser without an API at all, and NOAA has a solar calculator. I am using ipgeolocation.io's Astronomy API here because one call returns the window, solar noon, day length, twilight, and the sun's position together, which keeps the code short. Pick whatever you already have in your stack.

The three checks worth building

None of these needs irradiance. Each one closes a real gap in the naive "compare today's kWh to a fixed number" monitor.

Gate alerts to the real daylight window

The cheapest win is to stop evaluating production when the sun is not up. A monitor that compares output to a target every fifteen minutes will happily fire a "low production" alert at 06:00 in December, when sunrise is at 07:25 and the correct output is zero. Gate every underperformance rule behind the sunrise-to-sunset window and that class of alert disappears.

Trim the edges with a margin. Output in the first and last half hour of daylight is near zero because the sun is barely above the horizon, so a low-production alert there is just physics, not a fault. A 30-minute margin inside sunrise and sunset is a reasonable start; widen it for a site with a hard eastern or western horizon. The one edge case to handle is high latitude in midsummer or midwinter, where the API can report the sun as up or down all day; check sun_status before trusting the window there.

Watch the peak drift off solar noon

This is the check that earns its keep. Total daily kWh can look fine while a single string slowly fails, because the healthy strings mask the loss in the daily sum. The shape of the day gives it away sooner.

When the daily peak persistently shifts away from its normal offset, or the curve repeatedly becomes lopsided under comparable conditions, it can point to partial shading, uneven soiling, orientation effects, or inverter behavior. A single cloudy day's peak is weak evidence, so look for the change across multiple days rather than treating one maximum as a fault.

Orientation is the easy thing to get wrong here. A west-facing array peaks after solar noon by design and an east-facing one before it, so the threshold is relative to where your array should peak, not a universal number. Compare today's peak time to solar noon, keep a rolling few weeks of the offset, and alert on the change rather than the absolute value.

Normalize the baseline by day length

A flat kWh target assumes every day has the same amount of daylight, which is why it flags winter. Scaling the target by today's day length against a summer reference removes most of that error in about three lines. A 40 kWh midsummer target becomes roughly 29 kWh at the December solstice (10 hours 2 minutes of daylight against a 14-hour reference); the flat 40 kWh number would have marked a perfectly healthy winter day about 27% low.

Be honest about what this does not fix. Winter days are not just shorter, the sun is also lower, so each daylight hour delivers less energy and real output drops more than the day-length ratio predicts. Day-length scaling gets you from "wildly wrong" to "roughly right," which is enough to stop the seasonal false alarms. Closing the rest of the gap means modeling irradiance and sun elevation, which is exactly the job Forecast.Solar, Solcast, and the pvlib library exist to do.

Pull the sun data

The endpoint is a single GET. The free tier is 1,000 requests a day with no credit card, and one request covers a full day, so a per-site daily pull sits comfortably inside it. Sign up for a key on the Astronomy API and keep it out of source control.

# Free tier: 1000 requests/day, no card. One call returns the whole day's geometry.
# 2s timeout so a slow response can't hang a monitor loop.
curl -sS --max-time 2 \
  "https://api.ipgeolocation.io/v3/astronomy?apiKey=$IPGEO_API_KEY&lat=33.4484&long=-112.0740&date=2026-08-25&time_zone=America/Phoenix"

The response carries far more than the four fields we use. That is the point of one call:

{
  "location": {
    "latitude": "33.44840",
    "longitude": "-112.07400",
    "city": "Phoenix",
    "state_prov": "Arizona",
    "elevation": "331"
  },
  "astronomy": {
    "date": "2026-08-25",
    "current_time": "05:46:58.255",
    "sunrise": "2026-08-25 05:54",
    "sunset": "2026-08-25 19:05",
    "solar_noon": "2026-08-25 12:30",
    "day_length": "13:10",
    "sun_altitude": -3.03,
    "sun_azimuth": 75.14,
    "sun_distance": 151249918.79,
    "sun_status": "-",
    "morning": {
      "civil_twilight_begin": "2026-08-25 05:32",
      "civil_twilight_end": "2026-08-25 05:54",
      "golden_hour_begin": "2026-08-25 05:42",
      "golden_hour_end": "2026-08-25 06:31"
    },
    "evening": {
      "golden_hour_begin": "2026-08-25 18:29",
      "golden_hour_end": "2026-08-25 19:18",
      "civil_twilight_begin": "2026-08-25 19:05",
      "civil_twilight_end": "2026-08-25 19:28"
    },
    "moon_phase": "WAXING_GIBBOUS",
    "moonrise": "2026-08-25 17:48",
    "moonset": "2026-08-25 03:26",
    "moon_illumination_percentage": "93.10"
  }
}

Two things to notice before you write parsers. day_length is a string, "13:10", meaning 13 hours 10 minutes, not a decimal. And because the request set time_zone, the times come back as "YYYY-MM-DD HH:mm" in that zone rather than bare clock times. Both matter for the code. One more, in case it trips you up: sun_altitude and sun_azimuth are the sun's position at current_time, which is when the call ran, not at noon. In this capture that was just before sunrise, hence the negative altitude. The checker below ignores those fields, but they are useful for a live "is the sun even up right now" readout.

Pitfall: timestamps are returned in the time_zone you request. The curl example above asks for Phoenix local time, while the checker below deliberately requests UTC so the timestamps can be parsed unambiguously. Keep now timezone-aware and compare absolute times consistently. The date you request should still be the calendar date at the solar site.

Build the baseline checker

Fetch once per day, then run all three checks against that one response. Calling the API per check wastes credits and adds latency for data that does not change within a day. A small cron job at local midnight that caches the day's response is enough; there is no reason to hit the endpoint again until the date rolls over.

import os
import sys
from datetime import datetime, timedelta, timezone

import requests

IPGEO_API_KEY = os.environ.get("IPGEO_API_KEY")
ASTRONOMY_URL = "https://api.ipgeolocation.io/v3/astronomy"


def fetch_sun_day(lat, lon, date_str):
    """One day of sun geometry. Costs one credit, so call it once per day and
    reuse the result for every check instead of hitting the API per rule."""
    if not IPGEO_API_KEY:
        raise RuntimeError("Set IPGEO_API_KEY in the environment")
    params = {
        "apiKey": IPGEO_API_KEY,
        "lat": lat,
        "long": lon,
        "date": date_str,
        # Request UTC so returned timestamps are unambiguous when parsed.
        "time_zone": "UTC",
    }
    try:
        # (connect, read) timeouts so a slow upstream can't stall the monitor loop
        resp = requests.get(ASTRONOMY_URL, params=params, timeout=(1.0, 1.5))
        resp.raise_for_status()
    except requests.RequestException as err:
        # Fail open: this is a sanity layer, not a safety system. If it's down,
        # skip the geometry checks rather than block the rest of monitoring.
        print(f"sun lookup failed, skipping geometry checks: {err}", file=sys.stderr)
        return None
    return (resp.json() or {}).get("astronomy")


def hhmm_to_minutes(value):
    """day_length arrives as a string like '10:02' (hours:minutes), not decimal."""
    if not value or ":" not in value:
        return None
    hours, minutes = value.split(":")[:2]
    return int(hours) * 60 + int(minutes)


def parse_dt(value):
    """Parse the API's UTC 'YYYY-MM-DD HH:mm' timestamps as aware datetimes."""
    if not value:
        return None
    try:
        return datetime.strptime(
            value, "%Y-%m-%d %H:%M"
        ).replace(tzinfo=timezone.utc)
    except ValueError:
        return None

Those three helpers absorb the two gotchas: the string day length and the dated timestamps. Everything below returns cleanly on missing fields so a partial response never throws.

def in_daylight(now, astro, margin_minutes=30):
    """True only inside the productive window. The margin trims dawn and dusk."""
    status = astro.get("sun_status")

    if status == "Always above the twilight angle":
        return True
    if status == "Always below the twilight angle":
        return False

    sunrise = parse_dt(astro.get("sunrise"))
    sunset = parse_dt(astro.get("sunset"))

    if not sunrise or not sunset:
        return True  # unknown, so don't suppress a potentially real alert

    if now.tzinfo is None:
        raise ValueError("now must be timezone-aware")

    now_utc = now.astimezone(timezone.utc)
    start = sunrise + timedelta(minutes=margin_minutes)
    end = sunset - timedelta(minutes=margin_minutes)

    return start <= now_utc <= end


def peak_drift_minutes(observed_peak, astro):
    """How far the day's production peak sat from solar noon, in minutes.
    observed_peak must be a timezone-aware datetime."""
    solar_noon = parse_dt(astro.get("solar_noon"))
    if not solar_noon or not observed_peak:
        return None

    if observed_peak.tzinfo is None:
        raise ValueError("observed_peak must be timezone-aware")

    observed_peak_utc = observed_peak.astimezone(timezone.utc)
    return abs((observed_peak_utc - solar_noon).total_seconds()) / 60.0


def seasonal_target(base_kwh, astro, reference_day_length="14:00"):
    """Scale a flat kWh target by today's day length against a summer reference.
    Removes the gross seasonal error. It under-corrects, because winter also has a
    lower sun (less energy per daylight hour); closing that gap needs irradiance."""
    today = hhmm_to_minutes(astro.get("day_length"))
    reference = hhmm_to_minutes(reference_day_length)

    if today is None or reference is None or reference == 0:
        return base_kwh

    return round(base_kwh * (today / reference), 1)

Use the daylight gate around real-time production alerts, but run the peak-drift and daily-kWh checks only after the day's production window is complete. A full-day kWh target should never be compared with energy accumulated halfway through the day. The tolerance band below is still only a rough weather buffer, not a substitute for irradiance data.

def evaluate_completed_day(
    observed_peak,
    actual_kwh,
    base_kwh,
    lat,
    lon,
    date_str,
):
    """Run after the day's production window has finished."""
    astro = fetch_sun_day(lat, lon, date_str)
    if astro is None:
        return

    drift = peak_drift_minutes(observed_peak, astro)
    if drift is not None and drift > 90:
        print(
            f"peak offset was {drift:.0f} min from solar noon; "
            "track whether that shift persists across comparable days"
        )

    expected = seasonal_target(base_kwh, astro)

    if actual_kwh < expected * 0.75:
        print(
            f"actual {actual_kwh} kWh below seasonal expectation "
            f"{expected} kWh"
        )

The Node version is the same shape. fetch with a hard timeout, optional chaining on the response, and the identical string-and-timestamp parsing. It assumes Node 18 or newer, where fetch and AbortSignal.timeout are built in; on older runtimes add node-fetch and an abort polyfill.

const ASTRONOMY_URL = "https://api.ipgeolocation.io/v3/astronomy";

async function fetchSunDay(lat, lon, dateStr) {
  const key = process.env.IPGEO_API_KEY;
  if (!key) throw new Error("Set IPGEO_API_KEY in the environment");

  // dateStr should be the calendar date at the solar site.
  // Request event timestamps in UTC so Date parsing is unambiguous.
  const url = `${ASTRONOMY_URL}?apiKey=${key}&lat=${lat}&long=${lon}`
    + `&date=${dateStr}&time_zone=UTC`;
  try {
    // 1.5s timeout so a slow upstream can't stall the monitor loop
    const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const body = await res.json();
    return body?.astronomy ?? null;
  } catch (err) {
    // Fail open: sanity layer, not a safety system
    console.error(`sun lookup failed, skipping geometry checks: ${err.message}`);
    return null;
  }
}

// day_length is a string like "10:02" (h:mm), not a number
function hhmmToMinutes(value) {
  if (!value || !value.includes(":")) return null;
  const [h, m] = value.split(":");
  return Number(h) * 60 + Number(m);
}

// We request UTC from the API, so the timestamp can be parsed unambiguously.
function parseDt(value) {
  if (!value || value === "-:-") return null;
  const d = new Date(`${value.replace(" ", "T")}:00Z`);
  return Number.isNaN(d.getTime()) ? null : d;
}

function inDaylight(now, astro, marginMin = 30) {
  if (astro?.sun_status === "Always above the twilight angle") return true;
  if (astro?.sun_status === "Always below the twilight angle") return false;

  const sunrise = parseDt(astro?.sunrise);
  const sunset = parseDt(astro?.sunset);

  if (!sunrise || !sunset) return true; // unknown, don't suppress a real alert

  const start = new Date(sunrise.getTime() + marginMin * 60000);
  const end = new Date(sunset.getTime() - marginMin * 60000);

  return now >= start && now <= end;
}

function seasonalTarget(baseKwh, astro, referenceDayLength = "14:00") {
  const today = hhmmToMinutes(astro?.day_length);
  const reference = hhmmToMinutes(referenceDayLength);
  if (today === null || reference === null || reference === 0) return baseKwh;
  return Math.round(baseKwh * (today / reference) * 10) / 10;
}

Peak drift is the same idea on parsed values:

function peakDriftMinutes(observedPeak, astro) {
  const solarNoon = parseDt(astro?.solar_noon);
  if (!solarNoon || !observedPeak) return null;
  return Math.abs(observedPeak.getTime() - solarNoon.getTime()) / 60000;
}

Flag it against your array's orientation, same caveat as before: a west-facing array measures drift from its own expected offset, not from solar noon.

Where this stops and irradiance begins

Run the checker against a week of clear days and it behaves. Run it against a stretch of overcast ones and the seasonal check will nag, because a cloudy day and a broken panel look identical to sun geometry. That is the wall. The 25% tolerance band is a blunt way to ride through normal weather, and it works until a genuinely bad week hides a genuinely bad panel.

The honest boundary is this: use sun times as the reference for checks about timing and geometry. The daylight window is deterministic; peak offset is useful when it persists across multiple comparable days, but clouds can move a single day's observed maximum. Lean on day-length scaling only to keep the seasonal baseline in the right ballpark. The moment you need to tell "cloudy" from "faulty," or you care about temperature derating and soiling trends, you have left what geometry can answer and you want an irradiance model: Forecast.Solar and Solcast expose one over an API (Forecast.Solar drops straight into Home Assistant if that is where your dashboard lives), pvlib gives you one in Python, and any of them will take your panel tilt and azimuth into account.

Drop the daylight gate in first. It is the cheapest change and stops the most false alarms. Add the peak-drift check once you have per-interval data to compare against solar noon. And when geometry-level checks stop being enough, treat that as the cue to pull an irradiance forecast, not to keep widening the thresholds until the alerts go quiet.

Enrich Elasticsearch Logs With GeoIP at Ingest

ABDULLAH AFZAL — Mon, 24 Aug 2026 13:26:25 +0000

An access log full of raw IPs can't answer where a traffic spike came from. Elasticsearch GeoIP fixes that at write time, enriching public-IP events with whatever country, region, city, and coordinate data is available so queries, alerts, and dashboards downstream can use geography directly. This guide sets up that enrichment in an ingest pipeline, fixes the two things that silently break it, and puts your logs on a Kibana map.

TL;DR

The geoip processor ships with Elasticsearch as a module. No plugin install, and it auto-downloads the free MaxMind GeoLite2 databases.

Enrichment happens in an ingest pipeline. Test it with the _simulate API before you point real data at it.

Your Kibana map will be empty unless the location field is mapped as geo_point before you index. Set that in an index template first.

Private and internal IPs (RFC 1918) return no geo fields by design. Handle them, don't ignore them.

GeoLite2 is city-level-optimistic and CC BY-SA. When you need better accuracy or security context, swap the database at ingest without changing the pipeline shape.

The short version: turn on a bundled processor, wire it into a pipeline, map one field correctly, and Kibana renders your traffic on a map. The parts that trip people up are the geo_point mapping and the IPs that have no location, both covered below. The core examples below target modern Elasticsearch 8.x and 9.x clusters with security enabled. Third-party ingest plugins have their own Elasticsearch-version compatibility requirements, so check the plugin's supported version before installing one.

What the Elasticsearch geoip processor gives you

The geoip processor is a module distributed with Elasticsearch, so on a current cluster there's nothing to install. By default it uses the GeoLite2 City, GeoLite2 Country, and GeoLite2 ASN databases from MaxMind, shared under CC BY-SA 4.0, and Elasticsearch downloads and updates them automatically from the Elastic GeoIP endpoint.

Feed it a field holding an IP address and it writes a geoip object onto the document. With the default City database, that object can include continent_name, country_iso_code, country_name, region_iso_code, region_name, city_name, and a location object holding lat and lon. You control which of those land with the properties option; the default set is continent_name, country_iso_code, country_name, region_iso_code, region_name, city_name, and location.

Two option names worth knowing before you write anything: target_field (default geoip) is where the enriched object goes, and ignore_missing (default false) decides whether a document with no IP field quietly passes through or errors. We'll use both.

Step 1: Create the ingest pipeline

An ingest pipeline is a named list of processors that runs on a document before it's indexed. Create one with a single geoip processor pointed at your IP field:

# Create a pipeline named "geoip-pipeline" that enriches the "ip" field.
# --cacert points at the CA cert Elasticsearch generated on first start;
# on 8.x/9.x the HTTP layer is TLS-on by default, so http:// will fail.
curl -sS -X PUT "https://localhost:9200/_ingest/pipeline/geoip-pipeline" \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:$ELASTIC_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Add GeoIP fields from the ip field",
    "processors": [
      {
        "geoip": {
          "field": "ip",
          "target_field": "geoip",
          "ignore_missing": true
        }
      }
    ]
  }'

ignore_missing: true matters more than it looks. Real log streams have events without a client IP (health checks, internal jobs). Without it, every one of those throws and the document is rejected. With it, they index cleanly and simply carry no geoip object.

Before you send a single real document, dry-run the pipeline with the _simulate API. This runs your processors against a sample doc and returns the result without indexing anything:

# Dry-run the pipeline against a real public IP.
# 8.8.8.8 is a convenient public test address. The exact GeoLite2 fields and coordinates can change as the database is updated.
curl -sS -X POST "https://localhost:9200/_ingest/pipeline/geoip-pipeline/_simulate" \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:$ELASTIC_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "docs": [
      { "_source": { "ip": "8.8.8.8" } }
    ]
  }'

The response wraps the enriched document under doc._source, and you should see a populated geoip object:

{
  "docs": [
    {
      "doc": {
        "_source": {
          "ip": "8.8.8.8",
          "geoip": {
            "continent_name": "North America",
            "country_iso_code": "US",
            "country_name": "United States",
            "location": { "lon": -97.822, "lat": 37.751 }
          }
        }
      }
    }
  ]
}

If _simulate gives you the fields you expect, the pipeline works. The rest is deciding what data flows through it and making sure Kibana can read the output.

Step 2: Map location as geo_point before you index

Here's the failure that fills the Elastic forums: everything ingests fine, the geoip.location field is populated, and the Kibana map is stubbornly empty. The cause is mapping. Elasticsearch's dynamic mapping sees { "lat": ..., "lon": ... } and guesses two float fields. Kibana Maps only plots a field typed as geo_point, and it won't infer that on its own.

Fix it once with an index template so every matching index is born with the right type:

# Any index matching "logs-geo-*" gets geoip.location typed as geo_point.
# Create this BEFORE the first document lands, or the wrong type sticks.
curl -sS -X PUT "https://localhost:9200/_index_template/logs-geo-template" \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:$ELASTIC_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "index_patterns": ["logs-geo-*"],
    "template": {
      "settings": {
        "index.default_pipeline": "geoip-pipeline"
      },
      "mappings": {
        "properties": {
          "geoip": {
            "properties": {
              "location": { "type": "geo_point" }
            }
          }
        }
      }
    }
  }'

Two things happened in that template. The mappings block pins geoip.location to geo_point so Kibana will plot it. And index.default_pipeline sets the pipeline to run automatically on anything written to a logs-geo-* index, so you don't have to name it on every request.

Pitfall: mapping type is fixed at field creation. If documents already landed and geoip.location came out as float, you can't change it in place. You create a new index with the correct template and reindex into it. Get the template in before the first write and you never hit this.

Step 3: Wire the pipeline to your log stream

You have two ways to attach the pipeline. The template above already set index.default_pipeline, which is the clean option: write to the index normally and enrichment is automatic. The other option is naming the pipeline per request with ?pipeline=geoip-pipeline, which is handy for one-off backfills but noisy to repeat on every write.

If you ingest with your own code, the bulk helper is the usual path. Here's a minimal, production-shaped Python ingester using the official client:

import os
from elasticsearch import Elasticsearch, helpers

# Never hardcode credentials. Pull them from the environment.
ES_URL = os.environ.get("ES_URL", "https://localhost:9200")
ES_USER = os.environ.get("ES_USER", "elastic")
ES_PASSWORD = os.environ.get("ES_PASSWORD")
CA_CERT = os.environ.get("ES_CA_CERT", "/etc/elasticsearch/certs/http_ca.crt")

client = Elasticsearch(
    ES_URL,
    basic_auth=(ES_USER, ES_PASSWORD),
    ca_certs=CA_CERT,
    request_timeout=10,  # fail fast instead of hanging a worker
)

def log_events():
    # Replace with your real source (a file tail, a queue, etc.).
    yield {"ip": "8.8.8.8", "path": "/checkout", "status": 200}
    yield {"ip": "2001:4860:4860::8888", "path": "/login", "status": 401}

def index_logs():
    # The index name matches logs-geo-*, so the default_pipeline runs
    # and geo_point mapping applies. No per-doc pipeline needed here.
    actions = ({"_index": "logs-geo-000001", "_source": event}
               for event in log_events())
    try:
        success, errors = helpers.bulk(client, actions, raise_on_error=False)
        if errors:
            # Log rejected docs; don't let one bad IP kill the batch.
            for err in errors:
                print(f"index error: {err}")
        return success
    except Exception as exc:
        # Network or auth failure: surface it, don't swallow it.
        print(f"bulk ingest failed: {exc}")
        return 0

if __name__ == "__main__":
    print(f"indexed {index_logs()} events")

raise_on_error=False plus an error loop is deliberate: one document with a malformed IP shouldn't sink a 10,000-event batch. You log the rejects and keep going.

One convention worth adopting if you use the Elastic Common Schema: put the client address in source.ip and target source.geo instead of a bare geoip field. Elastic's own dashboards and detection rules expect ECS field names like source.geo.country_iso_code, source.geo.city_name, and source.geo.location. Set "field": "source.ip" and "target_field": "source.geo" in the processor and your data drops straight into the built-in tooling.

A word on Logstash, since half the tutorials on this topic start there. The Logstash geoip filter still works and still makes sense if Logstash is already in your pipeline doing Grok parsing and transforms. But if Elasticsearch is your ingest point, the ingest-pipeline approach keeps enrichment inside the cluster with one less moving part to run and monitor. Use the filter when you're already in Logstash; use the processor when you're not.

Step 4: Put it on a map in Kibana

With geo_point mapping in place, Kibana Maps takes a couple of clicks:

Create a data view over your logs-geo-* indices (Stack Management, then Data Views).
Open Maps from the Analytics menu and add a layer from that data view.
Because geoip.location (or source.geo.location) is a geo_point, the documents layer plots each event as a point. Style by count to cluster dense areas. If you followed a tutorial that told you to create a "Tile Map" or "Coordinate Map" visualization, that's why it didn't work. Those classic visualization types were retired; the Maps application replaced them, and it reads geo_point fields directly through a data view.

Private and internal IPs return nothing

The geoip processor looks up public IP geolocation. Private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), loopback, and carrier-grade NAT (100.64.0.0/10) have no geographic location, so those documents come back with no geoip object at all. That's correct behavior, but if a chunk of your traffic is internal, a naive setup leaves you with events that silently have no geo and no explanation.

Tag them instead of dropping them. Add a conditional processor that marks internal traffic before the lookup, so a missing geoip object is intentional rather than a mystery:

# Mark RFC 1918 addresses as internal, then geoip-enrich the rest.
# Explicitly match the RFC 1918 private ranges so internal traffic
# is labeled instead of silently appearing without GeoIP data.
curl -sS -X PUT "https://localhost:9200/_ingest/pipeline/geoip-pipeline" \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:$ELASTIC_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Tag internal IPs, geoip-enrich the rest",
    "processors": [
      {
        "set": {
          "field": "network.scope",
          "value": "internal",
          "if": "def ip = ctx.ip; ip != null && (ip.startsWith(\"10.\") || ip.startsWith(\"192.168.\") || ip.startsWith(\"172.16.\") || ip.startsWith(\"172.17.\") || ip.startsWith(\"172.18.\") || ip.startsWith(\"172.19.\") || ip.startsWith(\"172.20.\") || ip.startsWith(\"172.21.\") || ip.startsWith(\"172.22.\") || ip.startsWith(\"172.23.\") || ip.startsWith(\"172.24.\") || ip.startsWith(\"172.25.\") || ip.startsWith(\"172.26.\") || ip.startsWith(\"172.27.\") || ip.startsWith(\"172.28.\") || ip.startsWith(\"172.29.\") || ip.startsWith(\"172.30.\") || ip.startsWith(\"172.31.\"))"
        }
      },
      {
        "geoip": {
          "field": "ip",
          "target_field": "geoip",
          "ignore_missing": true
        }
      }
    ]
  }'

Internal events now carry network.scope: internal, so one common reason for a missing geoip object is explicit instead of silent. Public IPs with no database match can still have no geoip object. No more staring at half-empty maps wondering where the other half went.

Backfilling indices you already have

Enrichment only touches documents at write time, so turning on the pipeline does nothing for the millions of events already sitting in your indices. To geo-tag existing data, run _update_by_query with the pipeline applied:

# Reprocess existing docs through the pipeline.
# Run this against a copy or a low-traffic window first: it rewrites
# every matched document and costs real I/O.
curl -sS -X POST "https://localhost:9200/logs-geo-000001/_update_by_query?pipeline=geoip-pipeline&wait_for_completion=false" \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:$ELASTIC_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "bool": {
        "must_not": [
          { "exists": { "field": "geoip" } }
        ]
      }
    }
  }'

The must_not exists geoip filter avoids reprocessing documents that were successfully enriched. Be aware that private IPs and public IPs with no database match also have no geoip field, so they will be selected again on a later run. If you need a strictly resumable backfill, add a separate processing marker and filter on that instead.
wait_for_completion=false returns a task ID immediately so a long backfill doesn't tie up your connection; poll it with the Tasks API.

One caveat: if the old index has geoip.location mapped as float (because it predates your template), _update_by_query writes the fields but Kibana still won't map them. In that case you reindex into a freshly templated index instead. Backfill in place when the mapping is already correct; reindex when it isn't.

When GeoLite2 is not enough

GeoLite2 is free, bundled, and good enough to see which countries your traffic comes from. It is also the lite tier: MaxMind's own positioning is that GeoLite2 is less accurate than paid GeoIP2, city-level results are approximate, and the CC BY-SA 4.0 license carries attribution and share-alike obligations that some commercial deployments can't accept. When you outgrow it, you swap the database, not the pipeline.

You have a few paths, and they nest cleanly into what you already built:

Point the same processor at a licensed MaxMind database. Elasticsearch can download GeoIP2 directly using your MaxMind license key through the database configuration API, and the geoip processor keeps working unchanged.
Use IPinfo databases via the ip_location processor. Recent Elasticsearch versions ship an ip_location processor that supports IPinfo databases alongside MaxMind, so you can switch providers without leaving the ingest layer.
Load a custom database file. Both processors accept a database_file option, so a compatible MaxMind-format database supported by the processor can back the lookup.
Enrich from a local database that also carries security and timezone context. IPGeolocation publishes an Elasticsearch ingest processor plugin that runs the lookup against a locally installed IPGeolocation database, so alongside country and city you get currency, timezone, and IP-security signals in the same document, with no per-event API call. That last option is worth a concrete look because it combines IPGeolocation's geolocation, timezone, currency, and security data in one local enrichment path. The plugin installs with elasticsearch-plugin install, a setup script downloads the database tier you licensed, and the processor is named ipgeo. Its required options are field (your IP field) and database_version (DB-I through DB-VII, the database tier you licensed); target_field defaults to ipgeo, and include pulls in the extra data classes:

# The ipgeo processor from the IPGeolocation plugin.
# database_version selects the licensed DB tier; include pulls in
# the security and timezone data classes on top of geolocation.
curl -sS -X PUT "https://localhost:9200/_ingest/pipeline/ipgeo-pipeline" \
  --cacert /etc/elasticsearch/certs/http_ca.crt \
  -u "elastic:$ELASTIC_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "description": "Enrich with IPGeolocation databases",
    "processors": [
      {
        "ipgeo": {
          "field": "ip",
          "database_version": "DB-VI",
          "ignore_missing": true,
          "include": "security,timezone"
        }
      }
    ]
  }'

A document enriched by that pipeline carries a richer object than GeoLite2 returns. The relevant part of the response, from the plugin's own docs:

{
  "ipgeo": {
    "country_name": "United States",
    "country_code2": "US",
    "city": "San Francisco",
    "state_prov": "California",
    "zipcode": "94107-2008",
    "location": { "lon": -122.39117, "lat": 37.78229 },
    "currency": { "symbol": "$", "code": "USD", "name": "US Dollar" },
    "time_zone": {
      "name": "America/Los_Angeles",
      "offset": -7.0,
      "is_dst": true,
      "current_time": "2024-05-17 04:52:01.693-0700"
    },
    "security": {
      "is_proxy": false,
      "proxy_type": "",
      "is_tor": false,
      "is_anonymous": false,
      "is_known_attacker": false,
      "is_bot": false,
      "is_spam": false,
      "is_cloud_provider": false,
      "threat_score": 0
    }
  }
}

The trade-off is honest and worth stating plainly: this path costs a plugin install, a licensed database, and an Elasticsearch restart, and the ipgeo.location field still needs the same geo_point mapping as before. What you get back is currency, timezone, and a security block (proxy, Tor, cloud-provider, known-attacker flags, and a threat_score) on every event, computed locally with no lookup latency. If your logs feed fraud rules or security dashboards, that context in the same document is the reason to pay. If you only need a map of where traffic comes from, GeoLite2 is already enough and you can stop at Step 4.

Operational notes

A few things that bite in production and rarely make it into tutorials:

The auto-downloaded databases expire. If Elasticsearch can't reach the Elastic GeoIP endpoint for 30 days, it stops using the stale databases and enrichment quietly goes blank, showing up as _geoip_expired_database tags on your documents. In an air-gapped cluster this is a when, not an if. Plan for a reverse-proxy or custom endpoint, or serve your own databases and turn the downloader off.

To disable the downloader entirely, set ingest.geoip.downloader.enabled: false in the cluster settings. Do this when you run only custom or licensed databases and don't want Elasticsearch reaching out for GeoLite2 updates you aren't using. Leave it enabled if you rely on Elasticsearch's automatically downloaded GeoLite2 databases. Disabling the downloader removes those downloaded databases; the 30-day expiration behavior applies when updates remain enabled but Elasticsearch cannot reach the GeoIP endpoint.

Enrichment runs on ingest nodes and costs CPU per document. On a high-volume cluster, watch ingest node load after you turn on a geo pipeline, and give dedicated ingest nodes room if a lookup runs on every event.

Get the geo_point mapping in before the first write, tag your internal IPs, and decide up front whether the free database is enough or you need licensed accuracy and security context. Those three calls are the difference between a map that just works and a week of debugging why half your events have no location.

How Do You Detect Bogon and Reserved IPs in Code?

ABDULLAH AFZAL — Thu, 20 Aug 2026 11:38:47 +0000

Some IP addresses should never show up as a client: bogon and reserved ranges. A signup form that logs 10.0.0.7 as the visitor, a fraud rule that scores 192.0.2.45, a geolocation lookup on 169.254.10.2: all three are working with addresses that carry no public meaning, and if your code treats them like normal traffic, you get silent bad data.

This is a reference for the application side of that problem. Not router ACLs or BGP prefix lists, which are covered to death elsewhere, but the check you run in Node or PHP when an IP arrives at your app and you have to decide: reject it, flag it, or trust it.

TL;DR

Bogon and reserved ranges are IPs that should never appear as a public source: unallocated space plus reserved blocks like private (RFC 1918), CGNAT, loopback, link-local, and documentation.
The action depends on the block. Private ranges are fine inside your network but suspect as a public client source. Documentation and "this network" ranges are always rejectable. CGNAT is legitimate but ungeolocatable.
The IPGeolocation API returns HTTP 423 Locked for bogon and private addresses, and those lookups do not consume credits, so the API can also act as a validation backstop.
In code, classify the IP against the special-use CIDR set locally first (fast, no network), then let the 423 be the authoritative signal on the lookup you were going to make anyway.
Normalize IPv4-mapped IPv6 (::ffff:a.b.c.d) before you check, or half your rules miss.

Special-use IPs fall into ranges that are either unallocated or reserved by RFC. Your app should treat each range by what it means: reject the impossible ones, flag the ungeolocatable ones, and accept private ranges only where an internal source makes sense. The rest of this reference is the range-by-range mapping and the code to apply it.

The special-use IP handling matrix

The core of this reference is not "what is a bogon." Our own full canonical IPv4 and IPv6 bogon list already covers the definitions and the complete range tables. What almost nobody writes down is what an application should do with each range when it shows up as a client address. That is the table below.

Three actions:

Reject: the address cannot legitimately be a public client. Drop it, or 400 the request.
Flag: the address can appear legitimately but you cannot geolocate or trust it. Keep the request, mark it, skip location logic.
Accept (internal): valid when the source is genuinely inside your network or behind your own proxy. The same address as a claimed public client source is a reject.

IPv4 special-use ranges and how your app should treat each

Range	What it is	Defined by	App treatment as a public client source
`0.0.0.0/8`	"This network"	RFC 791	Reject
`10.0.0.0/8`	Private	RFC 1918	Accept internal, reject as public
`100.64.0.0/10`	CGNAT / shared	RFC 6598	Flag (behind carrier NAT, ungeolocatable)
`127.0.0.0/8`	Loopback	RFC 1122	Reject (that is your own host)
`169.254.0.0/16`	Link-local	RFC 3927	Reject
`172.16.0.0/12`	Private	RFC 1918	Accept internal, reject as public
`192.0.0.0/24`	IETF protocol assignments	RFC 6890 / IANA registry	Check specific assignment; do not blanket-reject the entire `/24`
`192.0.2.0/24`	Documentation (TEST-NET-1)	RFC 5737	Reject
`192.168.0.0/16`	Private	RFC 1918	Accept internal, reject as public
`198.18.0.0/15`	Benchmark testing	RFC 2544	Reject
`198.51.100.0/24`	Documentation (TEST-NET-2)	RFC 5737	Reject
`203.0.113.0/24`	Documentation (TEST-NET-3)	RFC 5737	Reject
`224.0.0.0/4`	Multicast	RFC 5771	Reject (not a unicast client)
`240.0.0.0/4`	Reserved, future use	RFC 1112	Reject
`255.255.255.255/32`	Limited broadcast	RFC 919	Reject

The authoritative source of truth for this list is the IANA IPv4 Special-Purpose Address Registry, which records each block, its defining RFC, and whether it is valid as a source or destination. If you only hardcode one list, hardcode that one.

IPv6 ranges that actually reach applications

You do not need the full IPv6 bogon set (that is tens of thousands of prefixes). You need the handful that show up at an application:

Range	What it is	App treatment
`::1/128`	Loopback	Reject (your own host)
`::/128`	Unspecified	Reject
`::ffff:0:0/96`	IPv4-mapped	Normalize, then re-check the embedded IPv4
`fc00::/7`	Unique local (ULA)	Accept internal, reject as public
`fe80::/10`	Link-local	Reject
`2001:db8::/32`	Documentation	Reject
`ff00::/8`	Multicast	Reject

The IPv4-mapped row is the one that bites people. An address like ::ffff:10.0.0.7 is a private IPv4 address wearing an IPv6 coat. If your check only looks at IPv6 ranges, it sails through. Strip the ::ffff: prefix and run the IPv4 rules on what is left.

Bogon, martian, reserved: the distinction developers get wrong

These terms overlap, but they are not identical. A bogon is commonly an address from space that should not appear as a public Internet source, including unallocated space and addresses reserved for private or special use. A martian is an operational term for a packet whose source or destination is invalid or implausible in the network where it appears. Unlike the reserved ranges, “martian” is not a fixed CIDR list; whether an address is martian can depend on routing and network context.

Why it matters for your code: the stable special-use ranges are safe to hardcode because they rarely change. Unallocated address space is different: it changes as IANA and the RIRs delegate space, which is why a static “block all bogons” list eventually goes stale. For application-side validation, check the stable special-use ranges locally and use a current lookup or bogon feed for the moving portion. If you have ever wondered "why do I have a bogon IP in my logs," it is usually one of two things: a misconfigured client leaking a private source, or a spoofed packet. Neither is a real user you can act on.

Why your geolocation lookup returns 423 on these IPs

A well-behaved geolocation API refuses to invent a location for an address that has none. Send a bogon to the lookup endpoint and you get a 423 Locked back instead of a fake record:

curl 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=10.0.0.1'

HTTP/1.1 423 Locked
{
  "message": "'10.0.0.1' is a bogon IP address."
}

Two things make this useful rather than just an error. First, the lookup is not billed: bogon, private, and malformed IPs do not count against your quota, so you can throw questionable addresses at the API purely to validate them. Second, in a bulk call the same input does not blow up the batch. Invalid entries come back as per-record objects carrying a message field, while the valid IPs in the request are geolocated normally, so you can run a cleanup pass over a dirty log without splitting it first.

IPinfo, ip-api, MaxMind GeoIP2, IPGeolocation, and other IP-data providers handle bogon and private addresses specially, but the response model differs: some return a bogon marker, some return an error, and some return no matching record. I am using IPGeolocation for the examples because the 423 plus the not-billed behavior makes it clean to wire up as a validation layer. Pick whichever is already in your stack; the handling pattern below is the same.

Detecting special-use IPs in code

Two layers. The local check classifies the address against the martian set with no network call, which is the fast path for the common case. The API 423 is the authoritative backstop on the lookup you were making anyway, and it covers the moving unallocated ranges your hardcoded list does not.

Node.js: local classification with `net.BlockList`

Node ships a CIDR matcher in the standard library, so you do not need a dependency for the local check.

const net = require('node:net');

// Build the block list once at module load. Reuse it; rebuilding per request is wasteful.
const REJECT = new net.BlockList();
const FLAG = new net.BlockList();
const PRIVATE = new net.BlockList();

// Always-reject IPv4 (impossible or documentation-only as a public source)
[['0.0.0.0', 8], ['127.0.0.0', 8], ['169.254.0.0', 16],
 ['192.0.2.0', 24], ['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]].forEach(([ip, p]) => REJECT.addSubnet(ip, p, 'ipv4'));

// Private (accept only when an internal source is expected)
[['10.0.0.0', 8], ['172.16.0.0', 12], ['192.168.0.0', 16]]
  .forEach(([ip, p]) => PRIVATE.addSubnet(ip, p, 'ipv4'));

// CGNAT: legitimate but ungeolocatable, so flag rather than reject
FLAG.addSubnet('100.64.0.0', 10, 'ipv4');

// IPv6 special-use ranges that can reach application code
REJECT.addSubnet('::', 128, 'ipv6');          // unspecified
REJECT.addSubnet('::1', 128, 'ipv6');         // loopback
REJECT.addSubnet('fe80::', 10, 'ipv6');       // link-local
REJECT.addSubnet('2001:db8::', 32, 'ipv6');   // documentation
REJECT.addSubnet('ff00::', 8, 'ipv6');        // multicast
PRIVATE.addSubnet('fc00::', 7, 'ipv6');       // unique local

function classifyIp(raw) {
  // IPv4-mapped IPv6 (::ffff:10.0.0.7) is a v4 address in disguise. Unwrap before checking.
  const ip = raw.startsWith('::ffff:') && raw.includes('.') ? raw.slice(7) : raw;
  const type = net.isIPv6(ip) ? 'ipv6' : net.isIPv4(ip) ? 'ipv4' : null;
  if (!type) return 'reject';          // not a valid IP at all
  if (REJECT.check(ip, type)) return 'reject';
  if (FLAG.check(ip, type)) return 'flag';
  if (PRIVATE.check(ip, type)) return 'private';   // caller decides accept vs reject by context
  return 'public';
}

module.exports = { classifyIp };

net.BlockList does the subnet math for both families, and building the lists once at load keeps the per-request cost to a lookup. The classifyIp return value is the decision your route handler acts on, not a bare boolean, because "reject," "flag," and "internal-only" are three different responses.

For addresses that pass the local special-use checks but may still fall into freshly unallocated space, let the geolocation lookup act as the backstop:

The following example uses the global fetch API and AbortSignal.timeout(), so run it on Node.js 18+.

async function geolocate(ip) {
  const local = classifyIp(ip);
  if (local === 'reject') {
      return { ok: false, reason: 'special-use' };
  }

  if (local === 'flag') {
      return { ok: null, reason: 'cgnat' };
  }

  if (local === 'private') {
      return { ok: null, reason: 'private' };
  }

  try {
    const res = await fetch(
      `https://api.ipgeolocation.io/v3/ipgeo?apiKey=${process.env.IPGEO_API_KEY}&ip=${encodeURIComponent(ip)}`,
      { signal: AbortSignal.timeout(1500) } // never let a lookup hang a request
    );

    // 423 means the API classified it as bogon/private. Trust that over your static list.
    if (res.status === 423) return { ok: false, reason: 'bogon' };
    if (!res.ok) return { ok: null, reason: `http_${res.status}` }; // fail open, see below

    const data = await res.json();
    return { ok: true, location: data.location ?? null };
  } catch (err) {
    // Timeout or network error. Fail open here so a lookup outage does not block real users.
    console.error('geo lookup failed:', err.message);
    return { ok: null, reason: 'lookup_error' };
  }
}

Note the two failure paths. A 423 is a definite "this IP is special-use," so it is safe to act on. A timeout or 5xx is unknown, and the ok: null lets the caller decide whether to fail open or closed.

PHP: a CIDR check without a library

PHP has no native "is this IP in this CIDR" for both families, so here is a compact helper that handles v4 and v6 with inet_pton and a bitmask.

<?php

function ipInCidr(string $ip, string $cidr): bool {
    [$subnet, $bits] = explode('/', $cidr);
    $ipBin = @inet_pton($ip);
    $subnetBin = @inet_pton($subnet);
    // Reject mismatched families (v4 IP against v6 subnet, or an unparseable address)
    if ($ipBin === false || $subnetBin === false || strlen($ipBin) !== strlen($subnetBin)) {
        return false;
    }
    $bits = (int) $bits;
    $bytes = intdiv($bits, 8);
    $remainder = $bits % 8;
    // Whole-byte portion must match exactly
    if ($bytes > 0 && substr($ipBin, 0, $bytes) !== substr($subnetBin, 0, $bytes)) {
        return false;
    }
    // Partial byte: compare only the masked high bits
    if ($remainder !== 0) {
        $mask = ~(0xff >> $remainder) & 0xff;
        if ((ord($ipBin[$bytes]) & $mask) !== (ord($subnetBin[$bytes]) & $mask)) {
            return false;
        }
    }
    return true;
}

function classifyIp(string $raw): string {
    // Normalize IPv4-mapped IPv6 addresses so the IPv4 rules apply.
$ip = $raw;
$packed = @inet_pton($raw);

if (
    $packed !== false &&
    strlen($packed) === 16 &&
    substr($packed, 0, 10) === str_repeat("\x00", 10) &&
    substr($packed, 10, 2) === "\xff\xff"
) {
    $ip = inet_ntop(substr($packed, 12, 4));
}

    if (filter_var($ip, FILTER_VALIDATE_IP) === false) {
        return 'reject'; // not an IP we can trust
    }

    $reject = ['0.0.0.0/8','127.0.0.0/8','169.254.0.0/16','192.0.2.0/24','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','::/128','::1/128','fe80::/10','2001:db8::/32', 'ff00::/8'];
    $private = ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', 'fc00::/7'];

    foreach ($reject as $cidr) {
        if (ipInCidr($ip, $cidr)) return 'reject';
    }
    if (ipInCidr($ip, '100.64.0.0/10')) return 'flag'; // CGNAT
    foreach ($private as $cidr) {
        if (ipInCidr($ip, $cidr)) return 'private';
    }
    return 'public';
}

The @ on inet_pton suppresses the warning on a garbage input; the explicit false checks handle it instead. Pair classifyIp with the same API backstop as the Node version. If it returns reject, stop immediately. Handle flag and private according to request context without geolocating them. Only send addresses classified as public to /v3/ipgeo; if that lookup returns HTTP 423, treat it as a bogon or otherwise non-public address that your local static list did not catch.

Reject, flag, or accept: making the call

The local classifier hands you a label; the request context decides the response.

Pitfall: The single most common mistake is treating a private source IP as a real client because your app sits behind a load balancer. If you read req.socket.remoteAddress, you will see the proxy, not the user. Read the client IP from a trusted X-Forwarded-For (only the hop your proxy sets, not the whole attacker-controllable header) and classify that.

Fail-open versus fail-closed is a decision you should make on purpose, not by accident. If the geolocation lookup errors or times out, failing open (let the request through, skip the location logic) is right for most apps, because a lookup outage should not lock out real users. Fail closed only when the geolocation is the security control, for example a hard geo-restriction where "unknown" must mean "denied." The 423 case is different from an error: it is a definite answer, so you act on it regardless of your fail direction.

The CGNAT trap deserves a callout. 100.64.0.0/10 is legitimate inside carrier and service-provider networks, but it is not a globally routable client address. If it reaches your application through trusted internal infrastructure, flag it and skip geolocation. If it appears as the claimed source of a normal public Internet request, treat it as invalid or suspicious rather than as a geolocatable public client.

Keeping the list current

The reserved ranges in the tables above are safe to hardcode because they are defined by RFCs that change on the order of years. The unallocated portion is the part that moves, and IPv6 still has large unallocated regions that shift as IANA delegates space. If you need the moving set kept current at the network layer, Team Cymru's bogon reference is the long-standing source, published as BGP feeds, DNS, and plain lists that update through the day. For an application, the cleaner split is to hardcode the static martian set for your local fast path and let the API's 423 cover whatever has changed since you last looked.

If you run this at scale, cache the classification. The local check is cheap, but the API backstop is a network hop, so a short-lived cache keyed on the IP saves you repeat lookups on the same noisy sources, which special-use addresses tend to be.

Which Proxy & VPN Signals Should Block a Signup?

ABDULLAH AFZAL — Tue, 18 Aug 2026 12:51:01 +0000

A proxy or VPN flag at signup is a signal, not a verdict. This guide maps each IP signal to a block, friction, or allow decision at account creation, so a single boolean does not end up quietly blocking real customers or waving real fraud through.

The mistake that runs through most fake-account defenses is treating "this IP is anonymized" as "this account is fraud." It isn't. A commercial VPN, a datacenter proxy, a residential proxy, a Tor exit, and an iCloud Private Relay connection are five different risk profiles, and two of them are things your best paying customers use every day. The decision you actually make at signup is per-signal, and it has three settings: allow, add friction, block.

TL;DR

Most anonymized traffic at signup earns friction, not a block. Reserve outright blocks for bots, known attackers, and stacked high-risk signals.
Never treat a relay as a VPN. iCloud Private Relay and Cloudflare WARP are widely used privacy services, and blocking their exit IPs outright can reject legitimate users.
Residential proxies are the hard case. The IP genuinely belongs to a consumer ISP, so IP data alone can flag it but cannot cleanly clear it. Pair it with non-IP signals before you block.
Use a single 0-100 threat score to pick the action, and per-detection confidence scores to decide how far to take it.
Run shadow mode first: log the score and the action you would have taken for two weeks, then set thresholds against real numbers, not guesses.

A proxy flag tells you an IP is anonymized; it does not tell you the person behind it is a fraudster. The job at signup is to route each signal to the right action. Bots and known attackers get blocked, VPNs and relays usually get allowed or lightly challenged, and residential proxies get friction until a second signal confirms intent. The rest of this is the per-signal matrix and the thresholds behind it.

The signup decision matrix

This is the reference. Each row is a signal you get back on an IP lookup, the action it usually justifies at account creation, and the legitimate user you would wrongly hit if you blocked on that signal alone.

Signal	Usual action at signup	Why	Who a hard block wrongly hits
`is_bot`, `is_known_attacker`	Block	Automation or a history of malicious activity. There is almost no legitimate signup reason to be either.	Rare. An occasional security scanner or a recycled IP with stale reputation.
`is_tor`	Step-up or block, by product	Strong anonymity with a high abuse rate. Fine to allow for a privacy tool, wrong to allow for a payments product.	Privacy-conscious users, journalists, people in censored regions.
`is_residential_proxy`	Friction or step-up. Rarely an IP-only block.	The address belongs to a real consumer ISP, so you cannot clear it on IP data alone.	A real household running a proxy SDK they forgot they installed; a shared home IP.
`is_proxy` (datacenter or commercial)	Friction; block on high confidence plus a raised score	Server-origin traffic at a human signup is unusual, but not always fraud.	A user behind a corporate egress that routes through a datacenter proxy.
`is_vpn`	Friction, not a block	Extremely common among legitimate privacy and corporate users.	Everyone on NordVPN, Surfshark, or a work VPN. That is a lot of people.
`is_relay` (iCloud Private Relay, WARP)	Allow or log. Do not treat as a VPN.	A privacy service used by legitimate Apple users, with no inherent indication of fraud.	iPhone users who have iCloud Private Relay enabled.
`is_cloud_provider`	Context. Friction only when paired with another flag.	Could be a scraper, could be a user on a cloud-hosted VPN.	Developers and privacy users on cloud egress.
`is_spam`	Friction or step-up	A spam history is a moderate signal, not a conviction.	Shared or recycled IPs that inherited a bad reputation.

The pattern to notice: only two rows are block-by-default. Everything else is friction or context, because the false-positive cost is real and the signals overlap. The same IP can be flagged VPN, proxy, and residential proxy at once, and the right response is driven by the combination and the score, not by any single true.

What each signal actually means at signup

Bots and known attackers

These are the clean blocks. is_bot marks automated behavior; is_known_attacker marks an IP with a history of brute force, credential stuffing, or vulnerability scanning. A human creating one account has no reason to trip either. If you block on anything at the IP layer, block on these, and log the rare false positive so you can spot a mislabeled range.

Tor exit nodes

is_tor is a product decision more than a fraud decision. Tor carries a high abuse rate, but it is also how some people access the internet safely. A privacy-forward tool might allow Tor signups with email verification. A payments product or a marketplace with promo credits probably sends Tor to step-up verification or blocks it. Pick the policy that matches what a fraudulent Tor signup would actually cost you, and say so in your own docs so support can explain it.

Residential proxies

This is the category that breaks blocklist-only defenses. A residential proxy routes traffic through egress points on real end-user devices whose IPs sit in address space allocated to consumer ISPs (security research on the residential-proxy ecosystem describes the model in detail). To your signup form, the request looks like an ordinary household on Comcast or BT, because at the network layer it is one.

That has a hard consequence: IP data can raise a flag on a known residential-proxy egress, but it cannot clear a residential IP the way it can clear a clean datacenter range, because the address is legitimately residential. So is_residential_proxy earns friction and a second look, not an automatic block. The second look is where non-IP signals carry the weight: email age, device consistency, and signup velocity from the same fingerprint. Anyone selling you "100% residential proxy detection" from IP data alone is overselling; the honest version is high-confidence flagging plus behavioral corroboration.

Datacenter and commercial proxies

is_proxy without the residential flag usually means a datacenter or commercial proxy: server-origin traffic. A person filling out a signup form from a datacenter IP is unusual enough to justify friction, and a high proxy_confidence_score stacked with a raised threat score is a reasonable block. The caveat sits right next to the rule: some corporate networks egress through commercial proxies, so confidence and score matter more than the bare boolean.

Commercial VPNs

is_vpn is the signal teams most often over-weight. Tens of millions of people run a VPN by default, for privacy, for work, or because their browser bundles one. Blocking VPN signups outright is a conversion tax you pay to catch a thin slice of fraud that better signals would catch anyway. Friction is almost always the right call: allow the signup, add a verification step, and let behavior downstream decide. Provider attribution helps here. A corporate VPN and a scraping network both set is_vpn, and naming the provider lets you write different rules for each instead of the same blunt block.

Relays: the false positive to stop making

If you take one thing from this guide, take this. is_relay covers iCloud Private Relay and services like Cloudflare WARP, and it is not a VPN in any sense that matters for fraud. Private Relay is available to iCloud+ subscribers who choose to enable it, which is a large share of iPhone traffic.

Treating relay traffic as VPN traffic and blocking it means turning away privacy-conscious Apple users at the door, and it is a common source of avoidable false positives. A separate relay flag exists precisely so you can allow these users while still challenging real VPN and proxy traffic. Allow, or log and move on.

Cloud provider IPs

is_cloud_provider on its own is weak. It could be a scraper running on a rented box, or a legitimate user whose VPN happens to exit through a cloud region. Treat it as context that sharpens other flags rather than a trigger on its own. Cloud plus bot plus a raised score is a block; cloud alone is a log line.

Turning scores into thresholds

Per-flag rules get you most of the way. A single aggregate score gets you a clean decision boundary. A composite threat_score from 0 to 100 rolls every signal into one number, and the documented action bands map directly onto the allow, friction, block model:

Threat score	Meaning	Signup action
1-19	Low observed risk	Allow with standard controls, log for pattern analysis
20-44	Use with context	Combine with device, behavior, velocity, or geo before acting
45-79	Elevated risk	Add friction: OTP, CAPTCHA, email verification, rate limiting, or a review queue
80-100	High risk	Block, hard challenge, or route to manual review

Two scores, two jobs. The threat_score picks the action band. The per-detection confidence scores, vpn_confidence_score and proxy_confidence_score, tell you how far to take that action. Medium-confidence VPN traffic in the 45-79 band gets a light challenge; a 99-confidence proxy detection stacked with attacker history in the 80-100 band gets blocked.

Here is the decision as code. It checks the strongest block signals first, allows relay traffic when no stronger risk signal is present, and then maps the remaining score bands to an action. It fails open, because a lookup timeout should not lock legitimate users out of your signup:

// Node.js 18+
const API_KEY = process.env.IPGEO_API_KEY;

// Returns "allow" | "friction" | "block". Fails open on any error.
async function signupAction(ip) {
  try {
    const res = await fetch(
      `https://api.ipgeolocation.io/v3/security?apiKey=${API_KEY}&ip=${encodeURIComponent(ip)}`,
      { signal: AbortSignal.timeout(1500) } // don't hang the signup flow
    );

    if (!res.ok) return "allow"; // fail open on API errors

    const security = (await res.json())?.security;
    if (!security) return "allow";

    const score = security.threat_score ?? 0;

    // Strong risk signals take precedence, even when the IP is also a relay.
    if (security.is_bot || security.is_known_attacker) return "block";

    if (score >= 80) return "block";

    // Relay alone is not a reason to challenge a legitimate signup.
    if (security.is_relay) return "allow";

    if (score >= 45) return "friction"; // OTP, CAPTCHA, email verification

    if (score >= 20 && security.is_residential_proxy) {
      return "friction";
    }

    return "allow";
  } catch {
    // Timeout, network error, or malformed response: let signup continue.
    return "allow";
  }
}

The fail open choice is deliberate and worth stating explicitly: if the risk lookup is unavailable, blocking every signup is worse than letting a few risky ones through to a later layer. If your product genuinely needs fail-closed at signup, that is a real choice too, but make it on purpose.

The false-positive costs you're trading against

Every block threshold buys fraud reduction with some rate of wrongly rejected real users. You should know who those users are before you set the dial, so this is the qualitative side of the ledger:

The corporate VPN user. Signs up from a work laptop that routes everything through the company VPN. Sets is_vpn. Blocking them means rejecting exactly the professional buyers a B2B product wants.
The traveler. On hotel or airport wifi with a personal VPN switched on, because that is the responsible thing to do on public networks. Blocking them punishes good security hygiene.
The iPhone user. Has iCloud Private Relay enabled, so their traffic sets is_relay. If your rules fold relay into VPN, you risk blocking a legitimate privacy-conscious user.
The real household behind a proxy SDK. Installed a free app that quietly enrolled their connection into a residential proxy network. Their signup is genuine even though the IP is flagged. This is why residential-proxy blocks need a second signal.

These are all realistic sources of false positives. They are ordinary people, and each one is a paying customer you turned away if a single anonymization flag is enough to block. That is the whole argument for friction over blocking on the middle-risk signals.

Where these signals come from

You get flags, scores, and provider names from an IP security lookup. IPQualityScore, Spur, and proxycheck all return proxy and VPN signals; I am using the IP Security API from IPGeolocation for the examples because it splits the relay flag out from VPN, names the provider behind a detection, and returns the 0-100 threat score the bands above are built on. Security fields are on the paid plans, starting at $19/month; the free plan returns geolocation but not the security object.

A single call to the dedicated /v3/security endpoint returns the full shape. This is a real flagged IP, not a documentation placeholder, so the payload matches what you would actually get back:

{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": ["Zyte Proxy"],
    "proxy_confidence_score": 90,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": ["Nord VPN"],
    "vpn_confidence_score": 99,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A."
  }
}

Three fields do the heavy lifting for signup decisions. threat_score picks the action band. is_relay, is_residential_proxy, and the provider-name arrays let you separate the risk profiles the matrix treats differently. And proxy_last_seen and vpn_last_seen date each detection, so an exit node seen this week can be weighted differently from one last observed months ago. For batch backfills over existing users, the same data is available in bulk at up to 50,000 IPs per request.

A starter policy you can ship

You do not need to get the thresholds perfect on day one. You need to stop guessing.

Shadow mode for two weeks. Log the threat_score, the flags, and the action your rules would have taken, but do not block anyone yet. This tells you how much of your real signup traffic each band actually catches.
Set the block line high. Start by hard-blocking only the 80-100 band plus is_bot and is_known_attacker. That catches the worst traffic with the lowest false-positive risk.
Route the middle to friction. Send 45-79 to email verification or a light challenge. Send residential-proxy flags in the 20-44 band to the same friction, not a block.
Let clean relays and low scores through. Allow relay traffic when no stronger block signal is present, and allow anything under 20 with standard controls.
Watch the false-block rate. The number that tells you a threshold is too tight is not caught fraud, it is support tickets from real users who could not sign up. Tune against that.

A few things that trip people up

is_proxy and is_residential_proxy are not the same decision. The first covers datacenter and commercial proxies, where a block on high confidence is defensible. The second covers consumer-ISP proxies, where an IP-only block is not, because the address is genuinely residential. Read them separately.

A high threat score is a reason to act, not a reason to block. The 45-79 band is deliberately the friction band. If you find yourself blocking there, you are trading conversion for a marginal fraud reduction that a verification step would have caught anyway.

Relay is not VPN. It keeps coming up because so many defenses get it wrong. If your rules do not have a separate branch for is_relay, add one before you touch anything else.

Shadow mode is not optional busywork. The teams that block real customers are almost always the ones that set thresholds from intuition instead of from two weeks of their own logged traffic.

Start in shadow mode, block only the top band and the clean bot signals, and send the middle to friction. Then tune against your false-block rate rather than your caught-fraud count, because the false blocks are the ones that cost you customers you will never hear from again.

Classify an IP by ASN Type: Hosting, Business, ISP

ABDULLAH AFZAL — Thu, 13 Aug 2026 10:35:25 +0000

An IP address does not tell you what kind of network it belongs to. The autonomous system behind it does. Every routable IP sits inside an ASN, and that ASN has a type: hosting, business, education, government, or a consumer ISP. One lookup returns it, and that single field sorts almost any address into datacenter traffic, an organization, or a real person on a home connection.

Almost. There are a few cases where ASN type alone points you toward the wrong conclusion, including one that matters particularly for fraud and abuse work. We'll get to them.

TL;DR

Every public IP belongs to an ASN, and the ASN carries a type field: ISP, HOSTING, BUSINESS, EDUCATION, or GOVERNMENT.
HOSTING means a datacenter or cloud provider. ISP means a consumer access network. BUSINESS, EDUCATION, and GOVERNMENT are organizations on their own address space.
A single call to the dedicated ASN endpoint returns the type and can also include routing data such as routes, upstreams, downstreams, and peers for additional context.
The type describes the network operator. When a business runs on rented cloud space, the operator is a hosting company but the tenant is a business. Reading only the ASN type mislabels them.

The rest of this is the matrix, a classifier you can paste in, and the four places the type field stops being enough.

The ASN-type classification matrix

Here is the whole idea in one table. Look up the ASN for an address, read type, map it to a bucket.

`asn.type`	What it is	Example ASN	Treat traffic as
`HOSTING`	Cloud/datacenter provider. Servers live here.	AS24940 (Hetzner)	Datacenter. Bots, scrapers, and VPN exits cluster here.
`ISP`	Primarily an end-user access network, including fixed-line and mobile ISP space.	AS1257 (Tele2)	Consumer/access network. Lower baseline infrastructure suspicion, but not proof of a human user.
`BUSINESS`	A company operating its own address space.	AS1 (Level 3)	Organization. Office egress, corporate VPNs, SaaS backends.
`EDUCATION`	Universities and research networks.	AS12 (New York University)	Organization. Campus and lab traffic.
`GOVERNMENT`	Public-sector networks.	(varies by RIR)	Organization.

The three buckets developers usually care about, hosting, business, and consumer, come straight out of this. HOSTING is your datacenter bucket. ISP is your consumer bucket. BUSINESS, EDUCATION, and GOVERNMENT are three flavors of the same "this is an organization, not a home user and not a rented server" bucket, and you can collapse them if your logic doesn't need the distinction.

What makes this reliable is that ASN type is a property of the network operator, not a guess from the IP number. You cannot look at 49.12.0.0 and know it's a datacenter. You look up its ASN, see AS24940 Hetzner tagged HOSTING, and now you know.

One ASN lookup, one classification

The ASN type field is available on the dedicated ASN endpoint and in the main geolocation response. The dedicated ASN API is the cleaner choice when classification is all you want, because it returns the ASN record and nothing else, and it takes either an IP or an AS number.

The response and the type field

A lookup by IP returns the ASN that announces it:

curl -X GET 'https://api.ipgeolocation.io/v3/asn?apiKey=API_KEY&ip=49.12.0.0'

{
  "ip": "49.12.0.0",
  "asn": {
    "as_number": "AS24940",
    "organization": "Hetzner Online GmbH",
    "country": "DE",
    "type": "HOSTING",
    "domain": "hetzner.com",
    "date_allocated": "2002-06-03",
    "asn_name": "HETZNER-AS",
    "allocation_status": "ASSIGNED",
    "num_of_ipv4_routes": "84",
    "num_of_ipv6_routes": "6",
    "rir": "RIPE"
  }
}

type is HOSTING, so 49.12.0.0 is datacenter space. The type field requires a paid plan; the free tier returns the AS number, organization, and country but not the classification. Everything else in this guide keys off type, so that's the field to check your plan for.

Lookup by IP or by AS number

You can classify a single address, or a whole network. Passing an AS number instead of an IP skips the IP-to-ASN step and returns the same record:

curl -X GET 'https://api.ipgeolocation.io/v3/asn?apiKey=API_KEY&asn=1'

That returns AS1 (Level 3) as BUSINESS. This is useful when you already have the ASN from your logs or your CDN and just want its classification, or when you're building a static allowlist of, say, every ASN a partner operates. When you look up by asn, the response drops the top-level ip field, since there's no single address to report.

A classifier you can copy

Here's the logic wrapped so it returns a bucket and never throws on a bad response.

import os
import requests

IPGEO_API_KEY = os.environ.get("IPGEO_API_KEY")

# ASN type values that mean "an organization runs this," not a home user
# and not a rented server. Collapse them if your logic doesn't need the split.
ORG_TYPES = {"BUSINESS", "EDUCATION", "GOVERNMENT"}


def classify_ip(ip):
    """Return 'hosting', 'consumer', 'organization', or 'unknown' for an IP.

    Never raises on a network or parse error; callers get 'unknown' and can
    decide their own fallback (fail-open vs fail-closed) from there.
    """
    try:
        resp = requests.get(
            "https://api.ipgeolocation.io/v3/asn",
            params={"apiKey": IPGEO_API_KEY, "ip": ip},
            # Short timeouts: a classification call should never hang a request path.
            timeout=(1.0, 1.5),
        )
        resp.raise_for_status()
    except requests.RequestException as exc:
        # Log and fall back. Don't let an IP lookup take down the caller.
        print(f"ASN lookup failed for {ip}: {exc}")
        return "unknown"

    # .get() the whole way down: any field can be absent or empty.
    try:
        data = resp.json()
    except ValueError as exc:
        print(f"Invalid ASN response for {ip}: {exc}")
        return "unknown"

    asn_type = (data.get("asn") or {}).get("type") or ""

    if asn_type == "HOSTING":
        return "hosting"
    if asn_type == "ISP":
        return "consumer"
    if asn_type in ORG_TYPES:
        return "organization"
    return "unknown"  # empty type, unrecognized value, or bogon range


if __name__ == "__main__":
    for ip in ("49.12.0.0", "8.8.8.8", "91.128.103.196"):
        print(ip, "->", classify_ip(ip))

Two decisions worth calling out. The timeout is deliberately tight because an ASN lookup usually sits on a request path (a signup, a login, a checkout), and a slow classifier is worse than no classifier. And an empty or unrecognized type returns unknown rather than a guess, so your downstream rules can treat "we don't know" differently from "we know it's a home user."

The same shape in JavaScript, using fetch with an abort timeout:

const IPGEO_API_KEY = process.env.IPGEO_API_KEY;

// Organization ASN types, kept separate from hosting and consumer.
const ORG_TYPES = new Set(["BUSINESS", "EDUCATION", "GOVERNMENT"]);

async function classifyIp(ip) {
  const url =
    `https://api.ipgeolocation.io/v3/asn` +
    `?apiKey=${IPGEO_API_KEY}&ip=${encodeURIComponent(ip)}`;

  try {
    const resp = await fetch(url, {
      // Abort before this ever stalls a login or checkout flow.
      signal: AbortSignal.timeout(1500),
    });
    if (!resp.ok) throw new Error(`HTTP ${resp.status}`);

    const data = await resp.json();
    // Optional chaining the whole way: asn or type may be missing.
    const asnType = data?.asn?.type ?? "";

    if (asnType === "HOSTING") return "hosting";
    if (asnType === "ISP") return "consumer";
    if (ORG_TYPES.has(asnType)) return "organization";
    return "unknown";
  } catch (err) {
    // Network error, timeout, or bad JSON: fall back, don't throw.
    console.error(`ASN lookup failed for ${ip}: ${err.message}`);
    return "unknown";
  }
}

Both return one of four strings. What you do with them is your policy, not the classifier's job: most teams pass consumer, add friction to hosting, and treat organization as low-risk-but-log. The point is that the branching lives in one place, keyed on one field.

One operational note: If your logs or edge provider already give you the ASN, cache classification by AS number. If all you have is an IP, you still need an IP-to-ASN mapping first, so in a higher-volume implementation cache both the IP/prefix-to-ASN mapping and the ASN-to-type classification.

When ASN type is not enough

The matrix handles the large majority of addresses. Then there are four cases where reading type alone can give you an incomplete or misleading answer. These are the parts most guides skip, and they're the reason the classification isn't a one-liner.

Subleased cloud: the operator is hosting, the tenant is a business

This is the important one. A company rents servers or address space from a cloud provider and runs its own service on it. The ASN belongs to the hosting company, so asn.type reads HOSTING, but the actual occupant is a business. If you classify on ASN type alone, you file a legitimate company under "datacenter" and treat its traffic as suspect.

This is exactly why the company object in the main geolocation response is worth pulling alongside the ASN. The company object can identify a more specific organization associated with the IP range than the ASN operator, and it carries its own type. Look at 2.56.188.34:

curl -X GET 'https://api.ipgeolocation.io/v3/ipgeo?apiKey=API_KEY&ip=2.56.188.34'

{
  "asn": {
    "as_number": "AS62240",
    "organization": "Clouvider Limited",
    "type": "HOSTING",
    "domain": "clouvider.net"
  },
  "company": {
    "name": "Packethub S.A.",
    "type": "BUSINESS",
    "domain": "packethub.com"
  }
}

The ASN registrant is Clouvider, a hosting provider, tagged HOSTING. The company mapped to this address is Packethub, tagged BUSINESS. Same IP, two different answers, and the company result gives you more specific context for "who is associated with this IP". When company.type and asn.type differ, the company field can give you useful context about who is associated with that particular address range, while the ASN still tells you about the underlying network. Reading both, and knowing which to trust when they split, is the difference between a classifier that works on cloud-hosted businesses and one that flags every startup running on a VPS.

Corporate VPN: hosting-looking, entirely legitimate

An employee connecting through their company's VPN often egresses from a datacenter or a business ASN, not from their home ISP. The ASN type will say HOSTING or BUSINESS, and both are technically correct: the traffic really is leaving a server. But the human behind it is a legitimate employee, not a bot. If your rules hard-block hosting IPs, you've just locked out everyone on the corporate VPN. Weight the ASN type against account history and behavior rather than blocking on it outright.

Residential proxy: the one that reads consumer and isn't

Here is the case that runs opposite to the subleased-cloud one. A residential proxy routes traffic through a real home connection, so the exit IP sits on a consumer ISP and asn.type reads ISP. Everything about the network says "home user." But the traffic is being relayed on behalf of someone else, often a scraper or a fraud operation renting access to that household's connection. ASN type cannot see this, because at the network layer it genuinely is a consumer ISP. Catching it needs a dedicated signal: if you also run the security module, the is_residential_proxy flag is what flips an ISP-typed address from "trust" to "inspect." Without that flag, a residential proxy is invisible to ASN-type classification, which is worth knowing before you lean on the consumer bucket for anything security-sensitive.

CDN and anycast: the ASN bucket needs more context

Some addresses aren't a datacenter, a business, or a home. They're anycast IPs announced from many locations at once, fronting a CDN or a large platform. Akamai, Cloudflare, and the big content networks fall here. The ASN type may say HOSTING or BUSINESS, but treating the address as either misses that it's infrastructure serving content, not an origin you can reason about as a single user or server.

Treat is_anycast as an additional flag, not another ASN bucket. The ASN type can still describe the operator, but an anycast IP should not be interpreted as one physical server or one geographic origin because the same address may be served from multiple locations.

Corroborating with ASN topology

The ASN endpoint returns more than a label. Pass include=peers,downstreams,upstreams,routes,whois_response and you get the network's routing shape, which is a useful sanity check when a type value surprises you.

curl -X GET 'https://api.ipgeolocation.io/v3/asn?apiKey=API_KEY&asn=12&include=upstreams,downstreams,routes'

For AS12 (NYU, EDUCATION) the response includes its announced routes, its upstreams (transit providers like GTT and Zayo), and its downstreams (customer networks like NYU Langone Health). The signals that corroborate a type:

Downstreams. An ASN with customer networks hanging off it is transit or a large operator, not a home connection.
Upstreams. Who an ASN buys connectivity from tells you where it sits in the hierarchy.

You don't need this for routine classification, and pulling it on every request is wasteful. It earns its place when you're building the allowlist, auditing a surprising result, or investigating a specific ASN by hand. The raw whois_response is there too, but treat it as a last resort: it's an unstructured text blob meant for human reading, not something to parse in code. For routine classification, the structured fields are easier to work with. Keep whois_response for deeper registration details or manual investigation.

A few extra notes that don't need their own sections. IPv6 uses the same workflow: resolve the IPv6 address to its origin ASN, then classify that ASN in the same way. Bogon and private ranges have no public ASN, so a lookup on 10.0.0.0 or a documentation range returns an error rather than a type, which is why the classifier treats anything without a clean type as unknown. And the ASN type is stable over days and weeks, not seconds, so caching aggressively by AS number is safe.

Where this leaves you

Classification by ASN type is one field and one lookup for the common case, and a second field, company.type, for the case where a business runs on rented infrastructure. Wire the classifier onto the paths where the answer changes what you do, signup, login, checkout, and cache by AS number when you already have the ASN, or cache both IP-to-ASN and ASN-to-type mappings at higher volume. Keep the four edge cases in mind before you turn a bucket into a hard block: a hosting label can be a corporate VPN, a consumer label can be a residential proxy, and an anycast address isn't really any of the three. The type tells you what the network is. What you do with that is your call to make, and it should almost always be scoring, not blocking.

Turn a List of IPs Into Location Data in Google Sheets

ABDULLAH AFZAL — Wed, 12 Aug 2026 11:15:16 +0000

You have a Google Sheets file full of IP addresses. Maybe they came from server access logs, a list of login attempts, ad-click exports, or a fraud review queue. You need to know where those IPs are, what network they belong to, and whether any of them are running through a VPN or proxy.

You could paste them into an online lookup tool one by one. Or you could turn your Google Sheet into a geo-enrichment pipeline that resolves hundreds of IPs with a formula.

This guide covers the setup (about 10 minutes of copy-paste), a formula reference you can bookmark, and four practical workflows for doing something useful with the enriched data.

TL;DR

One Apps Script integration turns Google Sheets into a bulk IP enrichment tool. No add-ons, no code to write.
Formulas like =IPGEO(A2, "location.country_name") fill in country, city, timezone, currency, ASN, VPN status, proxy detection, and threat scores.
=IPGEO_BULK(A2:A500, "location.country_name") processes large lists in a single call instead of one formula per row.
All you need is a free API key. Sign up, paste the key once, and the formulas work immediately.
The full formula reference and source code live at the GitHub repository.

The short version: paste IPs in column A, use formulas in columns B onward, and the sheet fills itself with location and security data. The rest of this guide explains which formulas to use, when, and what to do with the output.

To geolocate IP addresses in Google Sheets, add the IPGeolocation Apps Script integration, store your API key once, and use custom formulas such as IPGEO for individual lookups or IPGEO_BULK for an IP range.

How to set it up

Several IP geolocation APIs work with Google Sheets through Apps Script. IPGeolocation, ipinfo, ip-api, and MaxMind GeoIP2 all return similar core data for country-level lookups. This guide uses IPGeolocation because it ships a ready-made Google Sheets integration with built-in formulas, bulk processing, and security signals, so you skip the Apps Script plumbing entirely.

The setup takes about 10 minutes:

Open your Google Sheet. Go to Extensions > Apps Script.
In the Apps Script editor, delete the starter code in Code.gs. Paste the full contents of Code.gs from the GitHub repository.
Save the project. Name it something like "IPGeolocation.io for Google Sheets."
In the function dropdown near the toolbar, select setIpGeolocationApiKey and click Run. Google will ask you to approve permissions (this is normal). A popup will ask for your API key. Paste it and click OK.
Go back to your spreadsheet tab and refresh the page. You should see a new IPGeolocation.io menu at the top. Sign up for a free API key if you don't have one. The key connects the sheet to the service and you only set it once per spreadsheet.

Test it by typing this in any empty cell:

=IPGEO("8.8.8.8", "location.country_name")

If it returns "United States," you're set.

Tip: If the IPGeolocation.io menu doesn't appear after refreshing, open Apps Script again and confirm the code saved correctly. A second refresh usually fixes it.

IP enrichment formulas

This is the table to bookmark. Every formula takes an IP address (or a cell reference like A2) as the first argument, a field path as the second, and optionally "security" as the third for security-related fields.

Location and network

What you need	Formula	Example output
Country name	`=IPGEO(A2, "location.country_name")`	Germany
Country code (2-letter)	`=IPGEO(A2, "location.country_code2")`	DE
City	`=IPGEO(A2, "location.city")`	Berlin
State or province	`=IPGEO(A2, "location.state_prov")`	Berlin
Latitude	`=IPGEO(A2, "location.latitude")`	52.5200
Longitude	`=IPGEO(A2, "location.longitude")`	13.4050
Timezone	`=IPGEO(A2, "time_zone.name")`	Europe/Berlin
Currency code	`=IPGEO(A2, "currency.code")`	EUR
ASN number	`=IPGEO(A2, "asn.as_number")`	AS13335
ASN organization	`=IPGEO(A2, "asn.organization")`	Cloudflare, Inc.

Security signals

What you need	Formula	Example output
VPN detected	`=IPGEO(A2, "security.is_vpn", "security")`	TRUE
Proxy detected	`=IPGEO(A2, "security.is_proxy", "security")`	FALSE
Tor exit node	`=IPGEO(A2, "security.is_tor", "security")`	FALSE
Bot detected	`=IPGEO(A2, "security.is_bot", "security")`	FALSE
Cloud provider	`=IPGEO(A2, "security.is_cloud_provider", "security")`	TRUE
Threat score (0-100)	`=IPGEO(A2, "security.threat_score", "security")`	72

Security formulas need that third "security" parameter. Without it, they return blank. There's also a dedicated =IPSECURITY(A2, "security.threat_score") formula that calls the security endpoint directly.

Shortcuts and bulk

Formula	What it does
`=IPGEO_COUNTRY(A2)`	Returns country name (shortcut)
`=IPGEO_CITY(A2)`	Returns city name (shortcut)
`=IPGEO_TIMEZONE(A2)`	Returns timezone name (shortcut)
`=IPGEO_ASN_ORG(A2)`	Returns ASN organization (shortcut)
`=IPGEO_IS_VPN(A2)`	Returns VPN detection (shortcut)
`=IPGEO_THREAT_SCORE(A2)`	Returns threat score (shortcut)
`=IPGEO_BULK(A2:A500, "location.country_name")`	Fills an entire column from a range
`=IPGEO_JSON(A2)`	Returns the raw JSON response (debugging)

IPGEO_BULK is the one to reach for when you have more than a few dozen IPs. Instead of dragging a formula down 500 rows (which fires 500 individual API calls), it processes the whole range in a single batch. Faster, fewer API calls, and the sheet stays responsive.

Note: Keep bulk ranges contiguous. IPGEO_BULK skips empty cells, so remove blank rows from the input range before running a bulk lookup to keep results aligned with the original IPs.

Four workflows that make the data useful

Looking up location data is the starting point. The value comes from what you do with it after the columns fill in.

Fraud and login review

Export login IPs from your auth system, paste them into column A, and bulk-enrich with country, city, VPN status, proxy status, and threat score. Then put conditional formatting to work:

Color-scale the threat score column. Green for 0-19, yellow for 20-59, red for 60-100. Suspicious rows stand out immediately without reading a single cell.
Filter by VPN. Show only TRUE rows. These are logins happening through VPN connections, which might be normal for remote employees or worth investigating for consumer accounts.
Cross-check country against expected geography. If your users are mostly in the US and Germany, a cluster of logins from a country you don't serve is worth a second look.

Marketing campaign analysis

If you capture IP addresses alongside campaign clicks or conversions, enrich them to answer questions your analytics dashboard can't:

Country and city breakdown that doesn't depend on the user's browser locale settings. IP-level country data is independent of what the user tells your form.
Bot and cloud-provider signals: A concentration of clicks from cloud infrastructure is worth investigating, especially when it overlaps with bot, proxy, known-attacker, or elevated threat signals. A cloud-provider flag by itself is context, not proof of fraudulent traffic.
Timezone grouping for scheduling. Pivot the enriched data by timezone to see when your actual audience is active, not when your analytics platform thinks they are. For a campaign with 2,000 clicks, =IPGEO_BULK(A2:A2001, "location.country_name") fills the country column in one call. Add a pivot table grouped by country, and you have a geographic distribution in under a minute.

Server log enrichment

Nginx and Apache access logs give you IP addresses, timestamps, URLs, and status codes. What they don't give you is who those IPs belong to.

Paste the IP column into a sheet. Enrich it with asn.organization and location.country_name, then pivot by ASN organization. A large share of requests may come from a relatively small set of networks. Some may be consumer ISPs, some cloud or hosting providers, some CDN infrastructure, and some networks you already recognize.

If an ASN you don't recognize is hammering a specific endpoint, that's a pattern worth investigating before it becomes an incident.

The sheet doesn't replace your monitoring stack, but it gives operations and security teams a quick way to triage access patterns without writing queries against a log aggregator. When someone asks "where is this traffic coming from," a pivot table by ASN answers it in a way that a raw IP list never will.

Compliance and access auditing

For teams with geographic access policies (data residency requirements, export controls, regional licensing), IP enrichment turns an access log into a compliance report.

The workflow: pull login records for a review period, enrich with country, and filter for logins originating outside your approved country list. If your policy says "US and EU only" and you see logins from a country not on that list, that's a finding that needs documentation. Adding the VPN column helps contextualize findings: a login from an unexpected country through a VPN has a different risk profile than one from a residential ISP in that same country.

This isn't a substitute for proper access controls. But when the auditor asks "were there any access events from outside approved regions during Q2," this is how you answer the question in 15 minutes instead of filing a ticket with engineering.

Handling larger datasets

Individual IPGEO formulas work fine for a few dozen rows. Beyond that, switch to IPGEO_BULK:

=IPGEO_BULK(A2:A1000, "location.country_name")

This processes the range as a single batch. The underlying API accepts up to 50,000 IPs per request, although practical Google Sheets batch sizes can be lower because Apps Script has its own execution and caching limits.

A few things to know about scale:

Caching. Results are cached for six hours inside Google Sheets using Apps Script's built-in cache service. If you look up the same IP twice within that window, the second call doesn't cost an API request.

Free tier quota. The free plan gives you 1,000 requests per day across all APIs. Bogon IPs (private ranges like 10.x.x.x, 192.168.x.x) don't count against quota, so dirty lists with internal IPs won't burn through your allowance.

Sheet performance. Google Sheets has its own execution limits for custom functions. If the sheet feels sluggish, switching from individual formulas to IPGEO_BULK is the single biggest performance improvement. The README's troubleshooting section covers other common slowdown causes.

What to watch out for

IP geolocation is approximate. Across IPGeolocation's dataset, country-level accuracy is 99%+, region/state is 90%+, and city-level is 85%+. City results should still be treated as estimates rather than exact positions, especially on mobile networks, VPNs, proxies, and networks where traffic exits far from the user.

VPN and proxy detection has false positives. A corporate VPN exit in another country looks identical to a privacy VPN from the network's perspective. Context matters. If your entire user base is enterprise employees, VPN flags will be noisy. Use threat_score thresholds rather than binary VPN flags for decision-making.

Google Sheets isn't a production system. This pipeline works well for periodic batch analysis, ad-hoc investigations, and generating reports. It's not a replacement for real-time API integration in your application code. For production use (per-request enrichment, middleware, real-time blocking), call the API from your backend.

The full formula reference and source code live at the GitHub repository, including a suggested five-tab template layout and additional troubleshooting. If a formula returns blank, the JSON dump formula (=IPGEO_JSON(A2)) shows the raw API response so you can check whether a field exists for that IP.

What's next

Drop the script into a sheet, paste your IPs, and run a bulk enrichment. Most people start with the location formulas and add security columns once they see how fast it fills in.

Automate IP Abuse Reports Into Your Ticket Queue

ABDULLAH AFZAL — Tue, 11 Aug 2026 11:35:45 +0000

Automating abuse reports for attacking IPs starts with a step most incident-response scripts skip: finding the network operator responsible for the address. Blocking the IP stops traffic from that address, but a well-evidenced report gives the operator a chance to investigate the system behind it and take action.

Doing that manually means looking up registration data, finding the right abuse contact, collecting timestamps and logs, and copying everything into a ticket or email. At any meaningful volume, that process gets skipped.

This guide builds a small pipeline to handle the repetitive parts: resolve the abuse contact for an offending IP, group repeated events by the abuse-handling network, and create a ticket with the contact details and evidence ready for human review. The raw lookup starts with curl, the complete workflow is implemented in Python, and the resolver is also shown in Node.js.

TL;DR

Blocking an abusive IP stops it hitting you. Reporting it gives the responsible network operator the evidence needed to investigate the source and take action.
The abuse contact is the operator's registered abuse desk from registry records, not the attacker. One call resolves it: GET /v3/abuse?ip=....
The response returns emails and phone_numbers as arrays, plus the operator's name, organization, route (the CIDR they answer for), country, and postal address.
Dedupe on route, not just the individual IP. Multiple abusive IPs can resolve to the same operator and abuse-handling network, so grouping them prevents your queue from filling with near-identical tickets.
Open a ticket for a human to review and send. Never auto-email abuse desks: log triggers include spoofed sources, and machine-gunning operators burns your sender reputation.
Fail open. A lookup or ticket failure should log and move on, never block your request path.

The pipeline is three steps: resolve the abuse contact for the offending IP, dedupe by the network route so one attacker isn't hundreds of tickets, and open a ticket with the contact and evidence attached. The code below is production-shaped, not a happy-path snippet.

Abuse reputation vs operator reporting: two different jobs

People conflate two actions that do different things.

The first is reporting the IP to a community blocklist like AbuseIPDB, usually wired through Fail2Ban. That raises the IP's reputation score so other people's firewalls treat it with suspicion. Useful, but it does nothing to the source. The attacker keeps their box.

The second is telling the operator that owns the IP range. IP address allocations are registered through one of the five Regional Internet Registries (ARIN, RIPE, APNIC, LACNIC, AFRINIC), and registry records commonly include an abuse or incident-response contact for the responsible operator. That contact is a role mailbox, abuse@ by convention, defined back in RFC 2142 as the address for "inappropriate public behaviour." Send evidence there and the operator can investigate, warn, or suspend the customer running the attack.

One point the registries make and worth repeating: the abuse contact is the network operator, not the abuser. You are asking the landlord to deal with the tenant. This tutorial automates the second job. The first is a one-liner you probably already have.

What one lookup returns

You can resolve the contact from raw WHOIS or RDAP yourself, and if you enjoy parsing free-text remarks: fields across five registries with different formats, go for it.

A lookup API flattens that into consistent JSON. IPGeolocation, IPinfo, and IPLocate all expose one; ip-api does not. I'll use IPGeolocation's dedicated endpoint here because it returns the parsed abuse object in a single call and normalizes the registry differences.

Grab a key and the raw call is one line:

curl -s -X GET \
  'https://api.ipgeolocation.io/v3/abuse?apiKey=API_KEY&ip=49.12.0.0'

For 49.12.0.0, an address in a Hetzner allocation, the response is:

{
  "ip": "49.12.0.0",
  "abuse": {
    "route": "49.12.0.0/20",
    "country": "DE",
    "name": "Hetzner Online GmbH - Contact Role",
    "organization": "ORG-HOA1-RIPE",
    "kind": "group",
    "address": "Hetzner Online GmbH\nIndustriestrasse 25\nD-91710 Gunzenhausen\nGermany",
    "emails": [
      "abuse@hetzner.com"
    ],
    "phone_numbers": [
      "+49 9831 505-3",
      " +49 9831 505-0"
    ]
  }
}

Eight fields, and each one matters when you build the ticket. route is the CIDR the desk answers for, which is your dedupe key. emails and phone_numbers are arrays, so code that assumes a string will break. kind is group or individual. organization can be an empty string on some ranges. And look at the second phone number: " +49 9831 505-0" has a stray leading space, and the address carries literal \n line breaks. Registry data is messy. Your code cleans it, or your tickets look broken.

Step 1: Resolve the abuse contact

Here's the resolver in Python. It fails open on purpose, returning None for anything it can't handle. Keep abuse reporting completely outside your application's request path. Run it from a worker, queue consumer, or detector action so an API, Redis, or ticketing outage cannot affect user traffic.

import os
import logging
import requests  # pip install requests

log = logging.getLogger("abuse_pipeline")

IPGEO_API_KEY = os.environ.get("IPGEO_API_KEY")
ABUSE_URL = "https://api.ipgeolocation.io/v3/abuse"

def resolve_abuse_contact(ip):
    """Resolve the operator's abuse contact for `ip`, or None if it can't be
    resolved. Fails open: reporting is a background task and must never block
    the caller's request path."""
    if not IPGEO_API_KEY:
        log.error("IPGEO_API_KEY is not set")
        return None
    try:
        # (connect 1s, read 1.5s). Reporting isn't latency-critical, but you
        # still don't want a hung socket per detected event.
        resp = requests.get(
            ABUSE_URL,
            params={"apiKey": IPGEO_API_KEY, "ip": ip},
            timeout=(1.0, 1.5),
        )
    except requests.RequestException as exc:
        log.warning("Abuse lookup failed for %s: %s", ip, exc)
        return None

    if resp.status_code == 423:
        # Bogon or private IP. Nothing to report, and your detector probably
        # shouldn't have flagged an RFC 1918 address in the first place.
        log.info("Skipping bogon/private IP %s", ip)
        return None
    if resp.status_code == 401:
        log.error("Abuse endpoint returned 401; check the API key.")
        return None
    if resp.status_code == 429:
        log.warning("Rate limited on abuse lookups; back off and retry later")
        return None
    if resp.status_code != 200:
        log.warning("Abuse lookup for %s returned HTTP %s", ip, resp.status_code)
        return None

    try:
        payload = resp.json()
    except ValueError as exc:
        log.warning("Invalid JSON from abuse lookup for %s: %s", ip, exc)
        return None

    abuse = (payload or {}).get("abuse") or {}
    emails = abuse.get("emails") or []
    if not emails:
        # No registered abuse address. Rare, but real on some ranges.
        log.info("No abuse email for %s (%s)", ip, abuse.get("route"))
        return None

    return {
        "route": abuse.get("route"),
        "country": abuse.get("country"),
        "org": abuse.get("organization") or abuse.get("name") or "unknown operator",
        "emails": emails,
        "phones": [p.strip() for p in (abuse.get("phone_numbers") or [])],
        "address": (abuse.get("address") or "").replace("\n", ", "),
    }

The status-code handling isn't padding. 423 is a bogon or private IP, 401 is a free key hitting a paid endpoint, 429 is your rate limit. Each one is a different decision, and collapsing them into a bare except hides the one you actually need to act on. The .strip() on phones and the newline replace on the address are there because of the exact mess you saw in the payload above.

The same thing in Node. Node 18+ has global fetch, so no dependency:

const IPGEO_API_KEY = process.env.IPGEO_API_KEY;
const ABUSE_URL = "https://api.ipgeolocation.io/v3/abuse";

async function resolveAbuseContact(ip) {
  // Fails open: returns null on any problem so the caller keeps running.
  if (!IPGEO_API_KEY) {
    console.error("IPGEO_API_KEY is not set");
    return null;
  }

  const url = `${ABUSE_URL}?apiKey=${IPGEO_API_KEY}&ip=${encodeURIComponent(ip)}`;

  let resp;
  try {
    // Abort after 1.5s so a slow lookup never wedges the event loop.
    resp = await fetch(url, { signal: AbortSignal.timeout(1500) });
  } catch (err) {
    console.warn(`Abuse lookup failed for ${ip}: ${err.message}`);
    return null;
  }

  if (resp.status === 423) return null; // bogon / private IP
  if (resp.status === 401) {
    console.error("Abuse endpoint returned 401; check the API key.");
    return null;
  }
  if (resp.status === 429) {
    console.warn("Rate limited on abuse lookups; back off and retry later");
    return null;
  }
  if (!resp.ok) {
    console.warn(`Abuse lookup for ${ip} returned HTTP ${resp.status}`);
    return null;
  }

  let payload;
  try {
      payload = await resp.json();
  } catch (err) {
      console.warn(`Invalid JSON from abuse lookup for ${ip}: ${err.message}`);
      return null;
  }

  const abuse = payload?.abuse ?? {};
  const emails = abuse.emails ?? [];
  if (emails.length === 0) return null; // no registered abuse desk

  return {
    route: abuse.route,
    country: abuse.country,
    org: abuse.organization || abuse.name || "unknown operator",
    emails,
    phones: (abuse.phone_numbers ?? []).map((p) => p.trim()),
    address: (abuse.address ?? "").replace(/\n/g, ", "),
  };
}

Both return a small normalized object or nothing. Everything downstream can trust the shape.

Step 2: Dedupe by route, not by IP

This is the step every other guide misses, and it's the one that decides whether your queue stays usable.

A single attacker sitting on a hosting provider rarely stays on one IP. They rotate across the block. If you dedupe on the IP, a scanner walking 49.12.0.5, 49.12.0.6, 49.12.0.7 opens a fresh ticket every hop, all pointing at the same Hetzner abuse desk. The desk gets 200 near-identical emails, ignores all of them, and your queue is noise.

Dedupe on route instead. The abuse contact answers for the whole CIDR, so one ticket per route per window is the right resolution. Redis makes it atomic:

import redis  # pip install redis

rdb = redis.Redis(host="localhost", port=6379, db=0)

def claim_route(route, ttl_seconds=86400):
    """True the first time a route is seen in the TTL window, False after.
    SET NX is atomic, so two workers racing the same route still open one
    ticket, not two."""
    if not route:
        return False
    try:
        return bool(rdb.set(f"abuse:route:{route}", "1", nx=True, ex=ttl_seconds))
    except redis.RedisError as exc:
        # Dedupe store is down. Allow the ticket rather than silently dropping
        # reports; a rare duplicate beats a missed abuse report.
        log.warning("Dedupe unavailable (%s); allowing ticket for %s", exc, route)
        return True

A one-day window is a reasonable default. A persistent attacker is worth one ticket a day, not one a minute. If you're single-process and don't want Redis, a dict of route -> expiry works, but you lose atomicity the moment you scale past one worker.

Step 3: Open the ticket

Now the resolved contact becomes a ticket. Here's a generic create_ticket() with Jira Cloud as the concrete target. The same normalized contact and evidence can be sent to Zendesk, ServiceNow, Linear, or another tracker, but each system has its own endpoint, authentication model, and ticket fields. Jira Cloud is the concrete example below.

import os
import requests

JIRA_BASE = os.environ.get("JIRA_BASE_URL")       # https://you.atlassian.net
JIRA_EMAIL = os.environ.get("JIRA_EMAIL")
JIRA_TOKEN = os.environ.get("JIRA_API_TOKEN")     # id.atlassian.com API token
JIRA_PROJECT = os.environ.get("JIRA_PROJECT_KEY", "SEC")

def create_ticket(summary, body):
    """Create a ticket for a human to review before anything reaches the
    operator. Jira Cloud here; other trackers differ only in fields and auth."""
    if not (JIRA_BASE and JIRA_EMAIL and JIRA_TOKEN):
        log.error("Jira credentials are not fully configured")
        return None
    payload = {
        "fields": {
            "project": {"key": JIRA_PROJECT},
            "summary": summary[:255],              # Jira caps summaries at 255
            "issuetype": {"name": "Task"},
            "description": {
                "type": "doc", "version": 1,
                "content": [{
                    "type": "paragraph",
                    "content": [{"type": "text", "text": body}],
                }],
            },
        }
    }
    try:
        resp = requests.post(
            f"{JIRA_BASE}/rest/api/3/issue",
            auth=(JIRA_EMAIL, JIRA_TOKEN),
            json=payload,
            timeout=(1.0, 3.0),
        )
        resp.raise_for_status()
    except requests.RequestException as exc:
        log.error("Ticket creation failed: %s", exc)
        return None
    return resp.json().get("key")                  # e.g. "SEC-1421"

The API token lives in an env var, never in the file. The [:255] truncation is a real Jira limit that will 400 your request if you ignore it. Everything is wrapped, because a tracker outage should log and drop the report, not crash the process handling your attack traffic.

The glue ties the three steps together:

from datetime import datetime, timezone

def report_abusive_ip(ip, reason, log_excerpt):
    contact = resolve_abuse_contact(ip)
    if not contact:
        return  # failed open, already logged

    if not claim_route(contact["route"]):
        log.info("Already ticketed %s today; skipping %s",
                 contact["route"], ip)
        return

    ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%SZ")
    summary = f"Abuse report: {ip} ({contact['route']}) via {contact['org']}"
    body = (
        f"Offending IP: {ip}\n"
        f"Network: {contact['route']} ({contact['org']}, {contact['country']})\n"
        f"Reason: {reason}\n"
        f"Detected at (UTC): {ts}\n\n"
        f"Send report to: {', '.join(contact['emails'])}\n"
        f"Phone (incident only): {', '.join(contact['phones']) or 'none registered'}\n"
        f"Postal: {contact['address'] or 'n/a'}\n\n"
        f"Evidence:\n{log_excerpt}"
    )
    key = create_ticket(summary, body)
    if key:
        log.info("Opened %s for %s", key, ip)

The ticket carries what an abuse desk needs to act: the offending IP, the network, a reason, a UTC timestamp, and the log excerpt as evidence. It also carries the resolved emails so whoever picks up the ticket sends to the right desk without re-doing the lookup. UTC matters; a report timestamped in your local zone forces the operator to guess, and abuse desks that get vague reports close them.

Wiring it to a trigger

The pipeline needs an offending IP from somewhere. Your detection layer already produces them: Fail2Ban jails, a rate-limit rule, a WAF event, an SSH log parser. The cleanest hook is a small entrypoint your detector calls:

import sys

if __name__ == "__main__":
    # Fail2Ban action example:
    #   actionban = /usr/bin/python3 /opt/abuse/report.py <ip> "ssh brute force"
    if len(sys.argv) < 2:
        sys.exit("usage: report.py <ip> [reason]")
    offending_ip = sys.argv[1]
    reason = sys.argv[2] if len(sys.argv) > 2 else "automated detection"
    report_abusive_ip(offending_ip, reason, log_excerpt="see host logs")

One caveat that will bite you if you pull the IP from a web request instead of a firewall log: make sure it's the real source. Behind a proxy or load balancer, the socket address is the proxy, and X-Forwarded-For is caller-controlled and trivially spoofed. Report the wrong hop and you're emailing an innocent operator. Only trust X-Forwarded-For from proxies you actually run, and take the right entry, not the first thing an attacker put there.

The one thing not to automate

Resolve, dedupe, ticket. Do not add a fourth step that emails the abuse desk automatically. I'd argue this is the line, and it's worth being blunt about.

Detection triggers fire on spoofed and forged sources all the time. A NANOG thread on exactly this problem put it plainly years ago: the hard part of automated reporting was "dealing with spoofed sources," traffic that looks hostile but didn't come from where it claims. Wire an auto-emailer to a raw log trigger and you will send reports about IPs that never touched you, to desks that will start filtering your domain. Once abuse@ stops reading your mail, your real reports go nowhere.

A ticket puts a human in the loop for ten seconds: glance at the evidence, confirm it's real, send. That's the difference between a report an operator acts on and a report that gets your sender reputation torched. The automation should do the tedious part, the lookup and the routing, and stop at the judgment call.

When you outgrow the API

Per-request lookups are right until they aren't. If you're processing millions of events and calling the endpoint on each one, you're paying a credit and a round trip per event (the X-Credits-Charged response header tells you the exact cost). At that volume, the downloadable abuse contact database is the move: match the IP against a local copy refreshed daily, no network call in the hot path. Same data, sourced from all five RIRs, without the per-lookup cost.

And read the operator's terms before you scale up reporting. A polite, evidenced, deduplicated report is welcome. A firehose is abuse of the abuse desk, which is a special kind of irony you don't want to be responsible for.

The ASN Pivot Playbook: Routes, Upstreams, Downstreams

ABDULLAH AFZAL — Sun, 09 Aug 2026 10:53:38 +0000

An ASN pivot is the cheapest move in an IP investigation and the easiest one to over-read. One call turns a single address into a network, a list of announced prefixes, a transit chain, and a set of customer networks. None of that tells you who owns anything.

That gap is the whole problem. The data is easy to get and hard to weigh, so investigations into C2 infrastructure either ignore it or lean on it far past what it supports. This is the version I'd hand a new analyst: five pivots, in the order I'd run them, each with the false positive it hands you.

TL;DR

An ASN pivot maps one IP to the network announcing it, then walks outward through announced routes, downstream customers, upstream transit, and WHOIS.
downstreams and routes carry most of the signal. peers carries the least, and may not mean what the name suggests.
Upstream, downstream, and peer labels are not declared in BGP. They are inferred from observed AS paths, so treat them as a good guess rather than ground truth.
Routing adjacency alone is low-confidence evidence, always. It tells you where to look next, not who did anything.
False positive risk depends almost entirely on the AS type. Shared cloud and residential ISP networks produce near-worthless clustering; small dedicated networks produce useful clustering.
Everything below runs on one paid endpoint call plus local set math, in curl and Python.

The short version: use routing data to generate leads and non-routing evidence to confirm them. An analyst who can say what a pivot does not prove is more useful than one who can run more pivots.

The five pivots, ranked by what they prove

Run them in this order. Each one costs a single lookup, and you can pull all of the data in one request and slice it locally rather than making five calls.

#	Pivot	What you get	What it proves	Confidence
1	IP to origin ASN	AS number, org, type, RIR, allocation date	This address is routed by this network	High
2	ASN to announced routes	Every IPv4 and IPv6 prefix observed as originated by the AS	The address space currently announced with this AS as origin	High
3	ASN to downstreams	Customer networks routing through this AS	The data infers these networks as customers of this AS	Medium
4	ASN to upstreams	Transit providers carrying this AS	Who to escalate to, and how well connected the AS is	Medium
5	ASN to WHOIS	Registrant org, abuse contacts, handles	Who registered the number, which is not always who uses it	Low to medium

Nothing in that table is attribution. Pivot 1 is close to a fact. Everything below it is an inference with a shrinking amount of evidence behind it, which is why the order matters more than the coverage.

What upstreams, downstreams, and peers actually mean

Three relationships between autonomous systems, and the money decides which is which.

Upstreams are transit providers. You pay them, they carry your traffic to the rest of the internet and announce your prefixes onward. A network with multiple upstreams is multi-homed, which provides routing redundancy. The number of upstreams alone does not determine whether an AS is a stub.

Downstreams are customers. They route through you to reach everyone else, and you announce their prefixes on their behalf. Networks that provide transit have downstream customers; a stub AS does not provide transit between other ASes.

Peers sit level with you. Two networks exchange traffic directly, usually settlement-free, usually at an internet exchange. In the conventional valley-free routing model, peer-learned routes are generally exported to customers rather than to other peers or providers. A typical path therefore goes up through providers, may cross a peer link, and then goes down through customers. Real-world routing policies can have exceptions, so treat valley-free behavior as a useful model rather than a protocol guarantee.

Here's the part that changes how much you should trust any of it. BGP does not carry a field that says "this neighbour is my provider." The protocol announces reachability, not commercial terms, and the commercial terms are confidential. In datasets that infer AS relationships from observed BGP paths, upstream, downstream, and peer labels are algorithmic classifications rather than declarations carried in BGP itself. CAIDA, whose relationship dataset underpins a large share of this tooling, says as much directly in the paper describing their AS relationship inference algorithm: the business relationships are confidential, and the algorithm infers them from BGP paths.

So the labels are good. They are not ground truth, and an investigation that treats them as ground truth is building on sand.

Why `peers` may already contain your upstreams and downstreams

Worth checking before you write set logic against these arrays.

In the documented full response for AS12, every one of the 8 upstreams and both of the downstreams also appears in the peers array. peers also contains AS286 twice, once with country NL and once with US. On that response, peers behaves as "every adjacency we observed," not "settlement-free peers only."

I could only confirm this on one AS, so treat it as a property to check rather than a rule. Either way the defensive version costs two lines: deduplicate on AS number across the union, and treat the remaining peers entries after subtracting known upstreams and downstreams as peer candidates rather than proven settlement-free peers. Code that assumes the three sets are disjoint will double-count adjacencies and inflate whatever score sits on top.

Pivot 1: IP to origin ASN

Start here, always. An IP on its own is a poor unit of analysis, because bulletproof hosting operators rotate them deliberately. The Australian Cyber Security Centre's advisory on bulletproof hosting describes the technique plainly: these providers frequently change the internet-facing identifiers tied to a customer, including assigned IP addresses and domain names, which makes it harder to link an incident to whoever was using the address at the time. The AS number churns far more slowly than the address does.

curl -sS --max-time 3 \
  "https://api.ipgeolocation.io/v3/asn?apiKey=$IPGEO_API_KEY&ip=49.12.0.0"

{
  "ip": "49.12.0.0",
  "asn": {
    "as_number": "AS24940",
    "organization": "Hetzner Online GmbH",
    "country": "DE",
    "type": "HOSTING",
    "domain": "hetzner.com",
    "date_allocated": "2002-06-03",
    "asn_name": "HETZNER-AS",
    "allocation_status": "ASSIGNED",
    "num_of_ipv4_routes": "84",
    "num_of_ipv6_routes": "6",
    "rir": "RIPE"
  }
}

To be explicit, since this is an article about investigations: Hetzner is a legitimate hosting company and appears here because it is a well-documented example of a HOSTING-type AS, not because of anything else. That distinction matters throughout, and the false-positive table later on is mostly about not making that mistake.

Two field quirks that will bite you. as_number carries the AS prefix, so it is a string, not an integer. num_of_ipv4_routes and num_of_ipv6_routes are also strings despite being counts, so cast before comparing. Full field reference is in the ASN API documentation.

import os
import requests

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


def resolve_origin(ip_address):
    """Map an IP to the AS announcing it. Returns None on any failure."""
    if not API_KEY:
        raise RuntimeError("IPGEO_API_KEY is not set")

    try:
        resp = requests.get(
            BASE_URL,
            params={"apiKey": API_KEY, "ip": ip_address},
            timeout=(2.0, 5.0),
        )
        # 423 means bogon or private. That is an input problem, not an outage.
        if resp.status_code == 423:
            return None
        resp.raise_for_status()
    except requests.exceptions.RequestException as exc:
        # Enrichment is not a gate. Log and let the caller proceed without it.
        print(f"ASN lookup failed for {ip_address}: {exc}")
        return None

    asn = resp.json().get("asn") or {}
    return {
        "as_number": asn.get("as_number"),
        "organization": asn.get("organization"),
        "type": asn.get("type"),
        "rir": asn.get("rir"),
        # Counts come back as strings. Cast, and survive an empty value.
        "ipv4_routes": int(asn.get("num_of_ipv4_routes") or 0),
    }

That returns None rather than raising, which is a deliberate choice. An ASN lookup is enrichment on a case note, so it should fail open. If you wire this into enforcement, choose fail-open or fail-closed explicitly based on the control's role, your risk tolerance, and your availability requirements.

Pivot 2: ASN to announced routes

The routes array is the address space currently observed as originated by the AS, and it is your enumeration surface. If your one indicator sits in a /24 inside a network announcing 84 prefixes, you now have a defined perimeter to scan, correlate against logs, or check for previously-seen addresses.

curl -sS --max-time 5 \
  "https://api.ipgeolocation.io/v3/asn?apiKey=$IPGEO_API_KEY&asn=AS12&include=routes"

The gotcha is small and annoying: IPv4 and IPv6 prefixes arrive mixed in the same array, as plain CIDR strings. Split them before you do anything numeric.

import ipaddress


def split_routes(routes):
    """Separate a mixed v4/v6 prefix list. Skips anything unparseable."""
    v4, v6 = [], []
    for prefix in routes or []:
        try:
            net = ipaddress.ip_network(prefix, strict=False)
        except ValueError:
            continue  # Malformed entry, not worth failing the whole pivot over
        (v4 if net.version == 4 else v6).append(net)
    return v4, v6

One caution before you scan everything you just enumerated. A prefix announced with the AS as origin does not make it interesting, and on a large host the announced space is mostly other people's servers.

Pivot 3: ASN to downstreams

This is the pivot that earns its place, and the one most write-ups skip.

The joint guidance CISA published with the NSA, FBI, DC3 and international partners in November 2025, Bulletproof Defense, makes the structural point: bulletproof hosting (BPH) operators increasingly resell stolen or leased infrastructure from legitimate hosting providers, data centres, ISPs and cloud providers, who may have no idea what they are carrying. If a reseller operates its own ASN and buys transit from another provider, it may appear as that provider's downstream. If it only leases IP addresses or servers inside the provider's network, no separate downstream ASN relationship may exist.

So when your indicator lands in a small or mid-sized AS, the customer list is where the interesting structure lives.

curl -sS --max-time 5 \
  "https://api.ipgeolocation.io/v3/asn?apiKey=$IPGEO_API_KEY&asn=25139&include=downstreams"

{
  "asn": {
    "organization": "TVCABO Comunicacoes Multimedia, Lda",
    "country": "MZ",
    "downstreams": [
      { "as_number": "AS328162", "description": "Icolo Ltd", "country": "KE" },
      { "as_number": "AS10798", "description": "The Standard Bank of South Africa Proprietary Limited", "country": "ZA" },
      { "as_number": "AS37477", "description": "Mozabanco", "country": "MZ" },
      { "as_number": "AS329394", "description": "OneCloud LDA", "country": "MZ" }
    ]
  }
}

Read that list the way an investigator should: a regional operator with a bank, a data centre company and a cloud provider as customers is a normal regional operator. Nothing here is suspicious. On a genuinely suspect network the shape is the signal, not any individual name. Many small downstreams registered in quick succession, opaque or recently created organisation names, and customers announcing far more space than the business behind the name would plausibly need.

A downstream relationship suggests a customer-provider relationship based on observed routing data. It does not prove a commercial agreement, common ownership, or shared operation. Plenty of resellers are exactly what they claim to be.

Pivot 4: ASN to upstreams

Upstreams answer two different questions, and it is worth being clear about which one you are asking.

The investigative question is how well connected the network is. A single upstream means the network depends on one inferred transit provider in this dataset. Several upstreams indicate multihoming and routing redundancy, but they do not tell you whether the operator is legitimate or well funded.

The operational question is who to talk to. The ACSC advisory makes the point that upstream providers may be unaware they are carrying downstream criminal infrastructure, and the CISA guidance is addressed largely to those providers. If you are filing an abuse report that has gone nowhere at the hosting layer, the transit provider one hop up is the next escalation, and it is often the one with both the standing and the incentive to act.

curl -sS --max-time 5 \
  "https://api.ipgeolocation.io/v3/asn?apiKey=$IPGEO_API_KEY&asn=AS12&include=upstreams"

There is a ceiling on this. Once you climb into tier-1 territory the concept stops being informative, because those networks carry effectively everything and their presence says nothing about any particular customer. When your upstream list is a set of global carriers, you have reached the top of the useful part of the pivot.

Pivot 5: ASN WHOIS, and the registrant trap

include=whois_response returns the raw registry record: registrant organisation, admin and tech handles, abuse contacts, allocation dates.

The trap is in the name of the organization field, and it catches people constantly. That field is the entity registered with the RIR as holding the AS number. It is not necessarily the entity using the address space. Subleasing, resale, acquisitions that never got reflected in the registry, and shell registrations all break the link, and this is precisely the pattern the CISA guidance describes when it talks about resold infrastructure. If you have ever wondered why looking up who owns an IP address gives you a cloud provider's name when the actual tenant is a startup you have never heard of, this is why.

Useful things in the record anyway: the abuse handle and email for reporting, RegDate and Updated for age, the RDAP references, and the maintainer objects, which occasionally tie several ASNs to one operator more reliably than any routing relationship does. Field names differ by registry, so an ARIN record and a RIPE record will not parse the same way. Recent allocation plus sparse contact detail plus a large customer list is a shape worth a second look.

Pull it once, slice it locally

All five pivots come out of one request. The include parameter takes all five datasets and adds no extra credit cost over the single credit the lookup already costs, so making five separate calls is just five times the spend for the same data.

# Continues the module from Pivot 1: requests, API_KEY and BASE_URL are already set.


def fetch_asn_profile(as_number):
    """One call, everything. Returns the asn object or None."""
    try:
        resp = requests.get(
            BASE_URL,
            params={
                "apiKey": API_KEY,
                "asn": as_number,
                "include": "routes,peers,upstreams,downstreams,whois_response",
            },
            timeout=(2.0, 10.0),  # Larger payload, so a longer read timeout
        )
        resp.raise_for_status()
    except requests.exceptions.RequestException as exc:
        print(f"Profile lookup failed for {as_number}: {exc}")
        return None

    return resp.json().get("asn") or {}


def relationship_sets(asn):
    """Dedupe adjacencies and separate unclassified peer candidates."""
    def numbers(key):
        return {n.get("as_number") for n in (asn.get(key) or []) if n.get("as_number")}

    upstreams = numbers("upstreams")
    downstreams = numbers("downstreams")
    peer_candidates = numbers("peers") - upstreams - downstreams

    return {
        "upstreams": upstreams,
        "downstreams": downstreams,
        "peer_candidates": peer_candidates,
        "all_adjacent": upstreams | downstreams | peer_candidates,
    }

Note that a lookup by AS number returns no top-level ip field, since there is no address to echo back. Do not assume it is there.

Cache relatively stable ASN metadata aggressively, but keep a timestamp. Organizations, allocations, and routing data can change. If route accuracy matters to your workflow, refresh routes more frequently than basic ASN metadata or fetch them per case.

What each signal actually proves

The table that should sit next to the pivot table in your head.

Signal	Confidence on its own	What raises it
Same IP observed across related events	Medium to high	Corroborating timing, service, account, or behavioral evidence
Same announced prefix	Medium to high	Matching services, banners, or TLS certificates on both hosts
Same origin ASN, small dedicated network	Medium	Consistent behaviour and timing across the hosts
Same origin ASN, large host or cloud	Very low	Effectively needs independent evidence to mean anything
Downstream relationship	Low to medium	Shared registrant, shared maintainer object, correlated registration dates
Upstream relationship	Very low	Almost nothing. Transit is a commercial arrangement, not an endorsement
Peer relationship	Very low	Same
Shared WHOIS registrant or maintainer	Medium	Corroborating DNS, certificate, or malware-family overlap

The pattern is consistent. Routing data is excellent at generating candidates and poor at confirming them. Certificates, passive DNS, service fingerprints and behavioural timing are what turn a candidate into a finding. Anyone who tells you an upstream relationship implicates a provider is selling something.

False positives by AS type

The type field is the single most useful thing for calibrating how much a shared ASN means. Same data, opposite conclusions.

`type`	What a shared ASN means	What to do
`ISP`	Almost nothing. Residential networks mix real users with compromised devices at scale	Never cluster on ASN alone. Score the host, not the network
`HOSTING`	Depends entirely on size. Meaningless on a large provider, meaningful on a small one	Check the routing footprint and other context first. Route count can help distinguish a broad network from a narrow one, but it is not a reliable measure of organization size by itself.
`BUSINESS`	Potentially useful, but may still contain shared, managed, or resold infrastructure	Confirm the operator and hosting model before clustering
`EDUCATION`	Often shared infrastructure with many unrelated users and systems	Avoid ASN-wide conclusions; investigate the individual host and context
`GOVERNMENT`	Shared organizational infrastructure where ASN-wide attribution is especially risky	Investigate narrowly and use appropriate escalation channels

The num_of_ipv4_routes count is a useful routing-footprint signal, which is the practical reason to bother casting that string. Do not treat it as a direct measure of organization size.

Stop rules

Over-pivoting is how a clean case turns into a pile of loosely related infrastructure nobody can act on. Stop when any of these is true.

You have reached a tier-1 network. Upstream relationships stop carrying information at the top of the transit hierarchy.
The AS type is ISP or a large HOSTING network. the shared-network signal is usually too weak on its own; further expansion just adds noise.
You are two relationship hops out with no corroborating evidence. Adjacency to adjacency is not a chain of evidence.
The candidate set is growing faster than your evidence. If each pivot adds twenty addresses and zero confirmations, the pivot is not working.
You cannot state what the next pivot would change. If the answer does not alter a decision, do not make the call.

Write the stop reason into the case note. The next analyst needs to know you stopped deliberately, not that you ran out of time.

Wiring it into a case note

Attach the routing profile to the indicator, not the case. Store as_number, organization, type, rir and the route counts alongside the address with a timestamp, because routing changes and an undated profile is one you cannot reason about six months later.

Keep the confidence label with the data. A field that records asn_match_confidence: low next to a cluster of addresses is worth more than the cluster, because it stops the next person treating your leads as your findings.

One credit per lookup, cached for a day, is cheap enough that IP enrichment at SIEM ingest is usually the right call rather than looking things up by hand mid-investigation. Just make sure the enrichment step cannot take the pipeline down with it.

Run the two-ASN check on the peers behaviour against your own data before you build scoring on those arrays. And if a pivot gives you a lead you cannot confirm with something outside BGP, write it down as a lead and move on. The discipline is the deliverable here, not the API call.

IP Reputation WAF Rules: Fields, Thresholds, Actions

ABDULLAH AFZAL — Thu, 30 Jul 2026 17:41:31 +0000

An IP reputation API is only useful in a WAF rule if you can see why a request got blocked. Cloudflare's threat score returns 0 now. AWS won't tell you what's in its list.

That leaves a gap most WAF rules quietly have. You can still block traffic by reputation, but on the two most widely deployed WAFs you either have no score to threshold against or no way to explain a block to the customer who hit it. This is a reference for closing that gap: which signals deserve a rule, what action each one justifies, and the syntax for four platforms.

TL;DR

cf.threat_score is deprecated and now always returns 0. Cloudflare's replacement bot score needs an Enterprise plan with Bot Management.
AWS WAF's AWSManagedRulesAmazonIpReputationList works, but the list contents, its changes, and its versioning are all undisclosed by design.
Azure's IP Reputation Rule Set sorts traffic into Bad, Good, and Unknown from Microsoft Threat Intelligence indicators, with no per-IP score either.
An external IP reputation API gives you per-signal fields, provider names, confidence scores, and last-seen dates, which is what makes a block auditable.
Precompute scores into a WAF list on a schedule. Don't put an API call in the request path unless you have a specific reason to.

Managed reputation lists are fine at catching obvious attackers and bad at everything requiring nuance. If you need to treat a corporate VPN differently from a residential proxy, or explain why a legitimate crawler got a 403, you need the underlying signals rather than a verdict.

Your WAF's built-in reputation signal is gone or opaque

Start with what each platform actually gives you, because two of the three have changed in ways the tutorials haven't caught up with.

Cloudflare removed the signal. The cf.threat_score field reference states that the score previously ran 0 to 100 and is now always 0. The Security Level docs say the same thing, and so does the analytics threat types page, which notes that the "Bad IP" category was based on that score. This isn't news, the deprecation was scheduled for September 2024, but a lot of still-circulating advice tells you to write cf.threat_score ge 15 rules. Those rules now match nothing. The replacement, cf.bot_management.score, requires Enterprise with Bot Management, so on Free through Business the Cloudflare threat score is gone with nothing behind it.

AWS keeps the signal and hides the inputs. AWSManagedRulesAmazonIpReputationList costs 25 WCUs and contains three rules: AWSManagedIPReputationList and AWSManagedReconnaissanceList both default to Block, while AWSManagedIPDDoSList defaults to Count. The data comes from Amazon's internal threat intelligence. What you can't get is the IP reputation list itself. The rule group documentation says the published information is "intended to provide you with what you need to use the rules without giving bad actors what they need to circumvent the rules," and the changelog explicitly doesn't report changes to the IP lists. No versioning, no SNS notifications. There's a reasonable security argument for that. There's also no way to audit it.

Azure does the same thing with different labels. The IP Reputation Rule Set and Bot Manager sort traffic into three buckets: Bad bots from high-confidence Microsoft Threat Intelligence IP indicators of compromise, Good bots from a verified allowlist, and Unknown bots including medium-confidence indicators. Useful defaults, no score, no per-IP evidence.

The failure mode is the same everywhere and it's documented by the vendors themselves. An AWS re:Post thread has an engineer discovering that the rule named "IP reputation" keys on bot behaviour and catches legitimate Googlebot traffic. On the Azure side, a Microsoft moderator confirmed that Bot Manager 1.1 doesn't classify ChatGPT, Claude, or Bing Copilot crawlers as Good Bots, so blocking Unknown Bots blocks them too.

The signals worth writing rules against

A single boolean is a bad input to a rule. "This IP is a proxy" forces you to pick between blocking real customers and letting threats through, because the flag covers a datacenter scraper and someone's work laptop on a corporate tunnel equally.

Anonymity signals split that. is_vpn, is_proxy, is_residential_proxy, is_relay, and is_tor describe genuinely different populations with different legitimate-use rates. Residential proxies share address space with ordinary consumers, so a hard block there hits real users. Privacy relays like iCloud Private Relay and Cloudflare WARP are ordinary consumer traffic wearing a different exit address.

Behaviour and infrastructure signals answer a different question. is_known_attacker, is_bot, and is_spam describe observed activity rather than connection type. is_cloud_provider and cloud_provider_name tell you the request came from hosting infrastructure, which matters on paths that should only see human traffic and doesn't matter at all on your API.

The evidence fields are what make any of this defensible. Provider names, confidence scores, and last-seen dates let a rule act on strength and recency instead of a bare flag. An exit node last seen this week isn't the same risk as one last seen in December, and a rule that can't tell them apart will age badly.

Here's the full security response. It's 19 fields, and this is a real flagged address rather than a documentation placeholder:

{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": ["Zyte Proxy"],
    "proxy_confidence_score": 80,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": ["Nord VPN"],
    "vpn_confidence_score": 80,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A."
  }
}

Two shapes to note before you write any parsing code. The *_provider_names fields are arrays, not comma-separated strings, and they can come back empty even when the matching boolean is true. relay_provider_name and cloud_provider_name are single strings that return "" rather than null when there's no match. proxy_last_seen can also be "" on a positive is_proxy. Handle the empty cases or your rule logic will throw on the first partial match.

Signal-to-action decision matrix

This is the part no vendor publishes, because publishing it means committing to a position.

Signal	What it actually tells you	Action	False-positive risk
`is_known_attacker`	Observed in attack traffic	Block	Low
`is_tor`	Tor exit node	Block, or challenge if privacy users matter to you	Low
`is_proxy` + high confidence + recent last-seen	Datacenter or commercial proxy	Block	Low to moderate
`is_residential_proxy`	Consumer ISP address routed as a proxy	Challenge. Don't hard block	High
`is_vpn`	Commercial VPN	Challenge, or allow depending on your business	High
`is_relay`	Privacy-routing service such as iCloud Private Relay or Cloudflare WARP	Do not block on relay status alone; evaluate other risk signals	Very high
`is_cloud_provider`	Hosting or cloud address	Rate limit or challenge on human-only paths	Moderate
`is_bot`	Automated agent	Route by path. Allow verified crawlers	Moderate
`is_spam`	Spam source	Challenge on forms and signup	Moderate
`is_anonymous`	Any of VPN, proxy, or relay	Don't use as a block trigger	High

The is_relay row is the one I would treat most cautiously. Relay status identifies privacy-routed traffic, not malicious intent. Do not block solely because the flag is present, but do not let it override independent evidence such as known attack activity, abusive behavior, or account-level risk.

One portability warning: challenge isn't universally available. Cloudflare has managed challenge and AWS WAF has CAPTCHA and Challenge actions, but challenge capabilities vary by platform and rule type. Cloudflare supports Managed Challenge, AWS WAF supports CAPTCHA and Challenge, and Azure Front Door Bot Manager 1.1 supports JavaScript Challenge for applicable bot rules. Where a native challenge action is unavailable, route or redirect the request to an application-controlled verification flow rather than treating “challenge” as a portable WAF action.

Threat score bands

A composite IP reputation score is the cheap version of the matrix above. It's useful as a first filter and dangerous as your only filter.

Band	Action	Why
80 to 100	Block or send to manual review	Multiple signals agreeing
45 to 79	Additional verification, OTP or CAPTCHA	Suspicious, not conclusive
20 to 44	Combine with other signals before acting	Needs context to mean anything
1 to 19	Log only	Low observed risk

Those bands are the vendor's own published guidance for this particular score. That matters more than it sounds, because scores don't transfer between providers. A 70 from one API and a 70 from another are unrelated numbers built from different inputs with different weightings. If you migrate providers, re-derive your thresholds against your own traffic rather than porting the number across.

Two ways to wire an IP reputation API into a rule

There are only two real architectures, and the choice mostly comes down to whether you're willing to put a network call in front of your users.

Precompute into a WAF list. A scheduled job pulls reputation data, filters it to the addresses you care about, and writes them into a native IP list. The WAF evaluates locally. Bulk lookup takes up to 50,000 addresses per POST, which collapses a large refresh into a handful of requests. Note that it collapses the request count, not the bill: bulk charges the same 2 credits for every valid address in the body.

Evaluate per request. Your edge worker or application checks the address on the way in, with a cache in front. Fresher, and it gives you the full field set at decision time instead of a precomputed yes or no.

	Precompute	Per request
Added latency	None	Cache hit is negligible, miss is a network call
Cost	Predictable, one batch	Scales with traffic
Freshness	As stale as your interval	Current
Blast radius of a bad call	Whole list until next run	One request
Evidence at decision time	Just membership	Every field

I'd start with precompute for most teams. It keeps the request path clean, it fails safe by default because a broken sync job leaves the last good list in place, and it's easier to reason about during an incident. Reach for per-request when you actually need the individual fields at decision time, for instance when a residential-proxy hit should challenge while a datacenter-proxy hit should block outright.

IPGeolocation, MaxMind GeoIP2, IPQualityScore, ipinfo, and IPLocate all return reputation signals of some kind, and they differ mainly in how much evidence ships with each verdict. I'm using IPGeolocation's IP Security API for the examples because it returns provider names, confidence scores, and last-seen dates as separate fields, which is what the matrix above actually needs.

A single lookup looks like this. The dedicated security endpoint returns security data only and costs 2 credits, against 3 if you ask for security alongside geolocation on the unified endpoint:

curl -sS --max-time 2 \
  "https://api.ipgeolocation.io/v3/security?apiKey=${IPGEO_API_KEY}&ip=2.56.188.34"

Here's the sync job. It reads a candidate list, scores it in bulk, and writes the blockable addresses into an AWS WAF IP set:

import os
import boto3
import requests
from botocore.exceptions import ClientError

API_KEY = os.environ.get("IPGEO_API_KEY")
BLOCK_AT = 80  # matches the vendor's block band; tune against your own traffic

def score_addresses(addresses):
    """Bulk-score up to 50,000 addresses per POST. Returns those worth blocking."""
    try:
        response = requests.post(
            "https://api.ipgeolocation.io/v3/security-bulk",
            params={"apiKey": API_KEY},
            json={"ips": addresses},
            timeout=(2.0, 15.0),
        )
        response.raise_for_status()
    except requests.RequestException as exc:
        # Fail open. A failed refresh must leave the existing IP set untouched
        # rather than emptying it and dropping protection entirely.
        print(f"Scoring failed, keeping current IP set: {exc}")
        return None

    blockable = []

    for item in response.json():
        security = item.get("security") or {}

        # Bogon and malformed entries return no security object.
        if not security:
            continue

        score = security.get("threat_score", 0)
        known_attacker = security.get("is_known_attacker", False)

        # Relay status alone should not trigger a block, but it must not
        # override independent high-risk evidence.
        if security.get("is_relay") and not known_attacker and score < BLOCK_AT:
            continue

        if score >= BLOCK_AT or known_attacker:
            blockable.append(f"{item['ip']}/32")

    return blockable

def update_ip_set(waf, set_id, set_name, scope, addresses):
    try:
        current = waf.get_ip_set(Id=set_id, Name=set_name, Scope=scope)
        waf.update_ip_set(
            Id=set_id,
            Name=set_name,
            Scope=scope,
            Addresses=addresses,
            LockToken=current["LockToken"],  # required; rejects concurrent writes
        )
    except ClientError as exc:
        print(f"IP set update failed: {exc}")

if __name__ == "__main__":
    candidates = ["2.56.188.34", "1.0.175.9"]
    scored = score_addresses(candidates)

    # None means the scoring request failed, so preserve the last-known-good set.
    # An empty list means the request succeeded and no addresses remain blockable,
    # so update the IP set and clear the old entries.
    if scored is not None:
        update_ip_set(
            boto3.client("wafv2", region_name="us-east-1"),
            os.environ["WAF_IP_SET_ID"],
            os.environ["WAF_IP_SET_NAME"],
            "REGIONAL",
            scored,
        )

The fail-open behaviour is the important line. If scoring fails and you return an empty list, you've just replaced your blocklist with nothing. Returning None and skipping the write keeps the last known good state.

Two constraints on that endpoint worth knowing before you build against it. Bulk requires an API key and rejects request-origin CORS auth, so this has to run server-side. And invalid, private, or bogon entries come back as a bare message object rather than security data, which is why the loop skips anything without a security key instead of assuming every response item has one.

For the per-request path, a Cloudflare Worker with a cache in front:

const BLOCK_AT = 80;
const CACHE_TTL = 3600; // seconds; trades freshness for quota

export default {
  async fetch(request, env, ctx) {
    const requestUrl = new URL(request.url);

    // Prevent residential-proxy traffic from redirecting /verify to itself.
    if (requestUrl.pathname === "/verify") {
      return fetch(request);
    }
    // Cloudflare sets this to the real client address at the edge.
    // Behind another proxy, don't trust a client-supplied X-Forwarded-For.
    const ip = request.headers.get("CF-Connecting-IP");
    if (!ip) return fetch(request);

    const cacheKey = `rep:${ip}`;
    let verdict = await env.REPUTATION.get(cacheKey, { type: "json" });

    if (!verdict) {
      try {
        const url = `https://api.ipgeolocation.io/v3/security?apiKey=${env.IPGEO_API_KEY}&ip=${ip}`;
        const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
        if (!res.ok) throw new Error(`HTTP ${res.status}`);

        const security = (await res.json())?.security ?? {};
                verdict = {
          score: security.threat_score ?? 0,
          relay: security.is_relay ?? false,
          residential: security.is_residential_proxy ?? false,
          knownAttacker: security.is_known_attacker ?? false,
        };
        ctx.waitUntil(
          env.REPUTATION.put(cacheKey, JSON.stringify(verdict), { expirationTtl: CACHE_TTL })
        );
      } catch (err) {
        // Fail open: a reputation lookup is not worth an outage.
        console.log(`Lookup failed for ${ip}: ${err.message}`);
        return fetch(request);
      }
    }

    if (verdict.knownAttacker || verdict.score >= BLOCK_AT) {
      return new Response("Forbidden", { status: 403 });
    }

    if (verdict.residential) {
      return Response.redirect(new URL("/verify", requestUrl), 302);
    }

    return fetch(request);
  },
};

The residential-proxy branch redirects to a separate verification flow instead of blocking the request. The verification endpoint must implement the actual step-up control, such as Turnstile or account verification: same lookup, different action, because the populations are different.

Platform reference

Cloudflare

Custom lists live at the account level and are referenced in an expression with the in operator against $list_name:

ip.src in $reputation_blocklist

List names must match ^[a-z0-9_]+$ and stay under 50 characters. Updating the list updates every rule referencing it, so one rule slot covers the whole blocklist regardless of size, which matters on plans with a low custom-rule quota. Custom lists also accept ASNs, matched against ip.src.asnum, if you want to act on whole networks rather than addresses.

AWS WAF

Two patterns worth knowing. The first is your own IP set, referenced with an IPSetReferenceStatement and given a priority ahead of the managed group.

The second is more useful and less known. The managed reputation rule group adds labels to every request it evaluates, and those labels are available to AWS WAF rules running after it. So you can override the group's action to Count, then write your own rule keying on the label plus your own conditions:

awswaf:managed:aws:amazon-ip-list:AWSManagedIPReputationList

That turns an opaque block into a signal you combine with your own data. It's the closest thing AWS offers to tuning the managed list.

If a managed rule is blocking traffic you need, the documented fix is a scope-down statement: set the rule group's scope of inspection to "only requests that match a scope-down statement," then invert it with a NOT against your allowlist IP set.

Azure WAF

Custom rules are processed before managed WAF rules, which is the precedence you want for a bring-your-own signal. Rules run in priority order and combine a match condition with an action. Use an IPMatch condition against your synchronized address list. Standard actions include Allow, Block, Log, and Redirect, while Azure Front Door Premium also supports JavaScript Challenge in supported scenarios.

NGINX and ModSecurity

Self-hosted has no built-in reputation data at all, which makes it the clearest case. You supply everything, so there's nothing opaque.

For NGINX, generate a geo block from your scored data and include it:

geo $ip_reputation_block {
    default          0;
    include          /etc/nginx/conf.d/reputation.map;  # regenerate on each sync
}

server {
    if ($ip_reputation_block) {
        return 403;
    }
}

For ModSecurity or Coraza, match the address against a generated file:

SecRule REMOTE_ADDR "@ipMatchFromFile /etc/modsecurity/reputation.txt" \
    "id:1001,phase:1,deny,status:403,log,msg:'IP reputation block'"

If you're going the self-hosted route at volume, the downloadable security database is a better fit than the API. It ships the same fields as CSV keyed by address range, so you can regenerate these files from a local file instead of making network calls. One quirk to plan for: the database serialises booleans as strings, so is_proxy arrives as "true" rather than true. Cast before you branch on it.

What breaks this in production

The address you're scoring is the wrong address. AWS documents that its IP reputation rules use the source address from the web request origin, which behind a proxy or load balancer is the last proxy rather than the client. Same trust-proxy problem you have in application middleware, one layer further out. Verify what your WAF is actually seeing before you tune anything.

Fail-open versus fail-closed, decided on purpose. Both code paths above fail open. That's the right default for a reputation check, which is a risk signal rather than an authentication boundary. If you fail closed, say so in the runbook, because the first API timeout will otherwise look like an outage nobody can explain.

Cache TTL fights freshness. A one-hour TTL on a residential proxy address is probably fine. On a fast-rotating datacenter proxy it's stale. Consider a shorter TTL for high-score addresses and a longer one for clean ones.

Do the credit arithmetic before you commit. The Starter plan is $19 a month for 150,000 credits, and a dedicated security lookup costs 2 credits, so that's 75,000 lookups, not 150,000. Combined with geolocation on the unified endpoint it's 3 credits and 50,000 lookups. Bulk is billed per valid address at the same rate, so one maximum-size request of 50,000 addresses costs 100,000 credits, which is two thirds of a Starter plan in a single call. Size your refresh interval against that, not against the request count. The X-Credits-Charged header gives you the exact charge, and bogon, private, and malformed addresses aren't billed at all, which makes the API safe to point at unfiltered log data.

Shared addresses punish blunt rules. Carrier-grade NAT and mobile carrier ranges put thousands of unrelated users behind one address. A block there is a block on all of them. This is the strongest argument for challenge over block on the high-false-positive rows in the matrix.

IPv6 needs its own pass. Reputation coverage on IPv6 is thinner than IPv4 across every provider, and some WAF list features are IPv4-only. Check before you assume parity.

Start every new rule in Count or Log mode and leave it there long enough to see real traffic through it. Compare what it would have blocked against addresses you know are legitimate, then promote it. The threshold you ship should be the one your own traffic justified, not the one in this table.

IP Risk Score Thresholds: What to Do at Each Level

ABDULLAH AFZAL — Tue, 28 Jul 2026 14:32:25 +0000

An IP risk score is a 0 to 100 rating of how much abuse an IP address has been associated with. Every guide tells you to respond proportionally to it. Almost none of them name a number.

The page currently ranking first for "check IP risk score before processing payment" has a section titled "Define Action Tiers." It does not define a tier. The next two results are a vendor glossary and a three-year-old payment processor blog post. Between them: 5,000 words, zero thresholds, zero code.

So this is the reference I wanted and could not find. The bands, the fields underneath them, the action each one should trigger, and the parts where the score is no help at all.

TL;DR

Four bands: 1-19 allow with standard controls, 20-44 combine with other signals before acting, 45-79 add friction, 80-100 block or route to manual review.
A clean IP returns 0. Scores above 20 indicate additional risk context, but the category-specific flags explain what produced it.
Three fields should override the band: is_residential_proxy, is_known_attacker, and the confidence scores. A residential proxy scoring 30 is not the same animal as a cloud IP scoring 30.
is_relay should almost never block on its own. That flag includes privacy services such as iCloud Private Relay and Cloudflare WARP, so it can represent legitimate consumer traffic.
The gate belongs before the payment call, because plenty of abuse never reaches a payment object at all.
Stripe Radar is not a substitute and not a competitor. It scores a different thing at a different moment.

The score is a decision aid, not a verdict. It answers "how much abuse has this address been involved in," which is a narrower question than "is this person committing fraud." Treat the bands below as a starting policy and tune them against your own chargeback and false-positive numbers.

What an IP risk score actually measures

Vendors cannot agree on a name for this number. You will see it sold as an IP risk score, an IP fraud score, a fraud risk score, or an IP reputation score. Across the fraud detection APIs that expose one, it is the same idea under different labels, which is worth knowing before you compare two vendors' documentation and think you are reading about two different products.

A risk score is a composite of three things: whether the address is hiding its origin, whether it has abuse history, and what kind of infrastructure it sits on. Nothing in there is about the person holding the card.

That distinction matters more than it sounds. A score of 60 does not mean a 60% chance of fraud. It means several signals fired at once on an address that a lot of traffic shares. Corporate VPNs score. Datacenter egress scores. A university NAT gateway scores. All three are full of legitimate customers.

The composite is built from active honeypots, blocklists, VPN and proxy enumeration, and behavioural analysis, which is roughly the industry pattern. Field names below are ipgeolocation.io's, because that is the API I use for this, but the concepts port: IPQualityScore, MaxMind minFraud, IPLocate, IP2Proxy, and Spur all expose some version of a composite score plus category flags. What varies is whether you get the provider name and the confidence behind each flag, and that turns out to be the part that changes decisions.

The four bands and what to do in each

This is the table. Everything else in the article supports it.

`threat_score`	Reading	Action	What it usually means
1-19	Low observed risk	Allow with standard controls	Isolated, low-severity indicators. Often just cloud hosting. Still worth logging for pattern analysis.
20-44	Use with context	Combine with other signals before acting	Anonymization without attacker or abuse signals, or several light indicators adding up. Blocking here catches real users.
45-79	Elevated risk	Add friction before allowing	Anonymization plus abuse indicators such as bot activity or spam history. OTP, CAPTCHA, email verification, rate limiting, or a review queue.
80-100	High risk	Block, hard challenge, or manual review	Multiple signals at once: VPN or proxy alongside attacker history, spam reports, or bot-like behaviour.

Two notes on reading it. A clean address returns 0, and the documented bands start at 1, so treat 0 and the 1-19 band identically. And the 20-44 row is the one people get wrong: it is tempting to block there because "anonymization" sounds damning, but an IP showing a VPN and nothing else is a privacy-conscious customer far more often than a fraudster. The published threshold guidance is explicit that blocking at that level without device, behaviour, velocity, or geolocation context risks catching legitimate users.

If you implement only the 80-100 rule and log everything else for a month, you will have done most of the useful work and broken nothing.

The 19 fields and what each one means for a payment decision

The threat score is the summary. These are the inputs, and several of them should change your decision independently of the number.

Field	Type	What it tells you at checkout
`threat_score`	number, 0-100	The composite. Start here, do not stop here.
`is_anonymous`	boolean	True when a VPN, proxy, Tor, or relay is hiding the origin. The umbrella flag over the four below.
`is_vpn`	boolean	Commercial VPN. Extremely common among legitimate customers.
`vpn_provider_names`	array of strings	Named provider, for example `["Nord VPN"]`. Empty array when unattributed.
`vpn_confidence_score`	number, 0-100	How strongly the VPN detection is supported.
`vpn_last_seen`	string, `YYYY-MM-DD`	Recency of the detection. Empty string when absent.
`is_proxy`	boolean	Datacenter or commercial proxy.
`proxy_provider_names`	array of strings	For example `["Zyte Proxy"]`. Scraping infrastructure surfaces here.
`proxy_confidence_score`	number, 0-100	Detection strength for the proxy signal.
`proxy_last_seen`	string, `YYYY-MM-DD`	Recency. Empty string when absent.
`is_residential_proxy`	boolean	Residential proxy network. The flag most APIs do not have, and the one that matters most here.
`is_tor`	boolean	Tor exit node.
`is_relay`	boolean	iCloud Private Relay or Cloudflare WARP. Not evasion. See below.
`relay_provider_name`	string	Empty string when `is_relay` is false.
`is_known_attacker`	boolean	Observed participating in attacks. Escalate regardless of score.
`is_bot`	boolean	Automated client.
`is_spam`	boolean	Spam-source history.
`is_cloud_provider`	boolean	Hosting infrastructure. Expected for server-to-server, odd for a consumer checkout.
`cloud_provider_name`	string	For example `"Packethub S.A."`.

Note the empty-value conventions, because they will bite you: unattributed provider lists come back as [], confidence scores as 0, and date fields as "" rather than null. A truthy check on proxy_last_seen behaves the way you want; a !== null check does not.

The three fields that should override the band

is_known_attacker is the strongest single signal in the response. An address observed in actual attacks is not a scoring question. Block it at 30 the same way you would at 90.

is_residential_proxy is the one worth paying for. Residential proxy networks route traffic through real consumer devices, which is exactly what defeats a naive datacenter-IP rule. A residential proxy at a checkout is someone who went to deliberate trouble to look like a normal customer. I route those to review rather than blocking, because the false-positive cost is real: some are malware-compromised devices belonging to actual people, and a few are legitimate privacy tools.

The confidence scores are the field most teams ignore and should not. is_vpn: true with vpn_confidence_score: 30 and a vpn_last_seen from four months ago is a much weaker claim than the same flag at 90 seen last week. If your rule engine treats those identically, you are throwing away the only part of the response that tells you how much to trust it.

The one flag that should almost never block

is_relay covers iCloud Private Relay and Cloudflare WARP. Private Relay is included with iCloud+, but users must enable it on each device. Relay status alone is not evidence of fraud and should not trigger a block without additional risk signals.

Treating relay traffic as VPN traffic is the most expensive mistake in this whole area, and it is common because a lot of APIs collapse both into one boolean. If your provider does not separate is_relay from is_vpn, you cannot write this rule at all, and you are quietly adding friction to iPhone checkouts. Allow relay below the elevated band and let the score do the work above it.

Where the gate goes

Before the payment call, after you have resolved the real client IP. This is a pre-authorization check in the literal sense: it runs while you still have cheap options, before there is an authorization to reverse. One request:

curl -sS -X GET \
  "https://api.ipgeolocation.io/v3/security?apiKey=$IPGEO_API_KEY&ip=2.56.188.34"

The full response, all 19 fields, for a heavily flagged address:

{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": ["Zyte Proxy"],
    "proxy_confidence_score": 80,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": ["Nord VPN"],
    "vpn_confidence_score": 80,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A."
  }
}

That address is a Zyte proxy, a Nord VPN exit, a residential proxy, a known attacker, and cloud-hosted, all at once. The individual flags explain why the address falls in the high-risk band and provide more actionable context than the score alone, and once you are in the top band the individual flags tell you more than the number does.

The Node side, on Node 18 or later where fetch and AbortSignal.timeout are built in:

const RISK_ENDPOINT = "https://api.ipgeolocation.io/v3/security";

// Fail open. A checkout that 500s because a risk lookup timed out costs
// more than the fraud that lookup would have caught.
const UNAVAILABLE = { action: "allow", band: "unknown", reason: "lookup-unavailable" };

async function fetchRisk(ip) {
  const apiKey = process.env.IPGEO_API_KEY;
  if (!apiKey) throw new Error("IPGEO_API_KEY is not set");

  const url = `${RISK_ENDPOINT}?apiKey=${apiKey}&ip=${encodeURIComponent(ip)}`;

  // 1500ms is generous for this endpoint and still inside the budget of a
  // request a human is watching a spinner for.
  const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
  if (!res.ok) throw new Error(`risk lookup failed: HTTP ${res.status}`);

  return res.json();
}

function decide(security) {
  // Optional chaining throughout: any field can be missing on a partial
  // response, and a thrown TypeError here would block a paying customer.
  const score = security?.threat_score ?? 0;

  // Overrides first. These two outrank the band in both directions.
  if (security?.is_known_attacker === true) {
    return { action: "block", band: "override", reason: "known-attacker" };
  }
  if (security?.is_residential_proxy === true) {
    return { action: "review", band: "override", reason: "residential-proxy" };
  }

  // Private Relay and WARP are privacy routing, not evasion. Blocking these
  // can add unnecessary friction for legitimate privacy-relay users.
  if (security?.is_relay === true && score < 45) {
    return { action: "allow", band: "relay", reason: "privacy-relay" };
  }

  if (score >= 80) return { action: "block", band: "80-100", reason: "high-risk" };
  if (score >= 45) return { action: "step_up", band: "45-79", reason: "elevated-risk" };
  if (score >= 20) return { action: "context", band: "20-44", reason: "needs-context" };
  return { action: "allow", band: "1-19", reason: "low-risk" };
}

async function gate(req) {
// Configure Express `trust proxy` for the specific reverse proxies or subnets in front of this application, then read req.ip.
// Do not trust X-Forwarded-For directly or enable trust proxy globally unless every path to the app passes through a trusted proxy.

// Example only: replace these with the addresses or subnets of the
// reverse proxies that are allowed to supply forwarding headers.
// app.set("trust proxy", ["loopback", "10.0.0.0/8"]);

const ip = req.ip;

  try {
    const payload = await fetchRisk(ip);
    return decide(payload?.security ?? {});
  } catch (err) {
    console.error(`[risk-gate] ${ip}: ${err.message}`);
    return UNAVAILABLE;
  }
}

module.exports = { gate, decide };

Two things in there are load-bearing. The trust proxy note, because reading X-Forwarded-For directly is the single most common way this gets built wrong: the header is client-controlled, so an attacker just sets it to 8.8.8.8 and walks through your gate. And the fail-open default, which is a deliberate business call rather than a technical one. If your risk provider goes down, you either lose revenue or accept a few hours of unscreened traffic. I take the unscreened traffic. If you would rather fail closed, that is defensible, but decide it on purpose instead of discovering your choice during an outage.

The action strings are deliberately not booleans. context in particular is not a decision, it is an instruction to go look at your other signals, and collapsing it into allow or block throws away the entire point of the middle band.

Why not just use Stripe Radar

Fair question, and Radar ranks on the search results for this topic, so plenty of people are asking it.

Radar wins on signal. Its adaptive model uses hundreds of risk factors per payment plus data across Stripe's whole network, which is a dataset no IP API has. Its rules take four actions: request 3DS, allow, block, or review. If you are only going to run one of these two things, run Radar.

Three gaps are worth knowing about. Radar's granular 0 to 99 risk score, with its default 65 elevated and 75 high-risk thresholds, is a Radar for Fraud Teams feature rather than something you get with base Radar. Radar scores the initial payment of a recurring subscription and then evaluates rules without rescoring subsequent ones. And Radar operates on Charges, PaymentIntents, and SetupIntents, meaning it needs a payment object to exist before it has an opinion.

That last one is the actual argument for an IP gate, and it is not really a fraud argument. Card testing sweeps, credential stuffing against your login, coupon enumeration, and free-trial farming mostly never create a payment object at all. Radar cannot see any of it. A risk check at the edge covers requests that never become charges, which is a different job in a different place.

The other gap is explainability. Radar returns a score and an outcome. It does not tell you the connection came through a Zyte proxy last seen twelve days ago with 80% confidence. When you are writing a rule, or arguing with a customer whose order you held, that detail is the difference between a policy and a shrug.

Run both. Use the IP score to decide who gets to attempt a payment, and let Radar score the payment itself.

Tuning the bands against your own numbers

The four bands are a vendor default, and the vendor says so in the same breath as publishing them. Nobody else's thresholds are calibrated to your traffic mix.

Measure two things per band before you touch anything: what share of traffic lands in it, and what your chargeback rate is inside it. If your 80-100 band is 0.2% of traffic and carries a third of your chargebacks, the rule is working. If it is 6% of traffic and carries no more chargebacks than the 1-19 band, you are blocking customers for nothing, and the fix is to raise the threshold rather than to add more signals.

Here is the arithmetic people skip. Suppose 8% of your checkouts land in 45-79 and you send them all to a step-up, and 70% of those complete it. You have just added friction to 8% of checkouts and lost 2.4% of them outright. Whether that trade is good depends entirely on what fraud those 8% were actually carrying, and you cannot know until you have run the band in log-only mode for a few weeks.

The trap is tightening after a bad week. One chargeback cluster feels like evidence and is usually noise. Change one threshold at a time, wait out at least one full dispute cycle before judging it, and keep the log-only comparison running so you can tell what the old policy would have done.

What this will not catch

Worth being blunt about the ceiling, because a reference that oversells is worse than no reference.

Card testing from clean residential addresses defeats it completely. So does anything where the customer is genuinely who they claim to be and disputes the charge afterward, which is a large share of all chargebacks and has nothing to do with the network path. Account takeover from the victim's own home connection looks perfect on every field in that table. And an attacker who wants a clean residential IP can rent one for the price of a coffee, which is the honest limit of every IP-based control.

IP risk scoring is a cheap filter that removes the lazy and the automated. It signals, it does not prove, and any rule that treats a flag as a verdict on a customer will eventually hold an order it should not have.

A few extra notes

The security fields require a paid plan, starting at $19 a month with 150,000 credits. A security lookup costs 2 credits, so that allowance is 75,000 checks rather than 150,000, which is the kind of arithmetic worth doing before you put the call on every request. The free tier returns core geolocation and no security object at all. Credits are only charged on HTTP 200, so timeouts and errors cost nothing, and the X-Credits-Charged response header reports the actual charge per request.

Cache by IP with a short TTL, five to fifteen minutes depending on traffic. Risk data moves, last_seen dates shift, and an address that was clean this morning can be enumerated into a proxy pool by tonight. Caching for a day is how you end up allowing something you already know about.

If you want the country-mismatch layer that sits alongside this one, comparing IP country to billing country is a separate and complementary check, and I wrote that up separately.

ABDULLAH AFZAL

Jun 17

Stop the Chargeback Before It Ships: IP vs Billing Country

#webdev #security #node #php

13 min read

Both IPv4 and IPv6 are supported on the same endpoint, which matters more than it used to now that a real share of mobile traffic arrives over v6.

Start with the 80-100 rule and log the rest. Give it a month, look at where your chargebacks actually landed, and then decide whether the middle bands earn the friction they cost.

Detecting iCloud Private Relay (and Not Treating It Like a VPN)

ABDULLAH AFZAL — Fri, 24 Jul 2026 17:20:45 +0000

Your fraud stack sees a request from an IP it doesn't recognize, tags it anonymous, and quietly bumps the risk score. The user is a paying customer on an iPhone. They never turned on a VPN. They turned on iCloud Private Relay, a privacy feature included with iCloud+ that users can enable on their devices, and your rules just treated them like an attacker.

That misfire is common, and it's getting more common. Microsoft Sentinel users have reported anonymous-IP and anomalous-location alerts involving Private Relay sessions. The fix isn't to block harder. It's to detect relay traffic correctly and treat relay status as a privacy-service signal rather than evidence of malicious intent.

This post shows how to detect iCloud Private Relay and Cloudflare WARP on the server side, in curl and Node.js, and how to wire the result into fraud and geo logic without losing real users.

TL;DR:

iCloud Private Relay is not a VPN. It's a dual-hop privacy feature for Safari that preserves the user's country and does not let them fake a location.
Detect it server-side by reading is_relay and relay_provider_name from an IP security lookup, or match Apple's published egress ranges yourself.
Relay IPs can be shared by multiple users and may change between browsing sessions, so per-IP reputation and city-level geo are unreliable for these sessions.
The right handling: keep country-level rules, drop city-level precision, correlate on the account or session, and don't hard-block.
Cloudflare WARP is harder to isolate because its egress shares Cloudflare's edge IP space, so lean on a provider label rather than IP ranges.

Relay traffic can look anonymous to a coarse rule, but relay status alone is not evidence of abuse. Private Relay validates supported Apple devices and valid iCloud+ subscriptions, uses shared egress addresses, and preserves a coarse location. Detect it separately from VPN and proxy traffic, then combine the classification with account, device, payment, velocity, and behavioral signals before making a decision.

What Private Relay actually is (and why the IP fools you)

When Private Relay is on, Safari traffic takes two hops. The first hop goes to an Apple-run ingress that can see your real IP but not your destination. The second hop goes to a third-party egress (run by partners like Cloudflare, Akamai, and Fastly) that can see the destination but not your real IP. Your server only ever sees that egress IP.

Two consequences matter for detection. First, Private Relay protects Safari browsing, DNS resolution, and insecure HTTP traffic from apps. It is not a device-wide tunnel for all application traffic. So relay is a privacy-service connection signal, not proof that the user installed a conventional VPN or is attempting to conceal an arbitrary location. Second, the egress preserves coarse location. Per Apple's own description, Private Relay keeps users in their country and general region and does not let them present themselves as connecting from somewhere else. That's the opposite of a VPN's selling point.

The gotcha is that relay egress IPs can be shared by multiple users in a region and may change between browsing sessions, though they stay stable within a session. So two things break: per-IP reputation scoring becomes noise, because multiple unrelated users may share the address, and city-level geolocation is approximate and should not be used for strict location enforcement, because the egress location is approximate by design. Country-level geo still works.

Two ways to detect it

You can detect relay traffic without paying anyone, or you can get it plus a provider label in one API call. Both are legitimate; they trade maintenance for money.

The free path: Apple's egress list

Apple publishes the full set of relay egress ranges as a CSV at https://mask-api.icloud.com/egress-ip-ranges.csv. Each row is a CIDR block with a country, a language/region code, and a city:

# Fetch Apple's published relay egress ranges (CIDR, country, region, city)
curl --max-time 5 -s https://mask-api.icloud.com/egress-ip-ranges.csv | head -n 3
# 172.224.0.0/24,US,US-CA,San Francisco
# 172.225.0.0/24,US,US-NY,New York
# 2a04:4e41::/48,GB,GB-ENG,London

Load those CIDRs into anything that does fast prefix matching and check each incoming IP against them. Any match is Private Relay.

Treat the CSV as a maintained feed rather than a hard-coded lookup table. Refresh it on a schedule, validate each download before replacing the current copy, and retain the last-known-good version if an update fails. A non-match only means that the address is not present in the copy you currently have. The feed covers iCloud Private Relay; it does not classify Cloudflare WARP or other privacy services.

The API path: relay plus geo in one call

The other option is an IP intelligence lookup that returns geolocation and relay classification in the same response. The examples below use ipgeolocation.io's /v3/ipgeo?include=security endpoint, whose security object includes is_relay and relay_provider_name alongside other network-risk fields.

This is only one implementation option. If you only need iCloud Private Relay detection and can maintain the published ranges, Apple's CSV may be sufficient. If you also need classifications for WARP, VPNs, proxies, Tor, and other connection types, use an IP intelligence provider or dataset that fits your existing stack.

Detect relay with code

Here's the raw call. The API key goes in an environment variable, never in the source:

# Request geolocation and security classification in one response
curl --max-time 2 -s -G https://api.ipgeolocation.io/v3/ipgeo \
  --data-urlencode "apiKey=$IPGEO_API_KEY" \
  --data-urlencode "ip=172.225.46.223" \
  --data-urlencode "include=security"

For an iCloud Private Relay egress IP, the security object comes back like this. The location fields (country_code2, city, and so on) are in the same response; I've collapsed them to keep the focus on security:

{
  "ip": "172.225.46.223",
  "location": { "country_code2": "US", "country_name": "United States", "city": "New York" },
  "security": {
    "threat_score": 0,
    "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": true,
    "relay_provider_name": "Apple Relay",
    "is_anonymous": true,
    "is_known_attacker": false,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": false,
    "cloud_provider_name": ""
  }
}

Notice is_anonymous is true. That single flag is why naive rules blow up: a "block anonymous IPs" filter treats this validated Apple user exactly like a Tor exit node. The is_relay flag plus relay_provider_name is what lets you tell them apart.

For a verified Cloudflare WARP address, the security object uses the same field structure with a different provider label:

{
  "ip": "104.28.210.10",
  "security": {
    "threat_score": 50,
    "is_relay": true,
    "relay_provider_name": "Cloudflare WARP",
    "is_vpn": false,
    "is_proxy": false,
    "is_anonymous": true,
    "is_cloud_provider": false,
    "cloud_provider_name": ""
  }
}

Treat threat_score as a classification of the specific IP at the time of the lookup, not as a fixed or inherent score for all WARP traffic.

For contrast, here's a real VPN exit (2.56.188.34), which you should treat very differently. is_vpn is true, the provider is named, is_relay is false, and the threat score is high:

{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": ["Zyte Proxy"],
    "proxy_confidence_score": 80,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": ["Nord VPN"],
    "vpn_confidence_score": 80,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A."
  }
}

All three IPs report is_anonymous: true. Only the specific flags tell you which population you're looking at, and that difference is the whole point.

Now the same lookup in Node.js, wrapped so a slow or failed request never blocks a user. This uses the global fetch in Node 18 and later:

// classifyIp.js - Node 18+ (global fetch). No external deps.
const IPGEO_URL = "https://api.ipgeolocation.io/v3/ipgeo";

// A neutral result used when the lookup fails. Fail open: a geolocation
// outage should never lock out real traffic on its own.
const UNKNOWN = { isRelay: false, relayProvider: null, isVpnLike: false, threatScore: null, ok: false };

async function classifyIp(ip) {
try {  
    const key = process.env.IPGEO_API_KEY; // never hardcode the key
    if (!key) throw new Error("IPGEO_API_KEY is not set");

const url = `${IPGEO_URL}?apiKey=${key}&ip=${encodeURIComponent(ip)}&include=security`;
    // 1.5s ceiling: a request path can't wait on a third party forever.
    const res = await fetch(url, { signal: AbortSignal.timeout(1500) });
    if (!res.ok) return UNKNOWN; // 401 on free keys, 429 when rate-limited

    const data = await res.json();
    const s = data?.security ?? {}; // security is absent without include=security

    return {
      isRelay: s.is_relay === true,
      relayProvider: s.relay_provider_name || null, // "Apple Relay" | "Cloudflare WARP"
      isVpnLike: [s.is_vpn, s.is_proxy, s.is_residential_proxy, s.is_tor].some(Boolean),
      isDatacenter: s.is_cloud_provider === true,
      threatScore: typeof s.threat_score === "number" ? s.threat_score : null,
      country: data?.location?.country_code2 ?? null, // still trustworthy for relay
      ok: true,
    };
  } catch {
    // Timeout or network error. Return neutral and let other signals decide.
    return UNKNOWN;
  }
}

module.exports = { classifyIp };

The optional chaining matters because security simply isn't in the response unless you pass include=security, and reaching into an undefined object throws. The AbortSignal.timeout(1500) keeps a third-party hiccup from stalling your request path. And the neutral fallback means the worst case of a lookup failure is "we learned nothing," not "we blocked a customer."

Pitfall: Behind a load balancer, reverse proxy, or CDN, req.socket.remoteAddress usually belongs to the proxy rather than the user. Configure Express trust proxy to trust only your known proxy addresses or network path, then use req.ip. Do not read the leftmost X-Forwarded-For value directly, because clients may be able to spoof it if your proxy chain is not configured correctly.

Handle it correctly (the part everyone skips)

Detection is the easy half. The half that actually protects users is what you do with the result. Relay is a different population from VPN and proxy traffic, so it gets a different path.

// decideRisk.js
// IP classification informs the decision, but should not make it alone.

function decideRisk(c, context = {}) {
  const additionalRisk =
    context.highAccountRisk === true ||
    context.paymentCountryMismatch === true ||
    context.velocityExceeded === true ||
    context.impossibleTravel === true ||
    context.suspiciousBehavior === true;

  // A failed lookup should not block or escalate a user by itself.
  if (!c.ok) {
    return {
      allow: true,
      geoTrust: "unknown",
      escalate: additionalRisk,
      correlateBy: "account-or-session",
      reason: "ip-classification-unavailable",
    };
  }

  // Relay status alone is not suspicious.
  // Escalate only when stronger account or behavioral signals also exist.
  if (c.isRelay) {
  const relayHasAdditionalRisk =
    additionalRisk ||
    (c.threatScore ?? 0) >= 70;

  return {
    allow: true,
    geoTrust: "country",
    escalate: relayHasAdditionalRisk,
    correlateBy: "account-or-session",
    reason: `relay:${c.relayProvider ?? "unknown"}`,
  };
}

  const highNetworkRisk =
    c.isVpnLike ||
    (c.threatScore ?? 0) >= 70 ||
    (
      c.isDatacenter &&
      context.expectedConsumerTraffic === true
    );

  if (highNetworkRisk) {
    return {
      allow: true,
      geoTrust: c.isVpnLike ? "low" : "ip-geolocation",
      escalate: true,
      correlateBy: "account-session-and-ip",
      reason:
        c.isDatacenter && !c.isVpnLike
          ? "datacenter-in-consumer-flow"
          : "vpn-proxy-or-high-risk",
    };
  }

  return {
    allow: true,
    geoTrust: c.country ? "ip-geolocation" : "unknown",
    escalate: additionalRisk,
    correlateBy: "account-session-and-ip",
    reason: additionalRisk
      ? "non-network-risk"
      : "clean",
  };
}

module.exports = { decideRisk };

The policy keeps relay traffic on the normal path unless stronger account, payment, velocity, or behavioral signals justify additional verification. VPN, proxy, and high-risk network signals can trigger stricter treatment. Cloud-provider traffic is escalated only when it appears in a context where consumer traffic is expected, rather than because every cloud-hosted IP is inherently suspicious.

One thing worth saying out loud: don't escalate a relay session just because it's a relay session. Escalate when relay use pairs with something else that's actually suspicious, like a brand-new account, a payment country that doesn't match, signup velocity, or impossible travel. Relay on its own is a Tuesday.

Cloudflare WARP is the harder case

iCloud relay is tidy because Apple publishes the ranges and the second hop is identifiable. WARP is messier. Cloudflare's consumer VPN egresses through the same edge IP space (AS13335) that serves ordinary Cloudflare CDN traffic, and that space also carries iCloud Private Relay's second hop. So the IP and ASN alone can't reliably tell you "this is WARP" the way a CSV match tells you "this is iCloud relay."

That's why the provider label does the work here. A relay_provider_name of "Cloudflare WARP" is a classification from a dataset that has already done the disambiguation, which you can't reproduce from a public IP list. If you're rolling your own detection, WARP is the case where you'll want a feed or API rather than a static file.

Handle WARP as a separate connection category. Do not block a request solely because it uses WARP, but do not apply Apple-specific assumptions about validated iCloud+ subscriptions, Apple devices, or Safari traffic. WARP is a device-level tunnel that replaces the original IP with a Cloudflare address representing the user's approximate location. Combine the WARP classification with account, device, payment, velocity, and behavioral signals before choosing a normal, step-up, review, or block path.

A few extra notes

Cache successful classifications for a bounded period so the application does not repeat the same external lookup on every request. Use a shorter TTL for failed or unknown results, and choose the duration according to how much stale classification data your application can tolerate.

Remember the scope: Private Relay protects Safari web browsing, DNS resolution queries, and insecure HTTP traffic from apps. It is not a device-wide tunnel for all native app traffic, so secure app connections and certain excluded traffic may bypass it. For deeper background on how operators should treat relay sessions, see Cloudflare's operator guidance and Apple's WWDC session for developers.

Place classifyIp and decideRisk ahead of your existing fraud rules, then treat relay status as context rather than a verdict. Do not collapse Private Relay, WARP, VPNs, proxies, Tor, and cloud-hosted traffic into one anonymous-IP category. They represent different connection types, and the final decision should combine network classification with account, device, payment, velocity, and behavioral signals.

Card Testing Fraud: How the $1 Charge Storm Works and How to Stop It

ABDULLAH AFZAL — Wed, 15 Jul 2026 11:39:42 +0000

Card testing fraud turns your donation form into a free validator for stolen cards. Someone fires hundreds of tiny charges through it, watches which ones approve, and walks away with a verified list to resell or cash out somewhere else. You keep the chargebacks, the fees, and a payment processor that now thinks you are the risky one.

Donation forms are especially attractive targets because many accept arbitrarily low amounts with little friction. No cart, no shipping address, often no minimum. A donor can give $3.50 or $1.00, so a script giving $1.00 five hundred times does not look obviously wrong until the disputes land. The result can look like a $1 charge storm: a sudden spike of tiny authorizations and declines.

TL;DR

Card testing means submitting stolen card details through payment, authorization, or card-setup flows to determine which credentials are valid. Small payments are common, but a visible charge is not always required.
The attacker studies the authorization result and any exposed decline details. An approval confirms that the card can transact, while some decline responses can still confirm that the card number or other supplied details are valid; the money is incidental.
Donation forms are prime targets because they accept arbitrarily low amounts with little friction.
No single control stops it. You need layers: form controls, request-rate controls, and your payment processor's risk engine.
Your processor’s card-testing protections and risk engine are essential transaction-level defenses. Application controls should stop as much automated testing as possible before it reaches the payment rails.
IP reputation is a useful triage signal (is this a datacenter, a known proxy, a VPN?), not a wall. It is one input to a score, and it is evadable.
Do not rely on a single-IP or country block as your primary defense. Both can create false positives and do little against distributed traffic.

Card testing is an automated attack that abuses the low friction of a donation form to check stolen cards. Stopping it is a layering problem, not a single-tool problem: reduce the bot volume up front, let your processor's risk engine judge what remains, and use IP signals to decide who gets extra friction rather than who gets a door slammed on them.

What a card-testing attack actually is

Fraudsters buy stolen card numbers in bulk, but an untested list is less valuable because many of its cards may already be canceled, expired, frozen, or otherwise unusable. Testing sorts the live ones from the dead ones. The attacker submits each card through a payment, authorization, or card-setup flow and reads the response: an approval confirms a usable card, while a detailed decline can still reveal which part of the credential set is valid or incorrect. Stripe describes this plainly in its guide to card testing: the goal is validation, and the transaction amount barely matters.

That is why a $1.00 donation is an attractive testing method. The attacker is not trying to steal your $1.00. They are using your form as a credential-validation oracle, and a working card gets cashed out later at a merchant that sells something resellable.

Why donation forms are the perfect target

A checkout page often has more friction built in: a cart, a fixed product, sometimes an account, and billing or shipping details. Where supported, AVS can compare the billing address or postal code with the information held by the card issuer. A donation form strips most of that away on purpose, because friction kills donations. The same design that helps real donors helps the bot.

WooCommerce says it directly in its card-testing guidance: avoid pay-what-you-want or donation products with no minimum, because fraudsters use small arbitrary amounts that a cardholder may never notice. If transaction monitoring is weak, a low-value spike may go unnoticed until cardholders begin reporting the charges. Individual payments may also be small enough that cardholders do not report them immediately.

Anatomy of the $1 charge storm

The attack often has a recognizable pattern, although more sophisticated campaigns deliberately distribute their traffic to weaken these signals.

The card list and the bot

The attacker starts with a list, often generated or bought, sometimes built by guessing card numbers within a known BIN range (the first digits that identify the issuing bank). They point an automated script at your form. It runs from wherever compute is cheap and disposable: a rented cloud box, a pool of commercial proxies, sometimes a botnet of compromised residential machines so the traffic looks like real people.

The validation run

Then it fires. Dozens or hundreds of submissions in a short window, each a small donation, each a different card. The bot does not care about your thank-you page. It cares about the API response behind it. Approvals get flagged as usable cards. Declines are inspected for details that may reveal whether the card number, expiration date, CVC, or other supplied information was valid. If your form supports guest donations and does not challenge anything, the whole run can finish before anyone logs in.

In your logs it has a signature: a burst of attempts clustered in minutes, the same one or two donation amounts repeated, a high decline rate mixed with a few approvals, many distinct payment methods, sometimes concentrated within a small set of networks, devices, accounts, or sessions. If you graph transactions per minute, the storm is a spike relative to the form’s normal transaction baseline.

What happens after

The live cards move on to a real cash-out somewhere else, and your side of it may begin days or weeks later, when cardholders report the transactions and disputes start arriving.

What it actually costs you

If it were just noise, you could ignore it. It is not.

Each unauthorized test payment that becomes a dispute can add reversal costs, dispute fees, and operational work far beyond the original transaction amount. A flood of $1.00 tests can therefore cost far more than it ever donated. JPMorgan's merchant guidance on card testing makes the sharper point: the real damage is upstream. A high rate of small declines and disputes pushes your authorization decline rate up and can trigger additional scrutiny from your acquirer or payment partners, which can mean review, held funds, higher processing costs, or in a bad case losing the account. Stripe's own card-testing documentation warns that testing activity can degrade how the network sees you.

There is a quieter cost too. Cardholders may contact your organization after noticing unfamiliar charity charges, your support inbox fills up, and your reputation takes a hit.

The defense stack, and where each layer stops the attack

The mental model that helps most: an attack can be stopped at three points, and JPMorgan frames the goal well, which is to stop it before it reaches the acquirer. The earlier you intervene, the cheaper it is.

At the form

This is where you cut raw bot volume. A challenge on suspicious sessions (a CAPTCHA or an invisible bot check) can stop many basic automated scripts. A honeypot field that humans never see but bots fill in is close to free. One useful donation-specific control is a sensible minimum amount. It raises the cost of successful tests, but the threshold should reflect your normal donation patterns and should not be treated as a complete defense. Stripe's prevention guidance leads with the same three: restrict access to the form, add a CAPTCHA, and rate limit.

The gotcha with CAPTCHA: it is not a wall by itself. Solving services and more capable bots can bypass it, while CAPTCHA itself can add friction and reduce completion rates. Use it on risky sessions, not on everyone.

At the request

Here you cap how fast anything can hit the endpoint. Combine conservative IP and subnet velocity limits with session, account, email, device, and processor-level signals. Avoid hard subnet limits that could block users behind shared carrier or corporate networks. Cap attempts per session, account, email address, and processor-provided payment-method fingerprint or identifier. Do not store or log raw card numbers for rate limiting. If ten cards get tried from one network in thirty seconds, that is not a donor changing their mind.

At the processor

This is the transaction-level backstop. Stripe’s recommended integrations include automated card-testing protections such as rate limiters, risk models, and CAPTCHA triggers. These protections are separate from Radar’s fraudulent-dispute controls, although they use overlapping risk factors. Your processor can also evaluate payment, issuer, and network signals that your application cannot see. Use its recommended integration, collect CVC and billing information where supported, evaluate AVS as one signal, and apply risk-based 3DS where appropriate.

The IP layer, and why most advice about it is wrong

Almost every "how to stop card testing" list includes two IP tips: block the attacker's IP, and block transactions from outside your country. Neither is sufficient as a primary card-testing defense, and broad country rules can create false positives.

Blocking a single IP does little against a bot that rotates through a proxy pool or a residential botnet; you will be playing whack-a-mole against a new address every few seconds. Broad country blocking can also punish legitimate donors, especially when the organization accepts international support. A diaspora nonprofit takes real donations from exactly the countries a blunt geo-block would cut off. And plenty of legitimate traffic looks "foreign" or "anonymous" when it is not: someone donating through a corporate VPN that exits in another country, or an iPhone user on iCloud Private Relay, or Chrome's IP Protection. Treat those as attackers and you have quietly turned away real money.

Think of a supporter in Berlin who donates every year through their employer's VPN, which exits in Amsterdam. A country block or an “anonymous, deny” rule could lose that donation and never tells you why.

The signals that actually predict card testing

IP data is useful when you stop using it as a blocklist and start using it as a risk input. The signals that correlate with card testing are not "which country," they are "what kind of network":

Is the IP a datacenter or hosting provider? Hosting infrastructure is unusual for an ordinary donor’s browser session and can justify additional scrutiny, but it is not conclusive evidence of fraud. Card-testing bots can originate from rented cloud or hosting infrastructure.
Is it a known commercial proxy or VPN, and with what confidence? A high-confidence match to a datacenter proxy service is a strong signal; a low-confidence VPN guess is not.
Is it a residential proxy? This is the hardest case, because the traffic looks like a home connection. Residential-proxy detection is valuable because ordinary proxy checks may classify the connection as normal residential traffic.
Is it a relay (iCloud Private Relay, Chrome IP Protection)? A relay should not raise suspicion by itself. Treat it as neutral and continue evaluating the remaining signals. Relays are used by ordinary people.
Is there a velocity or geo anomaly? Many cards from one ASN in a minute, or a single session hopping continents, is the pattern to score on.

Several services expose some combination of these signals: IPQS, MaxMind minFraud, proxycheck.io, and IPGeolocation among them. Pick by whether they give you residential-proxy detection, provider attribution, and a confidence score, not just a raw boolean, because "it is a proxy" is less actionable than "it is associated with Zyte Proxy, with confidence 80 and a reported last-seen date". For the examples here I am using ipgeolocation.io's IP Security API because its response carries the provider names and confidence scores I want to score on, and a trial is available for testing the integration before using it in production.

A lookup against the dedicated /v3/security endpoint returns the full picture. Here is the real documented response for 2.56.188.34, which is a useful documented example of a high-risk response:

{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": ["Zyte Proxy"],
    "proxy_confidence_score": 80,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": ["Nord VPN"],
    "vpn_confidence_score": 80,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A."
  }
}

That is what you want to score on: a threat_score of 80, a named proxy (Zyte Proxy) with a confidence of 80 and a reported proxy_last_seen date, a hosting flag with the provider (Packethub S.A.), and is_known_attacker set. A country-only rule would not explain or distinguish any of those network-risk signals. Note the security lookup costs 2 credits per call, so cache and rate-limit your own lookups too.

Turning a signal into a decision

The point is not to block on any single flag. It is to fold the score into your existing risk logic and decide how much friction a session earns. High score, block or hold. Middle score, add a challenge or a 3-D Secure step-up. Low score, let it through. And a relay is not a strike against anyone.

// Node 18+.
// The IP check is one input; payment-provider controls still evaluate the transaction.

const IPGEO_KEY = process.env.IPGEO_API_KEY;

if (!IPGEO_KEY) {
  throw new Error("IPGEO_API_KEY is required");
}

async function assessIp(ip) {
  const url = new URL("https://api.ipgeolocation.io/v3/security");
  url.searchParams.set("apiKey", IPGEO_KEY);
  url.searchParams.set("ip", ip);

  try {
    const res = await fetch(url, {
      signal: AbortSignal.timeout(1500)
    });

    if (!res.ok) {
      throw new Error(`security lookup returned HTTP ${res.status}`);
    }

    const sec = (await res.json())?.security ?? {};
    const score = Number(sec.threat_score ?? 0);

    // Illustrative thresholds only.
    // Tune them using legitimate-traffic and fraud outcomes.
    if (score >= 80 || sec.is_known_attacker) {
      return { action: "block", reason: "high risk", score };
    }

    const highConfidenceProxy =
      sec.is_proxy &&
      !sec.is_relay &&
      Number(sec.proxy_confidence_score ?? 0) >= 80;

    if (score >= 45 || sec.is_cloud_provider || highConfidenceProxy) {
      return {
        action: "challenge",
        reason: "needs friction",
        score
      };
    }

    return {
      action: "allow",
      reason: sec.is_relay
        ? "relay without additional risk signals"
        : "low risk",
      score
    };
  } catch (err) {
    const message = err instanceof Error ? err.message : String(err);
    console.warn(`IP assessment skipped for ${ip}: ${message}`);

    // Fail open for this enrichment layer only.
    // The payment processor still evaluates the transaction.
    return {
      action: "allow",
      reason: "lookup unavailable"
    };
  }
}

Two things that trip people up here. First, get the client IP right. Behind a proxy or CDN, configure Express’s trust proxy setting to match your actual infrastructure, then use req.ip. Do not parse the raw X-Forwarded-For header yourself or blindly trust every proxy hop. Second, decide your failure mode on purpose. For a donation flow I fail open, because rejecting real donors when a third-party API blips is worse than letting one risky session reach a processor that is already scoring it. A login or a payout might fail closed instead. State the choice; do not let it be an accident.

And the honest ceiling: none of this is a wall. A residential proxy or a real-device botnet can make a bot look like a home broadband donor, and IP signals will shrug. That is expected. The IP layer buys you cheap triage, so the obvious junk gets blocked or challenged before it ever reaches your processor, and the processor's model handles the harder cases. Anyone selling IP reputation as a complete card-testing fix is overselling it.

Putting it together: a resilient donation form

Walk two sessions through the finished stack.

A real donor from Berlin on their corporate VPN hits the form. The IP looks like a VPN but the threat score is low and it is not a hosting range, so they get a CAPTCHA at worst, pass it, give $25.00, CVC and billing-address checks pass, done. Mildly annoying, not blocked.

A testing bot from a rented server hits the same form. It trips the velocity controls, and the IP lookup returns a high threat score with cloud-hosting and known-attacker signals, so the application blocks the request. Any attempts that still reach the payment processor are evaluated by its card-testing and fraud controls. The layers reduce the volume and impact of the attack before it becomes a flood.

Same form, very different outcomes, because the layers each did one job.

A few things people get wrong

Broad country blocking can feel decisive but often creates avoidable false positives. You lose legitimate international donors and a rotating botnet barely notices. Score on network type and behavior instead of geography.

CAPTCHA alone is not a solution. It stops lazy scripts and gets solved or bypassed by better ones, and a hard challenge on every donor costs you real gifts. Reserve it for risky sessions.

"Just block the IP" does not scale against address rotation. Rate limit by subnet and fingerprint, and lean on your processor for the transaction-level call.

And IP data is not enough on its own, which is the whole point of this article. It is one honest layer. The minimum amount, the request-rate caps, and the processor's risk engine are doing the heavy lifting; the IP signal just tells you who deserves a second look.

Where to start

Consider a sensible minimum that reflects your normal donation patterns, combine per-IP and per-session velocity controls, and use the card-testing protections recommended by your processor. Then add an IP risk check to decide who gets a challenge versus a clean path, and fail open for this enrichment layer so a timeout does not reject a donor by itself.

DEV Community: ABDULLAH AFZAL

A Self-Correcting Solar System Baseline From Sunrise/Sunset Data

What sun times can and cannot tell you

The three checks worth building

Gate alerts to the real daylight window

Watch the peak drift off solar noon

Normalize the baseline by day length

Pull the sun data

Build the baseline checker

Where this stops and irradiance begins

Enrich Elasticsearch Logs With GeoIP at Ingest

What the Elasticsearch geoip processor gives you

Step 1: Create the ingest pipeline

Step 2: Map location as geo_point before you index

Step 3: Wire the pipeline to your log stream

Step 4: Put it on a map in Kibana

Private and internal IPs return nothing

Backfilling indices you already have

When GeoLite2 is not enough

Operational notes

How Do You Detect Bogon and Reserved IPs in Code?

TL;DR

The special-use IP handling matrix

IPv4 special-use ranges and how your app should treat each

IPv6 ranges that actually reach applications

Bogon, martian, reserved: the distinction developers get wrong

Why your geolocation lookup returns 423 on these IPs

Detecting special-use IPs in code

Node.js: local classification with net.BlockList

PHP: a CIDR check without a library

Reject, flag, or accept: making the call

Keeping the list current

Which Proxy & VPN Signals Should Block a Signup?

TL;DR

The signup decision matrix

What each signal actually means at signup

Bots and known attackers

Tor exit nodes

Residential proxies

Datacenter and commercial proxies

Commercial VPNs

Relays: the false positive to stop making

Cloud provider IPs

Turning scores into thresholds

The false-positive costs you're trading against

Where these signals come from

A starter policy you can ship

A few things that trip people up

Classify an IP by ASN Type: Hosting, Business, ISP

The ASN-type classification matrix

One ASN lookup, one classification

The response and the type field

Lookup by IP or by AS number

A classifier you can copy

When ASN type is not enough

Subleased cloud: the operator is hosting, the tenant is a business

Corporate VPN: hosting-looking, entirely legitimate

Residential proxy: the one that reads consumer and isn't

CDN and anycast: the ASN bucket needs more context

Corroborating with ASN topology

Where this leaves you

Turn a List of IPs Into Location Data in Google Sheets

TL;DR

How to set it up

IP enrichment formulas

Location and network

Security signals

Shortcuts and bulk

Four workflows that make the data useful

Fraud and login review

Marketing campaign analysis

Server log enrichment

Compliance and access auditing

Handling larger datasets

What to watch out for

What's next

Automate IP Abuse Reports Into Your Ticket Queue

Abuse reputation vs operator reporting: two different jobs

What one lookup returns

Step 1: Resolve the abuse contact

Node.js: local classification with `net.BlockList`

Why `peers` may already contain your upstreams and downstreams