WebService::AbuseIPDB - Client for the API (version 2) of AbuseIPDB
use WebService::AbuseIPDB; my $ipdb = WebService::AbuseIPDB->new (key => 'abc123...'); my $res = $ipdb->check (ip => '127.0.0.2'); die unless defined $res; printf "There is a %i%% chance this address is up to no good.\n", $res->score;
https://www.abuseipdb.com/|AbuseIPDB maintains a database of reports of bad actors on the net. Users may interface with the database through a web browser using forms on their site. An alternative is to use their API. Version 1 of this API is to be retired in 2020. This module serves as a client for Version 2 of the API.
my $ipdb = WebService::AbuseIPDB->new (%opts);
The constructor takes a hash of configuration details.
The API version - always set this as "2" to avoid potential problems with mismatched versions.
Your key for the API as a scalar string. You must obtain one before using this module.
The timeout in seconds to wait for the server to respond. Defaults to 20.
The number of times to retry on timeout or network error. Defaults to 0 (ie. no retries).
my $res = $ipdb->check (ip => '127.0.0.2', max_age => 90);
This uses the check endpoint and returns a WebService::AbuseIPDB::CheckResponse object to access the data held in the database for the provided IP address. The argument is a hash with these keys:
check
The IP address to be checked. This item is mandatory.
The age in integral days of the oldest report(s) to include. If omitted the server default is used (currently 30).
If set to any true value, the data from each report itself is also returned. Not yet impelemented.
my $res = $ipdb->report ( ip => '127.0.0.2', categories => [3, 4], comment => 'This address is the worst' );
This uses the report endpoint to report an abusive address. It takes a single hash as the only argument with these elements:
report
The IP address to report. Must be a single, valid IPv4 or IPv6 address. This element is mandatory.
An arrayref of categories as either scalar IDs or scalar names or WebService::AbuseIPDB::Category objects. This element is mandatory.
A scalar string with details of the offence. This is optional but recommended in most cases. It must be no more than 1024 characters. and should be decoded.
The method will return undef on client error and a WebService::AbuseIPDB::ReportResponse object otherwise.
my $res = $ipdb->blacklist ( min_abuse => 90, limit => 1000 ); print "As at " . $res->as_at . "\n"; for my $bad ($res->list) { printf "Address %s has score %i%%\n", $bad->ip, $bad->score; }
This uses the blacklist endpoint to retrieve a list of abusive addresses. It takes a single hash as the only argument with these elements:
blacklist
Only include addresses with an abuse confidence score of this level or higher. Minimum is 25, maximum is 100 and default is 75.
An integer giving the maximum quantity of addresses to return. Minimum is 1, maximum is 10,000 for non-subscribers and default is 1000.
The method will return undef on client error and a WebService::AbuseIPDB::BlacklistResponse object otherwise.
This is currently alpha software. Be aware that both the internals and the interface are liable to change.
Implement the verbose option on the check method.
verbose
Add the other API endpoints: check-block and bulk-report. Allow for fast blacklist-as-string response too.
More validation/sanitation of inputs.
Consider using objects for errors instead of AoH.
SendMail::AbuseIPDB is a client for v1 of the API.
Full documentation for the API is at https://docs.abuseipdb.com/.
Pete Houston, <cpan at openstrike.co.uk>
<cpan at openstrike.co.uk>
Please report any bugs or feature requests to bug-webservice-abuseipdb at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WebService-AbuseIPDB. See the file CONTRIBUTING.md for further details.
bug-webservice-abuseipdb at rt.cpan.org
Thanks to AbuseIPDB for making the database publicly available via this API.
Copyright © 2020 Pete Houston.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 dated June, 1991 or at your option any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
A copy of the GNU General Public License is available in the source tree; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
To install WebService::AbuseIPDB, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WebService::AbuseIPDB
CPAN shell
perl -MCPAN -e shell install WebService::AbuseIPDB
For more information on module installation, please visit the detailed CPAN module installation guide.