Sign in Start free

Flag and block abusive IPs with AbuseIPDB

Look client IPs up in AbuseIPDB, flag or block requests from abusive ones, block AbuseIPDB's blacklist on the first request, and report an abusive IP in one click. Your servers never wait on a lookup.

This page as Markdown

IP reputation checks the client IP of your API traffic against AbuseIPDB, a community database of IP addresses reported for abuse. A request from an abusive IP can be flagged in the firewall’s matches or blocked on every server. You can also report an abusive IP to AbuseIPDB from the request it came from.

Lookups never run inside your application’s request. ApiTraffic looks an IP up after its first request reaches us. If the IP is abusive, a short-lived deny reaches every server running your app within seconds. With the blacklist on, IPs AbuseIPDB already lists are refused on their first request too: your servers check them in memory, with no network call.

Before you begin

  • Your plan includes the Web application firewall, and you are an account owner or admin.
  • You have an AbuseIPDB account and an API key (Account > API). Lookups and reports use your key and its daily limits.
  • Your servers run @apitraffic/waf 2.1.0 or later. Earlier versions do not enforce IP reputation; ApiTraffic still flags abusive IPs in your traffic for them.
  • The client IP your framework reports is the real client’s. Behind a load balancer or proxy, tell your framework to trust it. See Country lists.

Connect AbuseIPDB

  1. Open the account area and select AbuseIPDB under Integration.
  2. Paste your API key and select Connect. ApiTraffic checks the key with one lookup before saving it.

The key is stored encrypted. Afterwards only its last 4 characters are shown, and it never reaches your servers or the browser. The page also shows the key’s status and how many lookups you have used today. To replace the key, paste a new one. To stop using AbuseIPDB, select Disconnect: IP reputation stops for every policy.

Turn it on in a policy

  1. Open Firewall (WAF), edit a policy and select IP Reputation.
  2. Choose a mode:
    • Monitor: requests from abusive IPs are recorded as would block, with rule reputation:abuseipdb. Nothing is blocked.
    • Enforcing: abusive IPs are denied on every server for the deny duration, then checked again.
  3. Optionally, turn on Block blacklisted IPs on their first request.
  4. Select Update.

Start in Monitor, review the matches, then switch to Enforcing.

Setting Default What it does
Confidence score 90 AbuseIPDB’s abuse confidence (0 to 100) at or above which an IP is abusive.
Minimum reports 2 An IP also needs at least this many reports, so one reporter cannot get it blocked.
Reports from the last 30 days How far back reports count.
Deny duration 3,600 seconds How long a deny lasts before the IP is checked again (60 seconds to 24 hours).
Block status 403 The status a reputation block answers with.
Mobile ISP score 100 The score for mobile carrier IPs. Many real users share one of these.
Tor exit nodes Off Treats Tor exit nodes as abusive, whatever their score.
Blacklist confidence minimum 100 The confidence of the blacklist your servers load. Free AbuseIPDB plans offer only 100.

Some IPs are never acted on:

  • IPs on one of your IP allow lists. Allow lists always win.
  • IPs on AbuseIPDB’s own allow list.
  • Private and reserved addresses.

What you see

A request whose client IP ApiTraffic has already looked up carries these tags:

  • apitraffic.ip.reputation.score
  • apitraffic.ip.reputation.reports
  • apitraffic.ip.reputation.verdict: abusive, clean, whitelisted or ignored.

The first request from a new IP has no tag: it is looked up afterwards.

Reputation decisions appear in the firewall’s matches with category reputation and one of these rules:

  • reputation:abuseipdb: monitored.
  • reputation:abuseipdb:sticky: blocked by a pushed deny.
  • reputation:abuseipdb:feed: blocked by the blacklist.

The request’s Firewall tab shows the IP’s score, report count and country. Select Check now for a live lookup.

Report an abusive IP

On a request’s Firewall tab, select Report IP to AbuseIPDB. ApiTraffic waits five seconds, so you can select Undo, then sends the report under your AbuseIPDB account.

  • Categories are filled in from the firewall’s finding. For example, SQL injection is reported as SQL Injection and Web App Attack. A request with no finding asks you to pick categories.
  • The comment is public. The default comment names only the finding, the method, a count and a time, never a host, path, payload or user. Select Edit report to change the categories or the comment. A comment that contains an email address, a token, a URL or another IP is refused.

AbuseIPDB accepts one report per IP every 15 minutes. If your account keeps only the network of client IPs, or none (see Client IP addresses), a request is reportable for 72 hours after the firewall flags it. After that, and for requests it never flagged, the full IP is no longer available.

Quotas and outages

Each IP is looked up at most once per cached result, whatever its traffic. A clean result is cached for 7 days and an abusive one for 6 hours. Accounts that use the same AbuseIPDB key share lookups.

When your daily limit runs low, suspicious traffic is looked up first, so requests with firewall matches or 401 and 403 responses come before ordinary ones. If AbuseIPDB is slow or down, or the limit is used up, nothing changes for your traffic. Lookups wait, the blacklist your servers have stays in force, and denies already pushed run to expiry.