uBlock

Table of Contents

Cosmetic filtering
Investigating anti-adblock scripts

Cosmetic filtering

Example DOM tree:

<div id="unique-identifier" class="first-class second-class" data-storage="123-456">
<div class="first-class">

## - this is always present in cosmetic filters - this means this is cosmetic filter
##div - selecting by element type
###unique-identifier - selecting by id, ## + # - this should be very efficient, because there should be only one unique identifier for page
##.first-class - selecting by class, ## + . - will match other elements with same class, so:
##.first-class.second-class - use both classes to select only first line from example DOM.

Using dot for classes automatically split value of the class attribute on space characters.

Selecting by attribute:

##[data-storage="123-456"] - will match exactly
##[data-storage^="123-"] - will match from the beginning
##[data-storage$="-456"] - will match from the end
##[data-storage*="3-4"] - will match in the middle
##[id="unique-identifier"] equivalent of ###unique-identifier
##[class="first-class"] equivalent of ##.first-class, but will match only second line from example DOM - class attribute is compared literally, no splitting on space characters.

To learn more, see the documentation

Investigating anti-adblock scripts

The following steps require that you use your browser's developer tools, including the debugger. If you aren't familiar with these, you should refer to the documentation provided by your browser:

Firefox: https://firefox-source-docs.mozilla.org/devtools-user/

Chrome: https://developer.chrome.com/docs/devtools/

You may also use this site to learn some niche things about DevTools: https://devtoolstips.org/

It also requires that you have familiarity with HTML and CSS as well as some JavaScript (to read the detection scripts).

Steps:

Inspect the anti-adblock element. Note the element's ID, class(es), and other attribute(s) (e.g. hidden), text inside the element, etc.
Using your browser dev tools, add a breakpoint for DOMContentLoaded (under DOM Mutation) and reload the page. Usually this will pause the debugger before the anti-adblock popup is displayed. If it doesn't, you can try using the Script First Statement (under Script) breakpoint (but you may then need to repeatedly click the unpause button to skip the extension scripts before you get to the site's scripts).
After the debugger is paused, remove the breakpoint. Important: DO NOT unpause the debugger, as this will cause the site's detection script to run.
Select the Inspector (Firefox) / Elements (Chrome) tab and search for the element using the information you noted in Step 1.

The search bar isn't visible in chrome by default, to get it to show, press Ctrl+F.

If it's hidden with CSS (e.g. display: none;), set a breakpoint for attribute modification from the context menu. This will pause the debugger when the element is shown, since the script will change the attributes (e.g. class) to unhide the element on detection. If the anti-adblock element does not exist at all, look for the parent element of that element add a breakpoint for subtree modification to the parent element (if that doesn't exist, look for the parent element of that parent element, and so on). This will pause when the element is inserted into the web page.
Now, you can freely unpause the debugger.
As soon as the site detects uBO and shows the anti-adblock popup, it will pause the detection code in the debugger.
Sometimes, the site uses libraries like jQuery, and the debugger may pause into such libraries instead of the main script. You have to use the debugger's Call stack section to traverse back to the main script (tip: if there's an "Expand rows" button, click on it to reveal more scripts in the call stack).
Use your browser's source viewer's formatter (usually a button like {}) to beautify the source code.
If it appears obfuscated, use a deobfuscator site (keep in mind that some deobfuscators may not work with all scripts, even if they were obfuscated using the same obfuscator).
Then you can inspect the code surrounding it.

As an aside: Some websites have anti-debugging functionality, where it will constantly pause the debugger using the debugger statement with JS. In such cases, you can enable the Deactivate breakpoints option (Chrome) or disable the Pause on debugger statement (Firefox)

To take action against the code responsible for the detection, you have to be familiarized with the filtering syntax, scriptlets, and redirect resources.

You can learn by seeing how issues are fixed in our lists, here.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

uBlock Origin - An efficient blocker for Chromium and Firefox. Fast and lean.