Since v0.9.14, abuseipdb-client is available as debian package (
.deb). Packages are available on packages.kristuff.fr/debian/. You can configure
apt to connect kristuff repository (see instructions here: packages.kristuff.fr/) and install it:
apt-get update apt-get install abuseipdb-client
Alternatively, you can download the latest package (from release tags on github or from repository) and install it using
# ----------------------------------------------- # /!\ Please change "X.X.X" to the latest version # https://packages.kristuff.fr/debian/pool/main/a/abuseipdb-client/ # ----------------------------------------------- wget https://packages.kristuff.fr/debian/pool/main/a/abuseipdb-client/abuseipdb-client_X.X.X_all.deb dpkg -i abuseipdb-client_X.X.X_all.deb # OR apt install ./abuseipdb-client_X.X.X_all.deb
Main library is deployed to
/usr/lib/abuseipdb-client/ and executable (symlink) to
/usr/bin/. Since v0.9.15, the config files are located in
You need composer to install the project.
Install project and dependencies with composer
create-project command. This will create a folder named abuseipdb-cli in the current directory and install dependencies:
$ composer create-project kristuff/abuseipdb-cli
The project structure should be the following:
abuseipdb-cli/ |_ bin/... |_ config/... |_ src/... |_ vendor/... composer.json composer.lock LICENCE
Make sure the binary file
abuseipdb, located in the
bin folder at the project root, is executable:
$ chmod +x /YOUR_PATH/abuseipdb-cli/bin/abuseipdb
To use it more easily and depending on how you want to use it (from terminal only or with other scripts), you could:
deploy the bin file to
This task requires root or administrator permissions.
ln -s /YOUR_PATH/abuseipdb-cli/bin/abuseipdb /usr/local/bin/
or create an
$ alias abuseipdb='php /YOUR_PATH/abuseipdb-cli/bin/abuseipdb'
In manual install, the configuration file (
conf.ini) is located in the
config directory. In case package is installed globally, configuration file is located in
In most of the cases you should not modify the
conf.ini file directly but provide customizations in a
local.ini file under the same directory. This prevents to loose changes during update.
You must at least define your api key. Other fields are optional.
Edit the configuration file
local.ini and set up the
api_key property in the
[common] api_key= "123456789"
If you plan to automate reports with Fail2ban and send logs lines as message (matches), it's recommended to configure a whitelist of IPs and names (domain name) you want to exclude from message. When you use the
report command, comments are checked and fields that match to an entry in the list are replaced by
*. Note that email addresses are already replaced.
To use a whitelist, edit the configuration file
local.ini and set up the
self_ips property in the
[report] section like this:
[report] self_ips= "xx9999.ip-256-256-256.xx ,256.256.256.256, subdomain.example.com,example.com, example"
Ips or names must be comma separated, and may contain spaces (will be trimmed). Order does matter: Enter subdomains first to prevent to replace a part of field only.
To setup a default timeout, locate and edit the configuration then set the
timeout property in the
Timeout is expressed in milliseconds. 0 means no timeout.
Timeout will apply to all API requests.
[common] ; setup a default timeout of 5 secs timeout= 5000
You can overwrite the default value in command line with the
AbuseIPDB provides a tutorial about integrating their API with Fail2Ban to automatically report bad IPs you should read first.
The default action for reporting an ip address, definided in file
action.d/abuseipdb.conf, sends logs lines as message (matches) while they may contain sensitive data.
You can use in place kristuff/abuseipdb-cli and its built-in filter in
report command (see Report a single IP address):
1/ Check your have Fail2Ban v0.10.0 or later installed (
fail2ban-client -V) and check the file
/etc/fail2ban/jail.local (the customizable version) contains the following definition for action_abuseipdb:
# Report ban via abuseipdb.com. # # See action.d/abuseipdb.conf for usage example and details. # action_abuseipdb = abuseipdb
2/ Make sure the file
/etc/fail2ban/action.d/abuseipdb.conf exists, and overwrite the
actionban by creating a file
/etc/fail2ban/action.d/abuseipdb.local with the following content (Adjust the binary path depending on your install, below
[Definition] actionban = /usr/bin/abuseipdb -R "<ip>" -c "<abuseipdb_category>" -m "<abuseipdb_comment>" > /dev/null
3/ In the file
/etc/fail2ban/jail.local, for each jail you want report IP each time an IP is banned, add a line to the
abuseipdb[abuseipdb_category=" ... ", abuseipdb_comment=" ..."]
The following examples suppose your default action is
%(action_)sin your jails.
action = %(action_)s abuseipdb[abuseipdb_category="webattack", abuseipdb_comment="<matches>"]
action = %(action_)s abuseipdb[abuseipdb_category="scan", abuseipdb_comment="Port scan detected from \[<ip>\]"]
action = %(action_)s abuseipdb[abuseipdb_category="ssh,brute", abuseipdb_comment="SSH brute force attack detected from \[<ip>\]"]
4/ Restart or reload Fail2Ban
The API daily rate limits are currently as follows:
|Commands||Standard||Webmaster||Supporter||Basic Subscription||Premium Subscription|
Upon reaching your daily limit, you will receive an error (HTTP 429 Too Many Requests).