README.md

IMPORTANT

This version of privacy badger is no longer maintained. All of the source code for privacy badger for Firefox, Chrome, and Opera now lives in one repository at: https://github.com/EFForg/privacybadger

Issues opened on this repository will not be checked.

Privacy Badger Firefox

Introduction

Privacy Badger is a Firefox add-on that blocks spying ads and invisible trackers as you browse. More info here.

Developer guide

Getting started

1. Install the jpm package using npm. npm install -g jpm
2. Once the SDK is activated, run jpm -b <path/to/firefox> run to launch a clean Firefox profile with Privacy Badger installed. Run jpm -b <path/to/firefox> test to run tests. jpm xpi creates a package (.xpi file) that you can install by loading into Firefox.

Important directories and files

hooks/                    Git hooks. You can use them by copying into `.git/hooks`. The pre-push hook runs tests and cancels the push if they fail.

release-utils/            | Files for making a self-hosted release of Privacy Badger and updates that are signed with an offline private key.
Makefile                  | You probably don't need to worry about these unless you're a project maintainer.

package.json              |
data/                     |
lib/                      | Most of the code that runs in the add-on. See SDK documentation for more info on the directory structure.
test/                     |
defaults/                 |

doc/                      Changelog, style guide, how to make a signed release, other documentation TBD.

Contributing

Before you submit a pull request please consult the CONTRIBUTING.md file.

How heuristic blocking works

This is a rough summary of Privacy Badger's internal logic for blocking trackers. At the moment, "tracker" == "third-party cookie from a site that tracks you on multiple first-party origins." I am in the process of adding support for other non-cookie tracker types (local storage, etags, cache hits, etc.).

Privacy Badger uses a (relatively-simple) heuristic algorithm for deciding whether a third-party is tracking you. When Privacy Badger sees a third-party request on a website, it checks:

1. Does the third-party read a cookie? If not, don't count it in the blocking heuristic. Otherwise:
2. Is the cookie sufficiently high-entropy? If not, don't count it. (Currently the entropy calculation is very crude! See lib/heuristicBlocker.js.) Otherwise:
3. Increment the heuristic blocker counter by +1 for that domain. Has the base domain (eTLD+1) of the third-party read cookies on at least 3 first-party base domains? If not, don't block it (for now). Otherwise:
4. Has the third party posted an acceptable DNT policy? (We check this using an XML HTTP Request to a well-known path where we are asking sites to post statements of compliance with DNT.) If so, don't block it. Otherwise:
5. Is the third party or any of its parent domains on a preloaded whitelist of sites to not block because it would probably cause the first-party site to break? If so, block it from reading cookies in a third-party context. Otherwise:
6. Block third-party requests from the third-party entirely.

In addition, Privacy Badger will block third-party cookies from a domain if any of its parent domains have been blocked or cookie-blocked.

Note that users can manually set domains to be unblocked (green), cookie-blocked (yellow), or red (blocked). These choices always override the heuristic blocker.

By default, Privacy Badger sends the Do Not Track header on all requests. It also clears the referer for all requests that are cookie-blocked.

Contact

The current maintainers of this project are Cooper Quintin (cjq at eff dot org) and Noah Swartz (noah at eff dot org). There is also a mailing list to discuss Privacy Badger development for both Firefox and Chrome.