File Coverage

blib/lib/Net/Google/SafeBrowsing4/Storage.pm
Criterion Covered Total %
statement 22 22 100.0
branch n/a
condition n/a
subroutine 18 18 100.0
pod 16 16 100.0
total 56 56 100.0


line stmt bran cond sub pod time code
1             package Net::Google::SafeBrowsing4::Storage;
2              
3             # ABSTRACT: Base class for storing the Google Safe Browsing v4 database
4              
5 5     5   71257 use strict;
  5         22  
  5         143  
6 5     5   26 use warnings;
  5         11  
  5         1511  
7              
8             our $VERSION = '0.3';
9              
10             =head1 NAME
11              
12             Net::Google::SafeBrowsing4::Storage - Base class for storing the Google Safe Browsing v4 database
13              
14             =head1 SYNOPSIS
15              
16             package Net::Google::SafeBrowsing4::Storage::File;
17              
18             use base qw(Net::Google::SafeBrowsing4::Storage);
19              
20             =head1 DESCRIPTION
21              
22             This is the base class for implementing a storage mechanism for the Google Safe Browsing v4 database. See L for an example of implementation.
23              
24             This module cannot be used on its own as it does not actually store anything. All public methods should redefined.
25              
26             =cut
27              
28              
29             =head1 CONSTRUCTOR
30              
31             =head2 new()
32              
33             Create a Net::Google::SafeBrowsing4::Storage object
34              
35             my $storage => Net::Google::SafeBrowsing4::Storage->new(
36             # Constructor parameters vary based on the implementation
37             ...
38             );
39              
40             =cut
41              
42             sub new {
43             ...
44 1     1 1 1461 }
45              
46             =head1 PUBLIC FUNCTIONS
47              
48             =over 4
49              
50             =back
51              
52             =head2 save()
53              
54             Add chunk information to the local database
55              
56             $storage->save(add => [...], remove => [...], state => '...', list => { threatType => ..., threatEntryType => ..., platformType => ... });
57              
58             Return the new list of local hashes.
59              
60              
61             Arguments
62              
63             =over 4
64              
65             =item override
66              
67             Optional. override the local list of hashes. 0 by default (do not override)
68              
69             =item add
70              
71             Optional. List of hashes to add.
72              
73             =item remove
74              
75             Optional. List of hash indexes to remove.
76              
77             =item state
78              
79             Optional. New list state.
80              
81             =item list
82              
83             Required. Google Safe Browsing list.
84              
85             =back
86              
87             =cut
88              
89             sub save {
90             ...
91 1     1 1 362 }
92              
93              
94             =head2 reset()
95              
96             Remove all local data.
97              
98             $storage->reset(list => { threatType => ..., threatEntryType => ..., platformType => ... });
99              
100              
101             Arguments
102              
103             =over 4
104              
105             =item list
106              
107             Required. Google Safe Browsing list.
108              
109             =back
110              
111             No return value
112              
113             =cut
114              
115             sub reset {
116             ...
117 1     1 1 358 }
118              
119              
120             =head2 next_update()
121              
122             Ge the timestamp when the local database update is allowed.
123              
124             my $next = $storage->next_update();
125              
126              
127             No arguments
128              
129             =cut
130              
131             sub next_update {
132             ...
133 1     1 1 375 }
134              
135              
136             =head2 get_state()
137              
138             Return the current state of the list.
139              
140             my $state = $storage->get_state(list => { threatType => ..., threatEntryType => ..., platformType => ... });
141              
142              
143             Arguments
144              
145             =over 4
146              
147             =item list
148              
149             Required. Google Safe Browsing list.
150              
151             =back
152              
153              
154             =cut
155              
156             sub get_state {
157             ...
158 1     1 1 344 }
159              
160              
161              
162             =head2 get_prefixes()
163              
164             Return the list of prefxies that match a full hash for a given list.
165              
166             my @prefixes = $storage->get_prefixes(hashes => [...], list => { threatType => ..., threatEntryType => ..., platformType => ... });
167              
168              
169             Arguments
170              
171             =over 4
172              
173             =item list
174              
175             Required. Google Safe Browsing list.
176              
177             =back
178              
179             =item hashes
180              
181             Required. List of full hashes.
182              
183             =back
184              
185              
186             =cut
187              
188             sub get_prefixes {
189             ...
190 1     1 1 335 }
191              
192             =head2 updated()
193              
194             Save information about a successful database update
195              
196             $storage->updated('time' => time(), next => time() + 1800);
197              
198              
199             Arguments
200              
201             =over 4
202              
203             =item time
204              
205             Required. Time of the update.
206              
207             =item next
208              
209             Required. Time of the next update allowed.
210              
211             =back
212              
213              
214             No return value
215              
216             =cut
217              
218             sub updated {
219             ...
220 1     1 1 333 }
221              
222              
223             =head2 get_full_hashes()
224              
225             Return a list of full hashes
226              
227             $storage->get_full_hashes(hash => AAAAAAAA..., lists => [{ threatType => '...', threatEntryType => '...', platformType => '...' }]);
228              
229              
230             Arguments
231              
232             =over 4
233              
234             =item hash
235              
236             Required. 32-bit hash
237              
238              
239             =item lists
240              
241             Required. Google Safe Browsing lists
242              
243             =back
244              
245             Return value
246              
247             =over 4
248              
249             Array of full hashes:
250              
251             ({ hash => HEX, type => 0 }, { hash => HEX, type => 1 }, { hash => HEX, type => 0 })
252              
253             =back
254              
255              
256             =cut
257              
258             sub get_full_hashes {
259             ...
260 1     1 1 328 }
261              
262              
263             =head2 update_error()
264              
265             Save information about a failed database update
266              
267             $storage->update_error('time' => time(), wait => 60, errors => 1);
268              
269              
270             Arguments
271              
272             =over 4
273              
274             =item time
275              
276             Required. Time of the update.
277              
278             =item wait
279              
280             Required. Number of seconds to wait before doing the next update.
281              
282             =item errors
283              
284             Required. Number of errors.
285              
286             =back
287              
288              
289             No return value
290              
291             =cut
292              
293             sub update_error {
294             ...
295 1     1 1 328 }
296              
297             =head2 last_update()
298              
299             Return information about the last database update
300              
301             my $info = $storage->last_update();
302              
303              
304             No arguments
305              
306              
307             Return value
308              
309             =over 4
310              
311             Hash reference
312              
313             {
314             time => time(),
315             errors => 0
316             }
317              
318             =back
319              
320             =cut
321              
322             sub last_update {
323             ...
324 1     1 1 346 }
325              
326             =head2 add_full_hashes()
327              
328             Add full hashes to the local database
329              
330             $storage->add_full_hashes(timestamp => time(), full_hashes => [{hash => HEX, list => { }, cache => "300s"}]);
331              
332              
333             Arguments
334              
335             =over 4
336              
337             =item timestamp
338              
339             Required. Time when the full hash was retrieved.
340              
341             =item full_hashes
342              
343             Required. Array of full hashes. Each element is an hash reference in the following format:
344              
345             {
346             hash => HEX,
347             list => { }',
348             cache => "300s"
349             }
350              
351             =back
352              
353              
354             No return value
355              
356              
357             =cut
358              
359             sub add_full_hashes {
360             ...
361 1     1 1 329 }
362              
363             =head2 full_hash_error()
364              
365             Save information about failed attempt to retrieve a full hash
366              
367             $storage->full_hash_error(timestamp => time(), prefix => HEX);
368              
369              
370             Arguments
371              
372             =over 4
373              
374             =item timestamp
375              
376             Required. Time when the Google returned an error.
377              
378             =item prefix
379              
380             Required. Host prefix.
381              
382             =back
383              
384              
385             No return value
386              
387              
388             =cut
389              
390             sub full_hash_error {
391             ...
392 1     1 1 326 }
393              
394             =head2 full_hash_ok()
395              
396             Save information about a successful attempt to retrieve a full hash
397              
398             $storage->full_hash_ok(timestamp => time(), prefix => HEX);
399              
400              
401             Arguments
402              
403             =over 4
404              
405             =item timestamp
406              
407             Required. Time when the Google returned an error.
408              
409             =item prefix
410              
411             Required. Host prefix.
412              
413             =back
414              
415              
416             No return value
417              
418              
419             =cut
420              
421             sub full_hash_ok {
422             ...
423 1     1 1 325 }
424              
425             =head2 get_full_hash_error()
426              
427             Get information about an unsuccessful attempt to retrieve a full hash
428              
429             my $info = $storage->get_full_hash_error(prefix => HEX);
430              
431              
432             Arguments
433              
434             =over 4
435              
436             =item prefix
437              
438             Required. Host prefix.
439              
440             =back
441              
442              
443             Return value
444              
445             =over 4
446              
447             undef if there was no error
448              
449             Hash reference in the following format if there was an error:
450              
451             {
452             timestamp => time(),
453             errors => 3
454             }
455              
456             =back
457              
458              
459             =cut
460              
461             sub get_full_hash_error {
462             ...
463 1     1 1 325 }
464              
465             =head2 get_lists()
466              
467             Gets all threat list names from Google Safe Browsing stored.
468              
469             my $lists = $storage->get_lists();
470              
471             Returns an array reference of all the lists:
472              
473             [
474             {
475             'threatEntryType' => 'URL',
476             'threatType' => 'MALWARE',
477             'platformType' => 'ANY_PLATFORM'
478             },
479             {
480             'threatEntryType' => 'URL',
481             'threatType' => 'MALWARE',
482             'platformType' => 'WINDOWS'
483             },
484             ...
485             ]
486              
487             or C on error.
488              
489             =cut
490              
491              
492             sub get_lists {
493             ...
494 1     1 1 344 }
495              
496              
497             =head2 save_lists()
498              
499             Store the threat list names from Google Safe Browsing.
500              
501             my $lists = $storage->save_lists(
502             [
503             {
504             'threatEntryType' => 'URL',
505             'threatType' => 'MALWARE',
506             'platformType' => 'ANY_PLATFORM'
507             },
508             {
509             'threatEntryType' => 'URL',
510             'threatType' => 'MALWARE',
511             'platformType' => 'WINDOWS'
512             },
513             ...
514             ]
515             );
516              
517             or C on error.
518              
519             =cut
520              
521              
522             sub save_lists {
523             ...
524 1     1 1 355 }
525              
526              
527              
528             =head1 SEE ALSO
529              
530             See L for handling Google Safe Browsing v4.
531              
532             See L for an example of storing and managing the Google Safe Browsing database.
533              
534             Google Safe Browsing v4 API: L
535              
536             =head1 AUTHOR
537              
538             Julien Sobrier, Ejulien@sobrier.netE
539              
540             =head1 COPYRIGHT AND LICENSE
541              
542             Copyright (C) 2016 by Julien Sobrier
543              
544             This library is free software; you can redistribute it and/or modify
545             it under the same terms as Perl itself, either Perl version 5.8.8 or,
546             at your option, any later version of Perl 5 you may have available.
547              
548              
549             =cut
550              
551             1;