Kristuff.
  • Accueil
  • Projets
    • AbuseIPDB
      • Overview (EN)
      • API Documentation (EN)
      • Technical details (EN)
    • AbuseIPDB CLI
      • Overview (EN)
      • API Documentation (EN)
      • Technical details (EN)
    • Phtemail
      • Overview (EN)
      • Demo (EN)
    • Parselog
      • Overview (EN)
      • API Documentation (EN)
    • Mishell
      • Overview (EN)
      • API Documentation (EN)
    • Apache Fancy Pages (EN)
    • Echolor (EN)
    • Minitoring (EN)
    • Gogs Themes (EN)
    • Patabase (EN)
    • Tous les projets →
  • Blog
  • Outils
    • Links
    • Css Filter
    • Timestamp
    • Htpasswd
    • Chmod calculator
    • Ip Detector
    • Tous les outils →
  • À propos
  • Connexion
  • Accueil
  • Projets
  • AbuseIPDB-CLI
  • Technical Details
Technical Details
GITHUB STARS 31 DOWNLOADS 116 LICENSE MIT STABLE v0.9.19
PHP AbuseIPDB API CLI
  • Overview
  • Documentation
  • Technical Details

AbuseIPDB CLI Technical Details

Build Status Scrutinizer Code Quality Latest Stable Version License Total Downloads

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 (not required if you use .deb package)

Dependencies

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

Install

Debian based distros

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 dpkg -i:

# -----------------------------------------------
# /!\ 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 /etc/abuseipdb-client/.

Other distros

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 /usr/local/bin/ or /usr/sbin/:

    This task requires root or administrator permissions.

    ln -s  /YOUR_PATH/abuseipdb-cli/bin/abuseipdb  /usr/local/bin/
    
  • or create an alias:

    $ alias abuseipdb='php /YOUR_PATH/abuseipdb-cli/bin/abuseipdb'
    

Configuration

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 /etc/abuseipdb-client/.

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.

Setup/change API key

Edit the configuration file conf.ini/local.ini and set up the api_key property in the [common] section.

[common]
api_key= "123456789"

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, edit the configuration file conf.ini/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.

Setup default timeout

To setup a default timeout, locate and edit the configuration then set the timeout property in the [common] section. 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 -t | --timeout option.

Fail2ban integration

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.conf or /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 /usr/bin/):

    [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 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:

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).

CONTENT
  • Features
  • Requirements
  • Dependencies
  • Install
    • Debian based distros
    • Other distros
  • Configuration
    • Setup API key
    • Setup self IPs
    • Setup default timeout
  • Fail2ban integration
  • AbuseIPDB API Daily Rate Limits
SEE ALSO
Overview Documentation Code source →
Explorer.
  • À propos
  • Blog
  • Projets
  • Outils
  • Kristuff Packages
  • Kristuff Git
  • Test de Julien à nouveau
  • Pwitter
Projets.
  • AbuseIPDB
  • AbuseIPDB-CLI
  • Phtemail
  • Mishell
  • Parselog
  • Apache Fancy Pages
  • Echolor
  • Patabase
  • Minitoring
  • Gogs Themes
Outils.
  • Links
  • Css Filter
  • Timestamp
  • Htpasswd
  • Chmod calculator
  • Ip Detector
Suivre Kristuff.
  • Twitter
  • Github
  • CodePen
  • Stackoverflow
  • Mastodon
  • Linkedin
  • Pwitter
  • Flux RSS
Kristuff.
© 2015-2023 Christophe Buliard Tous droits réservés | Made within France | Mentions légales | Contact | Flux RSS