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
  • Api Documentation
Api Documentation
GITHUB STARS 31 DOWNLOADS 116 LICENSE MIT STABLE v0.9.19
PHP AbuseIPDB API CLI
  • Overview
  • Documentation
  • Technical Details

1. Overview

1.1 Synopsis

abuseipdb -C <IP> [-d <DAYS>] [-v [-l <LIMIT>] ] [-o <FORMAT>] [-t <TIMEOUT>]
abuseipdb -K <NETWORK> [-d <DAYS>] [-l <LIMIT>] [-o <FORMAT>] [-t <TIMEOUT>]
abuseipdb -R <IP> -c <CATEGORIES> -m <MESSAGE> [-o <FORMAT>] [-t <TIMEOUT>]
abuseipdb -V <FILE> [-o <FORMAT>] [-t <TIMEOUT>]
abuseipdb -E <IP> [-o <FORMAT>] [-t <TIMEOUT>]
abuseipdb -B [-l <LIMIT>] [-s <SCORE>] [-o <FORMAT>] [-t <TIMEOUT>]
abuseipdb -L | -G  | -h | --version

1.2. Options

option Description
-h, --help Prints the current help.
-G, --config Prints the current config.
-L, --list Prints the list report categories.
-C, --check IP Performs a check request for the given IP address. A valid IPv4 or IPv6 address is required.
-d, --days DAYS For a check or check-block request, defines the maxAgeDays. Min is 1, max is 365, default is 30.
-R, --report IP Performs a report request for the given IP address. A valid IPv4 or IPv6 address is required.
-V, --bulk-report FILE Performs a bulk-report request sending a csv file. A valid file name or full path is required.
-E, --clear IP Remove own reports for the given IP address. A valid IPv4 or IPv6 address is required.
-K, --checkblock NETWORK Performs a check-block request for the given network. A valid subnet (v4 or v6) denoted with CIDR notation is required.
-c, --categories CATEGORIES For a report request, defines the report category(ies). Categories must be separate by a comma. Some catgeries cannot be used alone. A category can be represented by its shortname or by its id. Use abuseipdb -L to print the categories list.
-m, --message MESSAGE For a report request, defines the message to send with report. Message is required for all report requests.
-B, --blacklist Performs a blacklist request: get a list of reported IPs.
-l, --limit LIMIT For a blacklist request, defines the limit (default is 1000). For a check request with verbose flag, sets the max number of last reports displayed (default is 10). For a check-block request, sets the max number of IPs displayed (default is 0 mean no limit).
-o, --output FORMAT Defines the output format for API requests. Default is a colorized report, possible formats are json or plaintext. Plaintext option prints partial response (blacklist: IPs list, check or report: confidence score only, check-block: reported IP list with confidence score, bulk-report: number of saved reports, clear: number of deleted reports).
-s, --score SCORE For a blacklist request, sets the confidence score minimum. The confidence minimum must be between 25 and 100. This parameter is subscriber feature (not honored otherwise, allways 100).
-t, --timeout TIMEOUT Define the timeout in API request and overwrite the value defined in conf.ini or local.ini. Timeout is expressed in milliseconds.
-v, --verbose For a check request, display additional fields like the x last reports. Max number of last reports is defined in config. This increases request time and response size.
---version Prints the current version.

1.3. Report categories

For report and bulk-report, you must define one or more report category. Some categories, for example ssh (22), cannot be used alone.

For report command, a category can be represented by its shortname or by its id. When you use the bulk-report command, you must use the id.

Categories list must be separate by a comma. For report command, categories list may have no quote (18,22). When using bulkreport, categories list requires double quotes to include commas ("18,22").

You can print the categories list with:

abuseipdb -L
# or
abuseipdb --list

Here is the full Categories list:

ShortName Id Full name Can be alone?
dns-c 1 DNS Compromise true
dns-p 2 DNS Poisoning true
fraud-orders 3 Fraud Orders true
ddos 4 DDoS Attack true
ftp-bf 5 FTP Brute-Force true
pingdeath 6 Ping of Death true
phishing 7 Phishing true
fraudvoip 8 Fraud VoIP true
openproxy 9 Open Proxy true
webspam 10 Web Spam true
emailspam 11 Email Spam true
blogspam 12 Blog Spam true
vpnip 13 VPN IP false
scan 14 Port Scan true
hack 15 Hacking true
sql 16 SQL Injection true
spoof 17 Spoofing true
brute 18 Brute-Force true
badbot 19 Bad Web Bot true
explhost 20 Exploited Host true
webattack 21 Web App Attack true
ssh 22 SSH false
iot 23 IoT Targeted true

1.4. Output format

By default, all API commands (check, bulk-check, report, bulk-report, clean and blacklist) print a colorized report in terminal.

You can change the output format using the -o |--output FORMAT parameter. Format parameter accepts json or plaintext as value.

json format prints the full API response. If set, the --limit parameter in check or check-block command is ignored (apply only to number of reports/IPs displayed in terminal).

plaintext format prints partial response:

Command Plaintext output
blacklist IPs list (no confidence score), one IP per line
check confidence score
report confidence score
check-block reported IPs list with confidence score (space separated), one IP/score per line
bulk-report number of saved reports
clear number of deleted reports

2. How to

As said on abuseipdb, ip 127.0.0.1 is a private IP address you can use for check/report api testing. Make sure you do not blacklist an internal IP on your server, otherwise you won't have a good day!

2.1 Check a single IP address

You can check a single IP address using the --check | -C command.

2.1.1 Check Synopsis

abuseipdb -C <IP> [-d <DAYS>] [-v ] [-l <LIMIT>] [-t <TIMEOUT>]
abuseipdb --check <IP> [--days <DAYS>] [--verbose ] [--limit <LIMIT>] [--timemout <TIMEOUT>]

You must pass a valid IPv4 or IPv6 as argument.

Response does not include last reports and country name by default (number or reports and country code only). You can display last reports and country name with the -v | --verbose flag.

--verbose option increases request time and response size.

Displayed reports are currently limited to 10. You can change this value with the -l | --limit flag in your command.

By default, the last reports are checked on last 30 days, you can increase this number to 365 (min is 1) with the --days | -d parameter.

Like in any API request, you can overwrite the default timeout value (expressed in milliseconds) with the -t | --timeout option.

2.1.2 Check Usage

Check the ip 127.0.0.1 (default is on last 30 days):

abuseipdb -C 127.0.0.1 
# or
abuseipdb --check 127.0.0.1 

Check the ip 127.0.0.1 in last 365 days:

abuseipdb -C 127.0.0.1 -d 365
# or
abuseipdb --check 127.0.0.1 --days 365

Check the ip 127.0.0.1 and display additional infos with verbose flag and a timeout of 5 seconds:

abuseipdb -C 127.0.0.1 -v -t 5000
# or
abuseipdb --check 127.0.0.1 --verbose --timeout 5000

Check the ip 127.0.0.1, display additional infos with verbose flag and set the limit of last reports displayed to 20:

abuseipdb -C 127.0.0.1 -v -l 20
# or
abuseipdb --check 127.0.0.1 --verbose --limit 20

Here are sample outputs for this command (Click to see screenshots):

sample-check-internal-ip

sample-check-bad-ip

2.2 Check an IP block

You can check an IP block address using the --check-block | -K command.

2.2.1 Check-block Synopsis

abuseipdb -K <NETWORK> [-d <DAYS>] [-t <TIMEOUT>]
abuseipdb --check-block <NETWORK> [--days <DAYS>] [--timemout <TIMEOUT>]

The check-block command accepts a subnet (v4 or v6) denoted with CIDR notation as argument.

By default, the last reports are checked on last 30 days, you can increase this number to 365 (min is 1). Set the --days | -d flag in your command.

Like in any API request, you can overwrite the default timeout value (expressed in milliseconds) with the -t | --timeout option.

2.2.2 Check-block Limits

Due to the depth & breath of the these searches, the range of the parameters is capped by plan tier.

For most use cases, /24 is enough to an entire network. Many autonomous systems will sometimes have blocks of /20. Some of the largest autonomous systems will have blocks of /18 or /17.

Field Standard Basic Subscription Premium Subscription
network Up to /24 Up to /20 Up to /16
maxAgeInDays Up to 30 Up to 60 Up to 365

Exceeding a parameter limit will raise an error (402 Payment Required).

2.2.3 Check-block Usage

Check the block ip 127.0.0.1 (default is on last 30 days):

abuseipdb -K 127.0.0.1/24

Check the block ip 127.0.0.1 in last 15 days:

abuseipdb -K 127.0.0.1/24 -d 15
# or
abuseipdb --check-block 127.0.0.1/24 --days 15

Check the block ip 127.0.0.1 in last 15 days and display only 10 IPs:

abuseipdb -K 127.0.0.1/24 -d 15 -l 10
# or
abuseipdb --check-block 127.0.0.1/24 --days 15 --limit 10

Here are sample outputs for this command (Click to see screenshots):

sample-checkblock-internal-ip

sample-checkblock-bad-ip

2.3 Report a single IP address

You can report a specific IP address using the --report | -R command.

2.3.1 Report Synopsis

abuseipdb -R <IP> -c <CATEGORIES> -m <MESSAGE> [-t <TIMEOUT>]
abuseipdb --report <IP> --categories <CATEGORIES> --message <MESSAGE> [--timemout <TIMEOUT>]

The report command accepts a single IP address (v4 or v6) as parameter.

You must set :

  • valid report categories (see Report Categories)

  • a message. Message could be log lines or a custom message. By default, the report command checks for email address in message that are replaced by *. You can also configure a white list for IPs/domain names you want to remove too. (see Setup self IPs).

Like in any API request, you can overwrite the default timeout value (expressed in milliseconds) with the -t | --timeout option.

2.3.2 Reports Usage

Report the ip 127.0.0.1 for ssh and brute with message ssh brute force message using categories shortname:

# arguments order does not matter, these two lines do the same
abuseipdb -R 127.0.0.1  -c ssh,brute  -m "ssh brute force message"
abuseipdb  -m 'ssh brute force message' -c ssh,brute  -R 127.0.0.1

Report the ip 127.0.0.1 for ssh and brute with message ssh brute force message using categories id:

abuseipdb -R 127.0.0.1  -c 22,18  -m "ssh brute force message"

Here are sample outputs for this command (Click to see screenshots):

sample-report-internal-ip

2.4 Bulk report IP addresses

Instead of reporting IPs individually, you may compile a CSV of reports. This helps reduce bandwidth on both sides.

Note: The abuse confidence score of a IP reported this way is not immediately calculated.

You can report many IP by sending a CSV file using the --bulk-report | -V.

2.4.1 Bulk-Report Synopsis

abuseipdb -V <PATH> [-t <TIMEOUT>]
abuseipdb --bulk-report <PATH> [--timemout <TIMEOUT>]

This commands takes the file name/path as unique argument. The CSV file must be under 2 MB and less than or equal to 10,000 lines, including the headings.

Important: the CSV file is send AS IS, you need first to remove sensitive data in comments yourself.

Like in any API request, you can overwrite the default timeout value (expressed in milliseconds) with the -t | --timeout option.

2.4.2 CSV Format

Headings required, any order.

  • IP — A valid IPv4 or IPv6 IP address.
  • Categories — At least one category ID. Comma separated for multiple categories. See: Report Categories. Categories must be enclosed if there is more than one.
  • ReportDate — Date and time of the attack or earliest observance of attack. Any format that strtotime() can process is permitted. However, it's strongly recommend a timezoned format such ISO 8601 e.g. 2017-09-08T10:00:37-04:00. A time lacking a timezone is assumed to be in UTC.
  • Comment — A description of the attack. Truncated after 1,024 characters (bytes). The Comment must be enclosed in double quotes (") to include commas (,) and new line separators (\n, \r, \r\n). A blacklash () is needed to escape the enclosure. It does not escape itself.

Here is an example of valid content:

IP,Categories,ReportDate,Comment
89.205.125.160,"18,22",2018-12-18T10:00:37-04:00,"Failed password for invalid user odoo from 89.205.125.160 port 39121 ssh2"
123.183.209.136,"18,22",2018-12-18T11:25:11-04:00,"Did not receive identification string from 123.183.209.136 port 57192"
197.156.104.113,"14,15,18,11,10,21",2018-12-18T16:10:58+04:00,"[SMB remote code execution attempt: port tcp/445]
in blocklist.de:'listed [pop3]'
in SpamCop:'listed'
in sorbs:'listed [web], [spam]'
in Unsubscore:'listed'
*(RWIN=8192)(04:10)"

2.4.3 Bulk-Report Usage

Suppose a file named reports.csv, located in the current directory, with the following content:

IP,Categories,ReportDate,Comment
127.0.0.1,"18,22",2021-01-08T10:00:37-04:00,"test api"
127.0.0.1,"18,22",2021-01-08T10:00:37-04:00,"test api DUPLICATE IP"
127.0.0.2,"18,22",2021-01-08T10:00:37-04:00,"test api"
127.0.0.3,"18,22",2021-01-08T10:00:37-04:00,"test api"
127.0.0.WRONGIP,"18,22",2021-01-08T10:00:37-04:00,"test api with WRONG IP"
127.0.0.100,"777,999",2021-01-08T10:00:37-04:00,"test api with WRONG categorgies"

The file contains 3 error lines for testing (duplicate IP, wrong IP and wrong categories).

Send the csv file reports.csv:

abuseipdb -V "reports.csv"
# or
abuseipdb --bulk-report "reports.csv"

Here is a sample output for this command (Click to see screenshot):

sample-bulk-report

2.5 Remove own reports for an IP address

You can delete reports for a specific address from YOUR account using the --clear | -E command. It cannot delete another user's reports.

2.5.1 Clear Address Synopsis

abuseipdb -E <IP> [-o <FORMAT>] [-t <TIMEOUT>]
abuseipdb --clear <IP> [--output <FORMAT>] [--timemout <TIMEOUT>]

The clear command accepts a single IP address (v4 or v6) as parameter.

The only property it returns is the number of reports deleted from your account.

Like in any API request, you can overwrite the default timeout value (expressed in milliseconds) with the -t | --timeout option.

2.5.2 Clear Address Usage

Remove own reports for IP 127.0.0.1:

abuseipdb -E 127.0.0.1

Here are sample outputs for this command (Click to see screenshots):

sample-sample-clear-internal-ip

2.6 Download IP blacklist

You can download a blacklist using the --blacklist | -B command.

The blacklist is the culmination of all of the valiant reporting by AbuseIPDB users. It's a list of the most reported IP addresses.

2.6.1 Blacklist Synopsis

abuseipdb -B [-l <LIMIT>] [-s <SCORE>] [-o <FORMAT>] [-t <TIMEOUT>]
abuseipdb --blacklist [--limit <LIMIT>] [--score <SCORE>] [--output <FORMAT>] [--timemout <TIMEOUT>]

2.6.2 Blacklist Caching

The blacklist response for a given query is cached for 1, 6, or 24 hours depending on your plan (see table below).

Plan Hours Cached
Individual 24
Basic Subscription 6
Premium Subscription 1

2.6.3 Plaintext Blacklist

You can print the blacklist like any reports, or may want to receive the IP list in plain text like this:

5.188.10.179
185.222.209.14
95.70.0.46
191.96.249.183
115.238.245.8
122.226.181.164
122.226.181.167

If you prefer a simple newline-separated plaintext response, set the --output plaintext | -o plaintext flag in your command.

2.6.4 Blacklist Limit

To conserve bandwidth, the number of IP addresses included in the list is capped to 10,000. All users can set it between 1 and 10,000.

Subscribers, both basic and premium, can overcome this limit. If you are a subscriber and want to the full list, set the limit parameter to an absurd number like in the example (9,999,999). However, this large of a request may take a while, and firewall software such as csf may have trouble importing rules for over 10,000 IPs.

The default limit currently defined is 1,000, you can change limit in your command with --limit | -l flag.

2.6.5 Confidence Score

The default confidence score is 100, you can change mimimum condidence score in your command with --score | -s parameter. Score must be between 25 to 100. The score is a subscriber feature and is not honored otherwise.

The abuseConfidenceScore parameter is a subscriber feature. This is because custom blacklists take more juice to generate on-demand. Should your subscriber status lapse, an error response will not be thrown. Rather, the response will degrade gracefully to the simple blacklist. This works nicely with existing firewall software.

2.6.6 Blacklist Usage

  • Get a blacklist of 10 items:

    abuseipdb -B -l 10
    #or
    abuseipdb --blacklist --limit 10 
    

    Here are sample outputs for this command (Click to see screenshots):

    sample-blacklist

  • Get a blacklist of 10 items in plain text:

    abuseipdb -B -l 10 -o plaintext
    #or
    abuseipdb --blacklist --limit 10 --output plaintext
    

    Here are sample outputs for this command (Click to see screenshots):

    sample-blacklist-plaintext

  • Get a blacklist of 200 items with minimum confidence score of 75 :

    abuseipdb -B -l 200 -s 75
    #or
    abuseipdb --blacklist --limit 10 --score 75
    
  • Get a blacklist of 10000 items in plain text and save it to a file named list.txt:

    abuseipdb -B -o plaintext -l 10000 > list.txt
    # or
    abuseipdb --blacklist --output plaintext --limit 10000 > list.txt
    
CONTENT
  1. Overview
    1. Synopsis
    2. Options
    3. Report categories
    4. Output format
  2. How to
    1. Check a single IP address
      1. Check Synopsis
      2. Check Usage
    2. Check an IP block
      1. Check-block Synopsis
      2. Check-block Limits
      3. Check-block Usage
    3. Report a single IP address
      1. Report Synopsis
      2. Reports Usage
    4. Bulk report IP addresses
      1. Bulk-Report Synopsis
      2. CSV Format
      3. Bulk-Report Usage
    5. Clear reports for an IP address
      1. Clear Address Synopsis
      2. Clear Address Usage
    6. Download IP blacklist
      1. Blacklist Synopsis
      2. Blacklist Caching
      3. Plaintext Blacklist
      4. Blacklist Limit
      5. Confidence Score
      6. Blacklist Usage
SEE ALSO
Overview Documentation Technical Details 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