NAME

Net::Google::SafeBrowsing4::Storage - Base class for storing the Google Safe Browsing v4 database

SYNOPSIS

        package Net::Google::SafeBrowsing4::Storage::File;

        use base qw(Net::Google::SafeBrowsing4::Storage);

DESCRIPTION

This is the base class for implementing a storage mechanism for the Google Safe Browsing v4 database. See Net::Google::SafeBrowsing4::Storage::File for an example of implementation.

This module cannot be used on its own as it does not actually store anything. All public methods should redefined.

CONSTRUCTOR

new()

        Create a Net::Google::SafeBrowsing4::Storage object

        my $storage => Net::Google::SafeBrowsing4::Storage->new(
                # Constructor parameters vary based on the implementation
                ...
        );

PUBLIC FUNCTIONS

save()

Add chunk information to the local database

  $storage->save(add => [...], remove => [...], state => '...', list => { threatType => ..., threatEntryType => ..., platformType => ... });

Return the new list of local hashes.

Arguments

override

Optional. override the local list of hashes. 0 by default (do not override)

add

Optional. List of hashes to add.

remove

Optional. List of hash indexes to remove.

state

Optional. New list state.

list

Required. Google Safe Browsing list.

reset()

Remove all local data.

        $storage->reset(list => { threatType => ..., threatEntryType => ..., platformType => ... });

Arguments

list

Required. Google Safe Browsing list.

No return value

next_update()

Ge the timestamp when the local database update is allowed.

        my $next = $storage->next_update();

No arguments

get_state()

Return the current state of the list.

        my $state = $storage->get_state(list => { threatType => ..., threatEntryType => ..., platformType => ... });

Arguments

list

Required. Google Safe Browsing list.

get_prefixes()

Return the list of prefxies that match a full hash for a given list.

        my @prefixes = $storage->get_prefixes(hashes => [...], list => { threatType => ..., threatEntryType => ..., platformType => ... });

Arguments

list

Required. Google Safe Browsing list.

hashes

Required. List of full hashes.

updated()

Save information about a successful database update

        $storage->updated('time' => time(), next => time() + 1800);

Arguments

time

Required. Time of the update.

next

Required. Time of the next update allowed.

No return value

get_full_hashes()

Return a list of full hashes

        $storage->get_full_hashes(hash => AAAAAAAA..., lists => [{ threatType => '...', threatEntryType => '...', platformType => '...' }]);

Arguments

hash

Required. 32-bit hash

lists

Required. Google Safe Browsing lists

Return value

Array of full hashes:

    ({ hash => HEX, type => 0 }, { hash => HEX, type => 1 }, { hash => HEX, type => 0 })

update_error()

Save information about a failed database update

        $storage->update_error('time' => time(), wait => 60, errors => 1);

Arguments

time

Required. Time of the update.

wait

Required. Number of seconds to wait before doing the next update.

errors

Required. Number of errors.

No return value

last_update()

Return information about the last database update

        my $info = $storage->last_update();

No arguments

Return value

Hash reference

        {
                time    => time(),
                errors  => 0
        }

add_full_hashes()

Add full hashes to the local database

        $storage->add_full_hashes(timestamp => time(), full_hashes => [{hash => HEX, list => { }, cache => "300s"}]);

Arguments

timestamp

Required. Time when the full hash was retrieved.

full_hashes

Required. Array of full hashes. Each element is an hash reference in the following format:

        {
                hash            => HEX,
                list            => { }',
                cache => "300s"
        }

No return value

full_hash_error()

Save information about failed attempt to retrieve a full hash

        $storage->full_hash_error(timestamp => time(), prefix => HEX);

Arguments

timestamp

Required. Time when the Google returned an error.

prefix

Required. Host prefix.

No return value

full_hash_ok()

Save information about a successful attempt to retrieve a full hash

        $storage->full_hash_ok(timestamp => time(), prefix => HEX);

Arguments

timestamp

Required. Time when the Google returned an error.

prefix

Required. Host prefix.

No return value

get_full_hash_error()

Get information about an unsuccessful attempt to retrieve a full hash

        my $info = $storage->get_full_hash_error(prefix => HEX);

Arguments

prefix

Required. Host prefix.

Return value

undef if there was no error

Hash reference in the following format if there was an error:

        {
                timestamp       => time(),
                errors          => 3
        }

get_lists()

Gets all threat list names from Google Safe Browsing stored.

        my $lists = $storage->get_lists();

Returns an array reference of all the lists:

        [
                {
                        'threatEntryType' => 'URL',
                        'threatType' => 'MALWARE',
                        'platformType' => 'ANY_PLATFORM'
                },
                {
                        'threatEntryType' => 'URL',
                        'threatType' => 'MALWARE',
                        'platformType' => 'WINDOWS'
                },
                ...
        ]

        or C<undef> on error.

save_lists()

Store the threat list names from Google Safe Browsing.

        my $lists = $storage->save_lists(
                        [
                        {
                                'threatEntryType' => 'URL',
                                'threatType' => 'MALWARE',
                                'platformType' => 'ANY_PLATFORM'
                        },
                        {
                                'threatEntryType' => 'URL',
                                'threatType' => 'MALWARE',
                                'platformType' => 'WINDOWS'
                        },
                        ...
                ]
        );

        or C<undef> on error.

SEE ALSO

See Net::Google::SafeBrowsing4 for handling Google Safe Browsing v4.

See Net::Google::SafeBrowsing4::Storage::File for an example of storing and managing the Google Safe Browsing database.

Google Safe Browsing v4 API: https://developers.google.com/safe-browsing/v4/

AUTHOR

Julien Sobrier, <julien@sobrier.net>

COPYRIGHT AND LICENSE

Copyright (C) 2016 by Julien Sobrier

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

cpanm Net::Google::SafeBrowsing4

perl -MCPAN -e shell
install Net::Google::SafeBrowsing4