Net::G...wsing2(3pm)

📦 version 1.07, in ubuntu jammy

💖 Net::Google::SafeBrowsing2 — bestie edition 💖

okay so the manual page is Net::Google::SafeBrowsing2(3pm), from the User Contributed Perl Documentation, and it's literally a Perl extension for the Google Safe Browsing v2 API. also quick heads up: Google Safe Browsing v1 has been deprecated by Google, so don't come for me about v1, she's gone 💀

✨ NAME ✨

Net::Google::SafeBrowsing2 — a Perl extension for the Google Safe Browsing v2 API. and just so we're clear: Google Safe Browsing v1 has been deprecated by Google. rest in peace girl 🪦

🦋 SYNOPSIS 🦋

here's the whole vibe in one code block, copy it, love it, run it:

use Net::Google::SafeBrowsing2;
use Net::Google::SafeBrowsing2::Sqlite;

my $storage = Net::Google::SafeBrowsing2::Sqlite->new(file => 'google-v2.db');
my $gsb = Net::Google::SafeBrowsing2->new(
      key     => "my key",
      storage => $storage,
);

$gsb->update();
my $match = $gsb->lookup(url => 'http://www.gumblar.cn/');

if ($match eq MALWARE) {
      print "http://www.gumblar.cn/ is flagged as a dangerous site\n";
}

$storage->close();

like… she's giving "set up a storage backend, make the object, update, look up, close." iconic behavior honestly 👑

🌸 DESCRIPTION 🌸

okay so Net::Google::SafeBrowsing2 implements the Google Safe Browsing v2 API. periodt.

The library passes most of the unit tests listed in the API documentation. no cap, not all of them — if you wanna know about the tests that don't pass, go read the documentation at <http://code.google.com/apis/safebrowsing/developers_guide_v2.html> for more deets. 🔍

The Google Safe Browsing database must be stored and managed locally, bestie. like, you're the one hosting this. Net::Google::SafeBrowsing2::Sqlite uses Sqlite as the storage back-end, and Net::Google::SafeBrowsing2::MySQL uses MySQL. and the slay part? other storage mechanisms (databases, memory, etc.) can be added and used transparently with this module. plug and play, we love to see it 🫶

you might also wanna look at "Google Safe Browsing v2: Implementation Notes" at <http://www.zscaler.com/research/Google%20Safe%20Browsing%20v2%20API.pdf> — it's a collection of notes and real-world numbers about the API. it's for people who wanna learn more about the API, whether you're just a user or you're out here making your own implementation. main character energy for the implementers, fr fr ✨

the source code is available on github at <https://github.com/juliensobrier/Net-Google-SafeBrowsing2>. go star it, it's free 💅

oh and — if you do not need to inspect more than 10,000 URLs a day, you can use Net::Google::SafeBrowsing2::Lookup with the Google Safe Browsing v2 Lookup API, which does not require you to store and maintain a local database. no db, no problem 🎀

IMPORTANT: if you start with an empty database, you will need to perform several updates to retrieve all the Google Safe Browsing information. this may require up to 24 hours. and no, that's not this module being slow — it's literally a limitation of the Google API, not of this module. see "Google Safe Browsing v2: Implementation Notes" at <http://www.zscaler.com/research/Google%20Safe%20Browsing%20v2%20API.pdf>. 😭 patience is a virtue bestie

🎀 CONSTANTS 🎀

Several constants are exported by this module. here's the whole roster:

DATABASE_RESET — Google requested to reset (empty) the local database. like, wipe her. 🧹
MAC_ERROR — the replies from Google could not be validated with the MAC keys. 😬
MAC_KEY_ERROR — the request for the MAC keys failed. the keys said no 💀
INTERNAL_ERROR — an internal error occurred.
SERVER_ERROR — the server sent an error back to the client. rude.
NO_UPDATE — no update was performed, probably because it is too early to make a new request to Google Safe Browsing. she's resting 😴
NO_DATA — no data was sent back by Google to the client, probably because the database is up to date. nothing to see here, we're current 💅
SUCCESSFUL — the operation was successful. ate. 🔥
MALWARE — name of the Malware list in Google Safe Browsing (shortcut to 'goog-malware-shavar')
PHISHING — name of the Phishing list in Google Safe Browsing (shortcut to 'googpub-phish-shavar')

👑 CONSTRUCTOR 👑

new()

Create a Net::Google::SafeBrowsing2 object. look at her being born 🦋

my $gsb = Net::Google::SafeBrowsing2->new(
      key     => "my key",
      storage => Net::Google::SafeBrowsing2::Sqlite->new(file => 'google-v2.db'),
      debug   => 0,
      mac             => 0,
      list    => MALWARE,
);

Arguments

key — Required. your Google Safe Browsing API key. no key, no entry 🚪
storage — Required. object which handles the storage for the Google Safe Browsing database. see Net::Google::SafeBrowsing2::Storage for more details.
list — Optional. the Google Safe Browsing list to handle. by default, handles both MALWARE and PHISHING. overachiever behavior, love that 💅
mac — Optional. set to 1 to enable Message Authentication Code (MAC). 0 (disabled) by default.
debug — Optional. set to 1 to enable debugging. 0 (disabled) by default.

heads up bestie: the debug output maybe quite large and can slow down significantly the update and lookup functions. like she'll be talking A LOT 😭

errors — Optional. set to 1 to show errors to STDOUT. 0 (disabled by default).
version — Optional. Google Safe Browsing version. 2.2 by default.

🔥 PUBLIC FUNCTIONS 🔥

update()

Perform a database update. she's going to Google to get the tea ☕

$gsb->update();

Return the status of the update (see the list of constants above): INTERNAL_ERROR, SERVER_ERROR, NO_UPDATE, NO_DATA or SUCCESSFUL.

This function can handle two lists at the same time. if one of the lists should not be updated, it will automatically skip it and update the other one. and plot twist: it is faster to update two lists at once rather than doing them one by one. multitasking queen 🫶

NOTE: if you start with an empty database, you will need to perform several updates to retrieve all the Google Safe Browsing information. this may require up to 24 hours. this is a limitation of the Google API, not of this module. see "Google Safe Browsing v2: Implementation Notes" at <http://www.zscaler.com/research/Google%20Safe%20Browsing%20v2%20API.pdf>. yeah bestie, it's a whole overnight thing 😴

Arguments

list — Optional. update a specific list. use the list(s) from new() by default.
mac — Optional. set to 1 to enable Message Authentication Code (MAC). use the value from new() by default.
force — Optional. force the update (1). disabled by default (0).

be careful if you set this option to 1 as too frequent updates might result in the blacklisting of your API key. do NOT spam her, i'm so serious 💀

import_chunks()

Import add and sub chunks from a file.

my $result = $gsb->import_chunks(list => MALWARE, file => 'malware.dat');

Return the status of the import: INTERNAL_ERROR or SUCCESSFUL.

This function should be used to initialize an empty back-end storage. she's your starter pack ✨

Arguments

list — Required. Google list to use.
file — Required. file that contains the list of chunks. this file can be created with the "export" function inherited from "Net::Google::SafeBrowsing2::DBI".

lookup()

Lookup a URL against the Google Safe Browsing database. vibe check on the URL 💅

my $match = $gsb->lookup(url => 'http://www.gumblar.cn');

Returns the name of the list if there is any match, returns an empty string otherwise.

Arguments

list — Optional. lookup against a specific list. use the list(s) from new() by default.
url — Required. URL to lookup.

get_lists()

Returns the name of all the Google Safe Browsing lists. the full guest list 📝

my $@lists = $gsb->get_lists();

NOTE: this function is useless in practice because Google includes some lists which cannot be used by the Google Safe Browsing API, like lists used by the Google toolbar. so like… she's there, but she's not there 😭

last_error()

Get/Set the last error message.

print "Last error: ", $gsb->last_error(), "\n";
$gsb->last_error(''); # Reset last error

NOTE: the last error message might not come from the last call. returns an empty string if no errors. so don't assume she's talking about what just happened, she's got memory 🫠

🙈 PRIVATE FUNCTIONS 🙈

These functions are not intended to be used externally. like, they're backstage. do not come backstage bestie 🙅‍♀️

lookup_suffix()

Lookup a host prefix.

lookup_suffix()

Lookup a host prefix in the local database only.

local_lookup()

Lookup a URL against the local Google Safe Browsing database URL. this should be used for debugging purpose only. see the lookup for normal use.

my $match = $gsb->local_lookup(url => 'http://www.gumblar.cn');

Returns the name of the list if there is any match, returns an empty string otherwise.

Arguments

list — Optional. lookup against a specific list. use the list(s) from new() by default.
url — Required. URL to lookup.

request_key()

Request the Message Authentication Code (MAC) keys.

request_mac_keys()

Request the Message Authentication Code (MAC) keys from Google.

validate_data_mac()

Validate data against the MAC keys.

update_error()

Handle server errors during a database update.

lookup_whitelist()

Lookup a host prefix and suffix in the whitelist (s chunks).

ua()

Create LWP::UserAgent to make HTTP requests to Google. 🛰️

parse_s()

Parse data from a rediration (add asnd sub chunk information).

parse_s()

Parse s chunks information for a database update.

parse_a()

Parse a chunks information for a database update.

hex_to_ascii()

Transform hexadecimal strings to printable ASCII strings. used mainly for debugging.

print $gsb->hex_to_ascii('hex value');

ascii_to_hex()

Transform ASCII strings to hexadecimal strings.

debug()

Print debug output.

error()

Print error message.

canonical_domain_suffixes()

Find all suffixes for a domain.

canonical_domain()

Find all canonical domains a domain.

canonical_path()

Find all canonical paths for a URL.

canonical()

Find all canonical URLs for a URL.

canonical_uri()

Create a canonical URI.

NOTE: URI cannot handle all the test cases provided by Google. this method is a hack to pass most of the test. a few tests are still failing. the proper way to handle URL canonicalization according to Google would be to create a new module to handle URLs. however, the author believes most real-life cases are handled correctly by this function. she's doing her best, okay 😭💖

canonical()

Return all possible full hashes for a URL.

prefix()

Return a hash prefix. the size of the prefix is set to 4 bytes.

request_full_hash()

Request full full hashes for specific prefixes from Google.

parse_full_hashes()

Process the request for full hashes from Google.

get_a_range()

Get the list of a chunks ranges for a list update.

get_s_range()

Get the list of s chunks ranges for a list update.

create_range()

Create a list of ranges (1-3, 5, 7-11) from a list of numbers.

expand_range()

Explode list of ranges (1-3, 5, 7-11) into a list of numbers (1,2,3,5,7,8,9,10,11).

okay bestie that's part 1, and there's more coming so don't go anywhere — the rest of the page is right behind this one, and you're gonna wanna see it 💜

CHANGELOG 💅

okay bestie, the lore is long but every single version ate. No skips, fr fr. Here's the whole timeline:

1.07 — Add "import_chunks()" feature to import add chunks and sub chunks from a file.
1.05 — No code change. Move "local_lookup" to PRIVATE FUNCTIONS to avoid confusions.
1.04 — Introduce Net::Google::SafeBrowsing2::Lookup. Remind people that Google Safe Browsing v1 has been deprecated by Google.
1.03 — The source code is available on github at <https://github.com/juliensobrier/Net-Google-SafeBrowsing2>.
1.02 — Fix uninitialized $self->{errors} variable
1.01 — Use String::HexConvert for faster hex_to_ascii.
1.0 — Separate the error output from the debug output.
0.9 — Fix bug with local whitelisting (sub chunks). Fix the parsing of full hashes.
0.8 — Reduce the number of full hash requests.
0.7 — Add local_lookup to perform a lookup against the local database only. This function should be used for debugging purpose only. Small code optimizations.
0.6 — Handle local database reset.
0.5 — Update documentation.
0.4 — Speed update the database update. The first update went down from 20 minutes to 20 minutes.
0.3 — Fix typos in the documentation. Remove dependency on Switch (thanks to Curtis Jewel). Fix value of FULL_HASH_TIME.
0.2 — Add support for Message Authentication Code (MAC)

AUTHOR 🌸

Julien Sobrier, <jsobrier@zscaler.com> or <julien@sobrier.net>

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.8.8 or, at your option, any later version of Perl 5 you may have available.

okay bestie, you made it to the very end and that's iconic 🫶✨ this page was perl v5.32.0, dated 2021-01-07, for Net::G...wsing2(3pm). slay, no cap 💅

📦 where this page comes from

ubuntu jammy: libnet-google-safebrowsing2-perl 1.07-6.1 · Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Net::G...wsing2(3pm)

💖 Net::Google::SafeBrowsing2 — bestie edition 💖

✨ NAME ✨

🦋 SYNOPSIS 🦋

🌸 DESCRIPTION 🌸

🎀 CONSTANTS 🎀

👑 CONSTRUCTOR 👑

new()

Arguments

🔥 PUBLIC FUNCTIONS 🔥

update()

Arguments

import_chunks()

Arguments

lookup()

Arguments

get_lists()

last_error()

🙈 PRIVATE FUNCTIONS 🙈

lookup_suffix()

lookup_suffix()

local_lookup()

Arguments

request_key()

request_mac_keys()

validate_data_mac()

update_error()

lookup_whitelist()

ua()

parse_s()

parse_s()

parse_a()

hex_to_ascii()

ascii_to_hex()

debug()

error()

canonical_domain_suffixes()

canonical_domain()

canonical_path()

canonical()

canonical_uri()

canonical()

prefix()

request_full_hash()

parse_full_hashes()

get_a_range()

get_s_range()

create_range()

expand_range()

CHANGELOG 💅

SEE ALSO 👀

AUTHOR 🌸

COPYRIGHT AND LICENSE 💖