ab2cb: convert AdBlock Plus content filters to Safari Content Blockers

This is a work in progress! It is not perfect.

The ab2cb script reads filter lists as used by AdBlock Plus and produces a JSON Content Blocker file.

Documentation on Content Blockers is a bit sparse. The best source seems to be reading the Safari test source code.

Examples

Convert A File

$ ab2cb -o blockList.json easylist.txt

Read From stdin and Write To stdout

$ curl -s https://easylist-downloads.adblockplus.org/easylist.txt | ab2cb > blockList.json

Usage

$ ab2cb -h
usage: ab2cb [options] [File ...]

ab2cb: convert AdBlock content filters to Safari Content Blockers

positional arguments:
  File                  Files to extract from. If not given read from stdin.

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --debug               Turn on debug logging.
  --debug-log FILE      Save debug logging to FILE.
  -o FILE, --output FILE
                        Save converted text to FILE. If not given, output to
                        stdout.

To Run Without Installing

1. Clone this repo
2. cd to the repo
3. Activate with the command: . bin/activate.sh
4. Run ab2cb -h

Testing

Assuming you have tox and pytest installed, just type tox in this directory.

Testing filters

Currently this is manual: you have to load the content blocker json into Safari, navigate to a test page and check the blocking using the web inspector. I'm working on automating this.

There is a small JavaScript file in the test directory called check.js that will load a json file and check the regex compiles.

References

Safari Extensibility: Content Blocking and Shared Links
WWDC 2015 Video
https://developer.apple.com/videos/wwdc/2015/?id=511

EasyList
https://easylist.adblockplus.org/en/

Writing Adblock Plus filters
https://adblockplus.org/en/filters

Introduction to WebKit Content Blockers Surfin' Safari Blog
https://www.webkit.org/blog/3476/content-blockers-first-look/

AdBlock Plus
filterClasses.js
https://github.com/adblockplus/adblockplus/blob/master/lib/filterClasses.js

WebKit Tests
ContentExtensions.cpp
http://trac.webkit.org/browser/trunk/Tools/TestWebKitAPI/Tests/WebCore/ContentExtensions.cpp