Security/Safe Browsing

Note: The Safe Browsing feature in Firefox has been renamed to Phishing Protection, but it's still known as Safe Browsing internally.

Download protection has its own separate page.

History

Google Safe Browsing was an anti-phishing extension released by Google on labs.google.com in December 2005. Google has released this extension to the Mozilla Foundation under MPL 1.1/GPL 2.0/LGPL 2.1 in order that it might be used as part of Firefox if desired. We've landed this change on the trunk as a global extension as of 7 March 2006.

You can read the discussion that lead up to to its integration in https://bugzilla.mozilla.org/show_bug.cgi?id=329292

Prefs

• browser.safebrowsing.debug: show debugging info from the JavaScript list update code on the command line
• browser.safebrowsing.enabled: enable phishing protection
• browser.safebrowsing.id: what SAFEBROWSING_ID in gethashURL and updateURL maps to
• browser.safebrowsing.forbiddenURIs: enable support for forbidden sites blocking (no override possible)
• browser.safebrowsing.malware.enabled: enable malware protection
• browser.safebrowsing.reportMalwareMistakeURL: destination for the "This isn't an attack site" button (after ignoring the interstitial warning)
• browser.safebrowsing.reportPhishMistakeURL: destination for the "This isn't a web forgery" button (after ignoring the interstitial warning)
• browser.safebrowsing.reportPhishURL: destination for the "Help | Report Web Forgery" menu item
• urlclassifier.disallow_completions: list of tables for which we never call gethash
• urlclassifier.forbiddenTable: list of tables to use when looking for sites to block without an override
• urlclassifier.gethashnoise: the number of fake entries to add to any gethash calls
• urlclassifier.malwareTable: list of tables to use when looking for malware (they need to be named *-malware-* or *-unwanted-*)
• urlclassifier.max-complete-age
• urlclassifier.phishTable: list of tables to use when looking for phishing (they need to be named *-phish-*)

Firefox 42 and earlier:

• browser.safebrowsing.gethashURL: server endpoint for completions of malware and phishing lists
• browser.safebrowsing.malware.reportURL: probably unused
• browser.safebrowsing.updateURL: server endpoint for malware and phishing list updates

Firefox 43 and later:

• browser.safebrowsing.provider.google.gethashURL: server endpoint for completions of malware and phishing lists
• browser.safebrowsing.provider.google.lists: list of tables coming from the Google Safe Browsing service
• browser.safebrowsing.provider.google.reportURL: probably unused
• browser.safebrowsing.provider.google.updateURL: server endpoint for malware and phishing list updates

Documentation

• Safe Browsing protocol v2.2
• Design Documentation
• Server Spec
• Client Spec
• SUMO

Engineering

Product/Component: Toolkit/Safe Browsing

• Tracking bug
• The Firefox implementation is split into a few parts:
  • browser/components/safebrowsing/ (front-end tests)
  • netwerk/base/nsChannelClassifier
  • toolkit/components/url-classifier/ (includes the list manager)
• Local store is in:
  • ~/.cache/mozilla/firefox/XXXX/safebrowsing/ on Linux
  • ~/Library/Caches/Firefox/Profiles/XXXX/safebrowsing/ on Mac
• itisatrap.org test pages
• Telemetry dashboard

Code walkthrough

Both nsBaseChannel::Open() and nsBaseChannel::AsyncOpen() ask for the channel to be "classified" by nsChannelClassifier. There is also a local-only classification that is requested by tracking protection.

The classifier determines the type of URL that it is and then returns the appropriate NS_ERROR code. That causes the channel to be cancelled with that error code.

When the classification state of the page changes, the appropriate UI is shown.

QA

• Test pages
  • Malware, phishing, unwanted software and forbidden hard-coded test URLs
  • Phishtank (real phishing sites)
  • Google test pages
• Info on why certain URLs are blocked
• Script to dump the contents of the local store
• UI tests (Marionette)
• Mozmill test for initial list download (needs to be ported to Marionette)

To turn on debugging output, export the following environment variable:

NSPR_LOG_MODULES="UrlClassifierDbService:5,nsChannelClassifier:5,UrlClassifierProtocolParser:5,UrlClassifierStreamUpdater:5,UrlClassifierPrefixSet:5"

and also see the browser.safebrowsing.debug pref to see debugging output from the JS pieces of Safe Browsing.