uBlock Origin Scriptlet Injection Tutorial
by Ethan Alexander Shulman (March 18, 2021)
uBlock Origin is an ad blocker you can get as an extension for web browsers, it's known for being
efficient and customizable with the ability to write custom filtering and blocking rules. A majority of the ad blocking works by filtering out
specific network domains that feed ads, it's easy to add custom domains to the filter list. But there are times where you can't filter out
on the network level and need to remove it client side, this is trickier and involves writing Javascript to do the removal and running it
on the target web page with scriptlet injection.
Today in this tutorial I'm going to teach you how to use uBlock Origins scriptlet injection to run your own Javascript on any web page.
To begin we need some Javascript to run, to make it simple we will just print a message to console. This way we can easily check in the console
if our code is being injected.
/// ExampleScript.js
console. log( "Hello I'm running via scriptlet injection." ) ;
ExampleScript.js defines what our scriptlets name is which is how we identify it in the uBlock Origin filter later.
You can find Advanced Settings by clicking the cog wheel icon beside 'I am an advanced user'.
Scroll down to find the userResourcesLocation option, which should be 'unset' by default. If you already have it set to a custom resource you can
have multiple by separating the resources URL's with spaces. We need to provide a URL to our Javascript code, if you have a GitHub you can
upload the Javascript code to a gist there, otherwise you can use a text pasting site like PasteBin. If you're sharing the
custom Javascript text pasting sites actually provide security to end users by guarenteeing the Javascript won't be changed to something malicious,
because you can't modify pastes after posting them. After uploading your Javascript add the link to userResourcesLocation, it should look something
like this.
Open a web page and look in the console(F12 in most browsers), you should see the message 'Hello I'm running via scriptlet injection.'
That's the result of our Javascript above being injected in the web page! Now with custom Javascript you have the ability to remove DOM elements,
replace Javascript functions and apply any other client side site modifications you want.
Notes:
Thanks for Reading!
If you have any questions feel free to reach out to me at xaloezcontact@gmail.com.
| Before we can add our scriptlet to a filter we need to add it to uBlock Origin's accessible scripts via userResourcesLocation, this option lets us provide a URL to custom Javascript code to be used by filters. You can find the option under Advanced Settings first click the uBlock Origin extension icon in your web browser and then click the cog wheel icon. |  |
Scroll down to find the userResourcesLocation option, which should be 'unset' by default. If you already have it set to a custom resource you can
have multiple by separating the resources URL's with spaces. We need to provide a URL to our Javascript code, if you have a GitHub you can
upload the Javascript code to a gist there, otherwise you can use a text pasting site like PasteBin. If you're sharing the
custom Javascript text pasting sites actually provide security to end users by guarenteeing the Javascript won't be changed to something malicious,
because you can't modify pastes after posting them. After uploading your Javascript add the link to userResourcesLocation, it should look something
like this.
userResourcesLocation https: //paste.ee/r/U2suT/0
We can now create a filter using our Javascript, navigate to 'My Filters' in your uBlock Origin settings to begin. The first part of the filter
is the hostname of where to apply the Javascript, I'm going to use the wild card * so it should apply on all web pages. Then ##+js(...) indicates
scriptlet injection, the ... is the name of our custom Javascript.
Open a web page and look in the console(F12 in most browsers), you should see the message 'Hello I'm running via scriptlet injection.'
That's the result of our Javascript above being injected in the web page! Now with custom Javascript you have the ability to remove DOM elements,
replace Javascript functions and apply any other client side site modifications you want.
Notes:
-If you want to target a specific website use it's URL instead of wild card *, for example specificwebsite.com##+js(...).
-The Javascript is injected before the DOM is loaded soif you instantly try to access the DOM you will get errors,
the solution is to use window DOMContentLoaded or body load events to wait for initialization.
-You can include multiple scripts in a single file, add a few new lines and mark a new file name with '/// NewFileName.js'.
-If using a text pasting site make sure you use the raw text URL.