NAME

Sendmail::AbuseIPDB - API access for IP address abuse database

SYNOPSIS

use Sendmail::AbuseIPDB;

# CURRENT: For v2 API like this:
my $db = Sendmail::AbuseIPDB->new( v2Key => '** your v2 API key here **' );

# OBSOLETE: For v1 API like this:
my $db = Sendmail::AbuseIPDB->new( Key => '** your API key here **' );

my $ip = '190.180.154.131';                       # IP of sender
my $result = $db->get( $ip );

if( defined( $result->{data} ))
{
    print "Abuse confidence of $ip is $result->{data}{abuseConfidenceScore}\n";
}
else
{
    warn( "Failed to get result for $ip" );
}

DESCRIPTION

Convenient toolbox for Version-2 API access to https://www.abuseipdb.com/

Potentially for other sites with compatible API if you want to change the BaseURL.

METHODS

new( v2Key => $key, ... )

Additional parameters are: BaseURL, Days, Debug

Old parameter was Key which is for v1 API calls, supported for compatibility,
but most of the old v1 API has been shut down by the provider.

get( $ip )

Do a query to check an IP address. Returns single reference, looking similar to this:

   {
       'data' => {
           'isp' => 'Cicomsa S.A.',
           'lastReportedAt' => '2021-06-25T04:24:08+00:00',
           'domain' => 'mshquil.com.ar',
           'numDistinctUsers' => 8,
           'ipVersion' => 4,
           'abuseConfidenceScore' => 67,
           'isWhitelisted' => 0,
           'hostnames' => [],
           'countryCode' => 'AR',
           'totalReports' => 50,
           'usageType' => 'Fixed Line ISP',
           'isPublic' => 1,
           'ipAddress' => '190.180.154.131'
        }
   }

report( $ip, $comment, @category_list )

Report an abusive IP address back to the database.
The comment can be "" empty string or any other brief comment to explain why
you believe this IP has done something wrong.
One or more categories must be included, these can be numbers or printable
string categories. e.g. :

$db->report( '142.93.218.225', 'Very annoying IP address', 'Brute-Force', 'Port Scan' );

Warning copied from provider documentation.

STRIP ANY PERSONALLY IDENTIFIABLE INFORMATION (PPI);
WE ARE NOT RESPONSIBLE FOR PPI YOU REVEAL.

blacklist( $confidence )

Get a list of IP addresses where $confidence is the minimum confidence score
(percentage) that this IP address is likely to be abusive.
Depending on your account the server might force your $confidence value upwards
(in the case of free accounts only 100% confidence results are provided).

Result format is like this:

    {
        'data' => [
            {
                'ipAddress' => '60.29.254.252',
                'abuseConfidenceScore' => '100',
                'totalReports' => 4723
            },
            {
                'ipAddress' => '118.24.214.107',
                'abuseConfidenceScore' => '100',
                'totalReports' => 4712
            },
            # ... many others ...
        ],
        'meta' => {
            'generatedAt' => '2019-01-01T01:01:01+00:00'
        }
    }

It requires apallingly bad behaviour to achieve 100% confidence of abuse,
so the worst offender IP addresses should be filtered without remorse.
When using the "ipset" Linux kernel feature, set a reasonable timeout so that
old IP addresses will automatically be removed from the list once they are
no longer abusive. Hopefully most compromised systems do get cleaned up.

SEE ALSO

https://docs.abuseipdb.com/#check-endpoint

https://www.abuseipdb.com/categories

Sendmail::PMilter

Example program abuseipdb_milter.pl for a simple way to block suspicious senders.

Example program abuseipdb_blacklist_ipset.pl to feed into "ipset restore".

AUTHOR

<ttndy@cpan.org>

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.10.1 or,
at your option, any later version of Perl 5 you may have available.