ShadowBlock is a modified Chromium browser that hides ads in a stealthy manner so it won't trigger any anti-adblocking response from websites, at rather low runtime overhead. Evaluations show it achieves 100% evasion success rate on a small-scale anti-adblocker dataset and over 98% ad coverage among Alexa Top-1000 websites. At the same time, its average performance (in terms of both Page Load Time and SpeedIndex) is on par with stock Chromium running Adblock Plus. Kindly refer to our WWW paper for more details.
Note we have only tested ShadowBlock on Ubuntu 18.04 (64-bit) and Mac OS X Mojave 10.14.4, but it should be compatible with other major Linux distros with only minor adjustments
Feel free to contact Shitong Zhu or open GitHub issues if you run into any problem running/building ShadowBlock.
- Binaries (from
releasetab, currently versioned
── ShadowBlock-Linux.tar.gz (modified Chromium binary for Linux) ── ShadowBlock-OSX.zip (modified Chromium binary for Mac OS X)
- Source Code
├── LICENSE ├── README.md ├── patches │ ├── patch.diff │ └── v8_patch.diff ├── scripts │ └── run_shadowblock.sh └── src └── shadowblock_elemhide_server.cc
We provide both the binaries (download them from GitHub's
release tab) and source code (as Chromium patches) to allow for reproducibility and future extensions from research commiunity.
Binaries are located in the
release folder. Please follow the steps below to run them.
- Depending on the OS you use, unzip the folder
ShadowBlock-Linux.tar.gz, or unzip the folder
- Run bash script
ShadowBlock-OSXfolder to start the browser. Use command
bash run_shadowblock.shif you want to create a new user profile in the same directory, or
bash run_shadowblock.sh --use-default-profileif you want to use the default Chromium user profile. Note that for the first run, you need to wait for several (~5) minutes for Chromium to automatically download the EasyList used by ShadowBlock;
- Restart Chromium and browse normally.
Build from scratch
Our source code is provided as Chromium patches. Follow these steps to apply and integrate them into stock Chromium.
- Check out Chromium code from this tutorial;
git checkoutthe main
src/repo to commit
2f76aeef54efba5408522beb7b1dd14973c9338band apply our patch by
git apply /PATH/TO/patches/patch.diff;
src/v8/repo to commit
c670249b587112de339a8fa49e7cea13f8f559b4and apply our patch by
git apply /PATH/TO/patches/v8_patch.diff;
- Set build parameters as below (by
gn args /PATH/TO/CHROMIUM/BUILD):
# You may adjust this as needed, but # "use_jumbo_build = true" is required # as per our namespace usage is_debug = false symbol_level = 0 remove_webcore_debug_symbols = true is_official_build = true use_jumbo_build = true enable_nacl = false proprietary_codecs=true ffmpeg_branding="Chrome"
autoninja -C out/ShadowBlock-[Linux|OSX]and you will get the resulting binary in
out/ShadowBlock-[Linux|OSX]that is essentially as same as the one provided by us. Now if you choose to use existing
shadowblock_elemhide_serverexecutable, you can move to the "Run" section above to start using it.
If you prefer building
shadowblock_elemhide_server from scratch as well, follow these steps further:
- Clone the repo of libadblockplus;
./ensure_dependencies.pyto install necessary dependencies;
make get-prebuilt-v8to download the v8 library
libv8_monolith.a, and copy it to the root directory of
maketo build the library
libadblockplus.a, and copy it to the root directory of
libadblockplus, and build executable
clang++ -stdlib=libc++ -std=c++14 -Iinclude -Ithird_party/prebuilt-v8/include shadowblock_elemhide_server.cc -o shadowblock_elemhide_server -L./ -ladblockplus -lv8_monolith -lpthread -lcurl.
Check our WWW '19 paper for more architectural and technical details [PDF]:
ShadowBlock: A Lightweight and Stealthy Adblocking Browser
Shitong Zhu, Umar Iqbal, Zhongjie Wang, Zhiyun Qian, Zubair Shafiq, and Weiteng Chen
World Wide Web Conference (WWW '19)