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.

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"

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