Skip to content

AbuseIPDB

15.09

This section walks you through integrating AbuseIPDB with your ConfigServer Security and Firewall setup.

Think of AbuseIPDB as the arcade game Asteroids; harmful attackers and malicious IPs are like asteroids hurtling toward your server. As soon as they get too close, you blast them away for a satisfying 100 points per hit.

With this integration, you get real-time intelligence on abusive IPs, giving you the upper hand in the never-ending game of protecting your server from the digital cosmos.


Useful Resources

The following are useful resources associated with this page.



What is AbuseIPDB?

AbuseIPDB is a community-driven project focused on tracking and sharing information about IP addresses involved in abusive or malicious activity across the internet. The service allows individuals to report IPs associated with behaviors such as brute-force attacks, spam, port scanning, DDoS attempts, and other forms of network abuse. Each report includes contextual details like the abuse category, a brief description explaining the cause for the report, and the time it was observed.

The platform aggregates reports from thousands of contributors worldwide and analyzes them to generate an abuse confidence score for each IP address. This score is calculated based on factors such as how frequently an IP is reported, the severity of the reported activity, and how recent the reports are. AbuseIPDB also maintains historical data, allowing users to see patterns over time and understand what types of abuse an IP has been associated with.

AbuseIPDB offers both a free tier and several paid plans with expanded capabilities.

The free plan includes:

  • 1,000 IP checks and reports per day
  • 100 bulk blocklist checks per day
  • Access to a basic blacklist of up to 10,000 IPs

Users can interact with AbuseIPDB through its web interface for manual lookups, or integrate it directly into scripts, firewalls (including CSF), and security tools using the official AbuiseIPDB API. This flexibility makes it valuable for individual server operators as well as large-scale infrastructure and security teams.



Before You Begin

Before integrating AbuseIPDB with CSF, make sure that ConfigServer Security & Firewall (CSF) is already installed and working correctly on your server.

If CSF is not yet installed, begin with the Installation guide. That section walks you through installing the required dependencies, downloading CSF, and completing the initial setup so your system is ready for AbuseIPDB integration.



Setup Integration

Before continuing with the AbuseIPDB integration, make sure you have already completed the CSF installation by following our Installation Guide. This ensures that all required dependencies are in place and that CSF is properly installed on your system.

Once CSF is installed, visit the AbuseIPDB website and create an account. Click the Sign Up button at the top of the page, which will take you to the tier selection screen where you can choose the plan that best fits your needs.


AbuseIPDB › Select a Tier
AbuseIPDB › Select a Tier


You may start with the Free tier if you simply want to evaluate the service. This plan allows up to 10,000 IP addresses in your blocklist.

If you require higher limits or additional features, paid plans are available, increasing the blocklist capacity to 100,000 IPs and beyond.

Once you have selected the desired tier, the next page will ask you for your information.

Don't forget to confirm you are human at the bottom page the page. (You are human, right?)


AbuseIPDB › Register
AbuseIPDB › Register


After you complete the sign-up process, you should be re-directed to your Account home page. On the left-side navigation menu, select


On the right-side of the My API page, click the button:

image/svg+xml Create Key

AbuseIPDB › Account › Nav Menu
AbuseIPDB › Account › Nav Menu


When clicking the Create Key button, a dialog box will appear and ask you to specify a Name. The name serves no purpose other than identifying what this API key is associated with:


AbuseIPDB › Account › Nav Menu
AbuseIPDB › Account › Nav Menu


After saving the new name, the page should refresh and show you the new API key:


AbuseIPDB › Account › API Key
AbuseIPDB › Account › API Key


After getting your AbuseIPDB API key, we now need to integrate it into CSF. Open the file /etc/csf/csf.blocklists on your server with the desired editor:

sudo nano /etc/csf/csf.blocklists


Scroll through its contents until you locate the code shown below. If this section does not already exist in your copy of CSF, add the following code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# #
#   @blocklist              AbuseIPDB
#   @details:               https://abuseipdb.com/account/api
#   @notes:                 Requires you to create an account.
#                           Requires you to generate an API key.
#                           Add your generated API key in the URL below by 
#                               replacing `YOUR_API_KEY`.
#                           Change the 3rd field `10000` to a higher number
#                               if you are on a paid plan.
#                           Replace `&limit=10000` at the end of the URL with
#                               the same limit value.
#   
#                           Full documentation at:
#                               https://docs.configserver.dev/install/integrations/abuseipdb/
# #

#   ABUSEIPDB|86400|10000|https://api.abuseipdb.com/api/v2/blacklist?key=YOUR_API_KEY&plaintext&limit=10000


To enable the AbuseIPDB integration, start by removing the # character at the beginning of the line to uncomment it. Next, edit the URL and replace YOUR_API_KEY with the AbuseIPDB API key you generated earlier.

When finished, the query string should look similar to ?key=abcdefghi0123456789, using your actual API key in place of the example.

If you are subscribed to a paid plan, you can also increase the value 10000 to a higher number. This value defines the maximum number of IP addresses CSF is allowed to retrieve from the AbuseIPDB blocklist via the API.

Free accounts are limited to 10,000 IPs, while paid plans allow higher limits depending on your subscription tier.

Plan Price Maximum Blocklist IPs
Individual Free 10,000
Basic $25.00/month 100,000
Premium $99.00/month 500,000
Enterprise - Contact AbuseiPDB Sales


Once you have enabled and configured AbuseIPDB, save the file and close it.

The final step is to restart the CSF services so that the changes take effect and the blocklists can be downloaded. Open your terminal and run the following command:

csf -ra


Open your lfd log file at /var/log/lfd.log

cat /var/log/lfd.log


You should see the following in your log file:

Dec 15 11:14:24 configserver lfd: Retrieved and blocking blocklist ABUSEIPDB IP address ranges
Dec 15 11:14:24 configserver lfd: IPSET: loading set new_ABUSEIPDB with 10000 entries
Dec 15 11:14:24 configserver lfd: IPSET: switching set new_ABUSEIPDB to bl_ABUSEIPDB


If you see an error in your log file such as the following:

Dec 15 11:14:53 configserver lfd: Unable to retrieve blocklist ABUSEIPDB - Unable to download: Not Found


The error above means that you have configured something incorrectly. Ensure that the URL does not contain typos, and also make sure you copied your AbuseIPDB API key correctly.



While the free tier of AbuseIPDB is a great way to get started, one of the most valuable advantages of becoming a paid supporter is access to the Blacklist customization tools.

This section outlines some of the best features associated with AbuseIPDB paid plans.

Confidence Levels


AbuseIPDB › Blacklist › Confidence
AbuseIPDB › Blacklist › Confidence


The confidence level determines how strict AbuseIPDB is when deciding which IP addresses are included in your blocklist:

  • High Confidence level

    • Only IPs with a strong history of abusive behavior are included.
    • Pros:
      • Significantly reduces the chance of blocking legitimate users.
      • Ideal for production servers where availability and user access are critical.
    • Cons:
      • Some newer or less frequently reported malicious IPs may not be blocked.

  • Low confidence level

    • Includes IPs with fewer or less severe abuse reports.
    • Pros:
      • More aggressive protection against potential threats.
      • Useful for high-risk environments or servers that are frequent attack targets.
    • Cons:
      • Higher risk of false positives, which may block legitimate traffic.

Choosing the right confidence level depends on your server’s purpose and risk tolerance. Paid tiers give you the flexibility to strike the balance that best fits your environment.

With a free account, adjusting the confidence slider does not change the results you receive.

Paid plans unlock this feature, allowing you to fine-tune the generated blocklist so you can strike a better balance between security and legitimate access to your server.

Once you have selected your desired confidence level, scroll down to the right-hand side of the page and locate the API Endpoint section. Each time you adjust the confidence slider, the API URL will automatically update to reflect your current settings.


AbuseIPDB › Blacklist › Confidence
AbuseIPDB › Blacklist › Confidence


When you have the desired settings, scroll down the page and locate the right-side box labeled API Endpoint, and take note of the values within the generated URL:

AbuseIPDB › Blacklist › Confidence
AbuseIPDB › Blacklist › Confidence


You will need to apply these values to your AbuseIPDB blocklist entry inside of the file /etc/csf/csf.blocklists:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# #
#   @blocklist              AbuseIPDB
#   @details:               https://abuseipdb.com/account/api
#   @notes:                 Requires you to create an account.
#                           Requires you to generate an API key.
#                           Add your generated API key in the URL below by 
#                               replacing `YOUR_API_KEY`.
#                           Change the 3rd field `10000` to a higher number
#                               if you are on a paid plan.
#                           Replace `&limit=10000` at the end of the URL with
#                               the same limit value.
#   
#                           Full documentation at:
#                               https://docs.configserver.dev/install/integrations/abuseipdb/
# #

 ABUSEIPDB|86400|9999999|https://api.abuseipdb.com/api/v2/blacklist?key=YOUR_API_KEY&plaintext&limit=9999999&confidenceMinimum=25


Once you have modified the values; give CSF a restart using the command:

sudo csf -ra


You should now be using the parameters you picked from the Blacklist page.



Contribute to AbuseIPDB

Optional

This step is optional.

Proceed only if you would like to support AbuseIPDB’s mission to maintain a shared database of malicious IP addresses. By contributing, you help protect not only your own server, but also other server owners who rely on AbuseIPDB to detect and block harmful activity.

In addition to using AbuseIPDB to block malicious traffic, you can also help strengthen the platform by reporting abusive activity detected on your own server. By submitting reports for IP addresses that attempt to carry out malicious actions, you contribute to a shared reputation system that benefits the wider security community.

When CSF detects and blocks a malicious connection attempt, that event can be reported directly to AbuseIPDB. These reports become visible to other AbuseIPDB users, helping them identify and preemptively block the same abusive sources before they cause harm elsewhere.

To make this process easy, AbuseIPDB has provided multiple integration scripts that can be deployed alongside CSF. Since CSF itself is written in Perl, a native Perl reporting script is included.

However, they also offer Bash and Python versions of the integration script, allowing you to choose the language that best fits your environment or workflow.

Once configured, these scripts automatically submit reports to AbuseIPDB whenever CSF blocks a malicious IP, turning your firewall into an active contributor to the global abuse reporting network.


Setup

To configure CSF to detect malicious access attempts and report them to AbuseIPDB, choose one of the scripts provided below, create a new file with the selected code, and save it to a location on your server. The file may reside anywhere, as you will specify its path in CSF shortly.

The directory where you place this file determines where the script will be executed whenever CSF starts and identifies a malicious attempt against your server.


abuseipdb_block.pl
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
#!/usr/bin/perl
# This file was written as an executable to be used in the auto report function
# of csf and lfd. By replacing $YOUR_API_KEY below with your abuseipdb api key,
# allows you to use this code to integrate your csf system with abuseipdb.com
use strict;
use warnings;
use HTTP::Tiny;
use JSON;

# Gather the information from the commandline passed by lfd
my $ports = $ARGV[1];
my $inout = $ARGV[3];
my $message = $ARGV[5];
my $logs = $ARGV[6];
my $trigger = $ARGV[7];
my $comment = $message . "; Ports: " . $ports . "; Direction: " . $inout
    . "; Trigger: " . $trigger . "; Logs: " . $logs;
my $ua = HTTP::Tiny->new;

my $url = 'https://api.abuseipdb.com/api/v2/report';

my $data = {
    ip => $ARGV[0],
    comment => $comment,
    categories => 14
};

my %options = (
   "headers", {
       "Key" => "$YOUR_API_KEY",
       "Accept" => "application/json"
   },
);

my $response = $ua->post_form($url, $data, \%options);
my $json = JSON->new;
my $output = $json->pretty->encode($json->decode($response->{'content'}));

if ($response->{'status'} == 200){
    print "Report Succesful!\n" . $output;
} elsif ($response->{'status'} == 429) {
    print $output;
} elsif ($response->{'status'} == 422) {
    print $output;
} elsif ($response->{'status'} == 401) {
    print $output;
}
abuseipdb_block.sh
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
#!/usr/bin/sh

# Set your AbuseIPDB API key here.
key="f4635bfa5be867bcd3543064934716df3506bf8dbfe9daaedd896331b465851f0e3049daa6add6d2"

# Choose the appropriate AbuseIPDB category ID depending on what LFD is scanning.
# https://www.abuseipdb.com/categories
categories="18,22"

# Rename arguments for readability.
ports=$2
inOut=$3
message=$6
logs=$7
trigger=$8

# Concatenate details to form a useful AbuseIPDB comment.
comment="${message}; Ports: ${ports}; Direction: ${inOut}; Trigger: ${trigger}; Logs: ${logs}"

curl https://api.abuseipdb.com/api/v2/report \
  --data-urlencode "ip=$1" \
  -d categories=$categories \
  --data-urlencode "comment=$comment" \
  -H "Key: $key" \
  -H "Accept: application/json"
abuseipdb_block.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
#!/usr/bin/env python

import requests
import json
import sys

# Defining the api-endpoint
url = 'https://api.abuseipdb.com/api/v2/report'
ports = sys.argv[2]
inOut = sys.argv[4]
message = sys.argv[6]
logs = sys.argv[7]
trigger = sys.argv[8]
comment = message + "; Ports: " + ports + "; Direction: " + inOut + "; Trigger: " + trigger + "; Logs: " + logs
headers = {
     'Accept': 'application/json',
     'Key': '$YOUR_API_KEY'
}
# String holding parameters to pass in json format
querystring = {
    'ip':sys.argv[1],
    'categories':'14',
    'comment':comment
}


response = requests.request(method='POST', url=url, headers=headers, params=querystring)

decodedResponse = json.loads(response.text)

if response.status_code == 200:
    print(json.dumps(decodedResponse['data'], sort_keys=True, indent=4))
elif response.status_code == 429:
    print (json.dumps(decodedResponse['errors'][0], sort_keys=True, indent=4))
elif response.status_code == 422:
    print (json.dumps(decodedResponse['errors'][0], sort_keys=True, indent=4))
elif response.status_code == 302:
    print('Unsecure protocol requested. Redirected to HTTPS.')
elif response.status_code == 401:
    print (json.dumps(decodedResponse['errors'][0], sort_keys=True, indent=4))
else:
    print('Unexpected server response. Status Code:' + response.status_code)


Ensure the script is executable by applying +x execute permissions using one of the commands below:

sudo chmod +x abuseipdb_block.pl

sudo chmod +x abuseipdb_block.sh

sudo chmod +x abuseipdb_block.py


Once the permissions have been updated, you can enable reporting for the script. Open the CSF configuration file at /etc/csf/csf.conf and modify the following setting. Chnage /path/to to the location where you placed one of the scripts provided above:

BLOCK_REPORT = "/path/to/abuseipdb_report.pl"
Blocklist Reporting Process

When triggered, LFD executes the script specified by the BLOCK_REPORT setting as a forked process. If the script does not complete within 10 seconds, it is automatically terminated.

Because this script runs with root privileges, extreme caution should be taken to ensure the security and integrity of the BLOCK_REPORT script.


After you have configured CSF to utilize the new AbuseIPDB reporting script, give CSF a restart:

sudo csf -ra


Notes

Take note of the following pieces of information if you have issues with AbuiseIPDB integration and malicious IP reporting:


Testing Mode

If CSF or AbuseIPDB fails to start or does not behave as expected, verify that Testing Mode is disabled.
To do this, edit the CSF configuration file located at /etc/csf/csf.conf and ensure the TESTING option is set to 0.


TESTING

1 /etc/csf/csf.conf

Defines how often the cron job runs, in minutes. This timing is based on the system clock, not when you manually start the firewall.

For example, if the interval is set to 5 minutes, the job will trigger at regular 5-minute marks past the hour — meaning the firewall could reset anywhere between 0 and 5 minutes after startup.


CSF Restarts Slow

If CSF takes too long to restart, modify CSF's FASTSTART setting in the file /etc/csf/csf.conf and set the value to 0.


FASTSTART

1 /etc/csf/csf.conf

This option uses IPTABLES_SAVE, IPTABLES_RESTORE and IP6TABLES_SAVE, IP6TABLES_RESTORE in two ways:

  1. On a clean server reboot the entire csf iptables configuration is saved and then restored where possible to provide a near instant firewall startup

  2. On csf restart or lfd reloading tables, CC_* as well as SPAMHAUS, DSHIELD, BOGON, TOR are loaded using this method in a fraction of the time than if this setting is disabled

Set to 0 to disable this functionality


Logs

All activity performed by CSF and lfd is recorded in /var/log/lfd.log. Review this log to identify blocked or locked access attempts against your server.



Conclusion

By completing this guide, you have successfully integrated AbuseIPDB into CSF as an active blocklist provider. This integration adds an additional layer of protection by automatically blocking IP addresses with a known history of abusive behavior, significantly reducing unwanted traffic before it ever reaches your services.

The primary advantage of AbuseIPDB is its community-driven intelligence. Reports submitted by thousands of administrators and security professionals worldwide allow CSF to proactively defend against threats such as port scanning, brute-force attacks, spam attempts, and other malicious activity. Rather than reacting after an incident occurs, your server can now deny access to repeat offenders in advance.

Combined with CSF’s existing firewall and security features, AbuseIPDB helps harden your system, lowers log noise, and reduces the load caused by automated bots; allowing you to focus on legitimate traffic and server management with greater confidence.



Next Steps

Select what documentation you would like to proceed with next ...

  •   Geographical IP Block Integration

    Geographical IP blocking allows you to control access to your server based on the country or region an IP address originates from, rather than individual IP reputation or blocklist entries.

    This section explains what geographical IP blocks are, how they differ from blocklists and IPSETs, and when it makes sense to use country-based filtering.

    You’ll also learn how to integrate CSF with GeoIP data providers to apply regional access rules safely and efficiently.