AbuseIPDB CLI Technical Details

Features

• Single IP check request ✓
• IP block check request ✓
• Blacklist request ✓
• Single IP report request ✓
• Bulk report request (send csv file) ✓
• Clear IP address request (remove your own reports) ✓
• Auto cleaning report comments from sensitive data (email, custom ip/domain names list) ✓
• Colored reports, JSON or plaintext output ✓
• Easy Fail2ban integration ✓

Requirements

• PHP >= 7.1
• PHP's cURL
• A valid abuseipdb.com account with an API key
• Composer for install

Dependencies

• kristuff/abuseipdb A wrapper for AbuseIPDB API v2
• kristuff/mishell Used to build CLI colored tables/reports

Configuration

1. Install

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'
  

2. Setup/change API key

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.

3. Setup self IPs

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.

Fail2ban integration

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.

  • example for reporting IP for web hack attempts using the log lines (matches) as comment:

  action = %(action_)s
          abuseipdb[abuseipdb_category="webattack", abuseipdb_comment="<matches>"]
  

  • example for reporting IP for port scan using a custom message with IP as comment :

  action = %(action_)s
          abuseipdb[abuseipdb_category="scan", abuseipdb_comment="Port scan detected from \[<ip>\]"]
  

  • example for reporting IP for brute force on ssh using a custom message with IP as comment:

  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

AbuseIPDB API Daily Rate Limits

The API daily rate limits are currently as follows:

Upon reaching your daily limit, you will receive an error (HTTP 429 Too Many Requests).