NAME

WebService::AbuseIPDB - Client for the API (version 2) of AbuseIPDB

SYNOPSIS

    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;

DESCRIPTION

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.

SUBROUTINES/METHODS

new

    my $ipdb = WebService::AbuseIPDB->new (%opts);

The constructor takes a hash of configuration details.

ver

The API version - always set this as "2" to avoid potential problems with mismatched versions.

key

Your key for the API as a scalar string. You must obtain one before using this module.

timeout

The timeout in seconds to wait for the server to respond. Defaults to 20.

retry

The number of times to retry on timeout or network error. Defaults to 0 (ie. no retries).

check

    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:

ip

The IP address to be checked. This item is mandatory.

max_age

The age in integral days of the oldest report(s) to include. If omitted the server default is used (currently 30).

verbose

If set to any true value, the data from each report itself is also returned. Not yet impelemented.

report

    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:

ip

The IP address to report. Must be a single, valid IPv4 or IPv6 address. This element is mandatory.

categories

An arrayref of categories as either scalar IDs or scalar names or WebService::AbuseIPDB::Category objects. This element is mandatory.

comment

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.

blacklist

    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:

min_abuse

Only include addresses with an abuse confidence score of this level or higher. Minimum is 25, maximum is 100 and default is 75.

limit

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.

STABILITY

This is currently alpha software. Be aware that both the internals and the interface are liable to change.

TODO

Implement the verbose option on the check method.

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.

SEE ALSO

SendMail::AbuseIPDB is a client for v1 of the API.

Full documentation for the API is at https://docs.abuseipdb.com/.

AUTHOR

Pete Houston, <cpan at openstrike.co.uk>

BUGS

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.

ACKNOWLEDGEMENTS

Thanks to AbuseIPDB for making the database publicly available via this API.

LICENCE AND COPYRIGHT

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

cpanm WebService::AbuseIPDB

perl -MCPAN -e shell
install WebService::AbuseIPDB