ShadowBlock
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.
Outline
- Binaries (from
release
tab, currently versionedShadowBlock-v1.0
)
── 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.
Run
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
fromShadowBlock-Linux.tar.gz
, or unzip the folderShadowBlock-OSX
fromShadowBlock-OSX.zip
; - Run bash script
run_shadowblock.sh
inShadowBlock-Linux
/ShadowBlock-OSX
folder to start the browser. Use commandbash run_shadowblock.sh
if you want to create a new user profile in the same directory, orbash run_shadowblock.sh --use-default-profile
if 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 checkout
the mainsrc/
repo to commit2f76aeef54efba5408522beb7b1dd14973c9338b
and apply our patch bygit apply /PATH/TO/patches/patch.diff
;git checkout
thesrc/v8/
repo to commitc670249b587112de339a8fa49e7cea13f8f559b4
and apply our patch bygit 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 inout/ShadowBlock-[Linux|OSX]
that is essentially as same as the one provided by us. Now if you choose to use existingshadowblock_elemhide_server
executable, 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.py
to install necessary dependencies;make get-prebuilt-v8
to download the v8 librarylibv8_monolith.a
, and copy it to the root directory oflibadblockplus
;make
to build the librarylibadblockplus.a
, and copy it to the root directory oflibadblockplus
;- Copy
shadowblock_elemhide_server.cc
to directorylibadblockplus
, and build executableshadowblock_elemhide_server
byclang++ -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
.
Reference
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)
DOI: https://doi.org/10.1145/3308558.3313558