csv
file) ✓The recommanded way to install CLI tool is to install kristuff/abuseipdb-client with composer. This is a bootstrap project that defines main program as dependency.
Why we do that? This is done to help deploying binary/config files and allow to update main project and dependencies together.
Install project and dependencies with composer create-project
command. This will create a folder named abuseipdb-client in the current directory and install dependencies:
$ composer create-project kristuff/abuseipdb-client
The project structure should be the following:
abuseipdb-client/
|_ bin/...
|_ config/...
|_ 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-client/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 /usr/local/bin/
or /usr/sbin/
:
This task requires root or administrator permissions.
ln -s /YOUR_PATH/abuseipdb-client/bin/abuseipdb /usr/local/bin/
or create an alias
:
$ alias abuseipdb='php /YOUR_PATH/abuseipdb-client/bin/abuseipdb'
After install, run abuseipdb -S
or abuseipdb --save-key
to register your API key (requires writing permissions on the config directory).
$ abuseipdb -S YOUR_API_KEY
# or
$ abuseipdb --save-key YOUR_API_KEY
You cound also create a key.json
file in the config
path and define your api key like this:
{
"api_key": "YOUR ABUSEIPDB API KEY"
}
Then, if you want to change your config, edit the key.json
or run abuseipdb -S
again to recreate it.
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, create a file self_ips.json
in the config
path like this:
{
"self_ips": [
"xx9999.ip-256-256-256.xx",
"256.256.256.256",
"subdomain.example.com",
"example.com",
"example"
]
}
Order does matter. Enter subdomains first to prevent to replace a part of field only.
AbuseIPDB provides a tutorial about integrating their API with Fail2Ban to automatically report bad IPs you should read first.
By default, the actionban
curl command send 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.conf
or /etc/fail2ban/jail.local
(the customizable version) contain 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/ In the file /etc/fail2ban/action.d/abuseipdb.conf
, replace the actionban
command like this (Adjust the binary path depending on your install, below /usr/sbin/
):
actionban = /usr/sbin/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 action
definition:
abuseipdb[abuseipdb_category=" ... ", abuseipdb_comment=" ..."]
The following examples suppose your default action is
%(action_)s
in 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
fail2ban-client reload
The API daily rate limits are currently as follows:
Commands | Standard | Webmaster | Supporter | Basic Subscription | Premium Subscription |
---|---|---|---|---|---|
check | 1,000 | 3,000 | 5,000 | 10,000 | 50,000 |
blacklist | 5 | 10 | 20 | 100 | 500 |
report | 1,000 | 1,000 | 5,000 | 10,000 | 50,000 |
check-block | 100 | 250 | 500 | 1,000 | 5,000 |
bulk-report | 5 | 10 | 20 | 100 | 500 |
clear-address | 5 | 10 | 20 | 100 | 500 |
Upon reaching your daily limit, you will receive an error (HTTP 429 Too Many Requests).